# Grantor documentation

**OAuth with no authorization server.** A caller presents a **deed** — a
self-certifying credential it mints itself — and your app verifies it with a
library call against a public on-chain registry. No authorization server
exists in this path: Grantor operates no service, and the trust anchor is a
contract readable from any RPC endpoint.

## The 30-second model

1. Your app issues a **challenge** (the OIDC `nonce` shape — one value, one use).
2. The caller signs or proves against it and returns a **deed**. No redirect, no
   token endpoint, no round trip to anyone.
3. Your app calls `verify_deed`, which checks the cryptography *and* reads the
   on-chain registry: is this tenant paid up, and for agents, is this member
   still un-revoked?
4. You mint your own session however you already do. Grantor never sees it.

Step 3 is a plain `eth_call` — a read. It costs no gas, needs no API key, and
works from any RPC provider.

## Pick your path

| You are… | Start here |
|---|---|
| An **app that needs to authenticate callers** | [Getting started](guide/getting-started.md) |
| Just **trying it out** without spending anything | [Develop locally](guide/local-devnet.md) — a free, disposable local devnet |
| Adding **wallet login** for humans | [Wallet login](guide/wallet-login.md) |
| Adding **passkey login** for humans (closes the wallet-login phishing residual) | [Passkey login](guide/user-passkey.md) |
| Your users hold **smart-contract wallets** (Safe / EIP-1271) | [Smart-wallet login & admin](guide/smart-wallet.md) |
| Building an **AI agent** that needs API access | [Agent tokens](guide/agent-tokens.md) · [Agent integration](agents/README.md) |
| Restricting login to **an admin-curated allowlist**, anonymously | [User gating](guide/user-gating.md) |
| Gating a **remote MCP server** | [MCP server auth](guide/mcp-server.md) |
| Granting **bounded, delegated authority** (not just identity) | [Capabilities](guide/capabilities.md) |
| Licensing software / gating a paid feature | [Software licensing](guide/licensing.md) |
| Operating a tenant and want to detect a **compromised admin key** | [Chain watcher](guide/chain-watcher.md) |
| Wondering **how any of this works** | [Concepts](guide/concepts.md) |
| A **contributor** | [Architecture](internal/architecture.md) · [Contributing](internal/contributing.md) |

## Kinds of deed

| Mode | Who holds it | Proves | On-chain check |
|---|---|---|---|
| `user-sig` | a human with a wallet | control of a wallet-derived, app-scoped key; the app sees a **pseudonym**, not an address | tenant billing status |
| `user-passkey` | a human with a passkey (WebAuthn) | control of a browser-bound P-256 credential; the app sees a **pseudonym** | tenant billing status |
| `user-1271` | a human with a smart-contract wallet (Safe / EIP-1271) | on-chain `isValidSignature` approval; the app sees a **pseudonym**, but one linkable to the wallet's public address — [tradeoff](sovereign-tier.md#the-pseudonymity-tradeoff--read-before-picking-this-mode) | `isValidSignature` (the login itself) + tenant billing status |
| `agent-zk` | an enrolled agent | ZK membership of the tenant's registry **without revealing which member** | membership-root recency (revocation) + billing |
| `user-zk` | a human enrolled in the tenant's own **user allowlist** | ZK membership of that allowlist **without revealing which member**; the app sees a **pseudonym** | membership-root recency (revocation) + billing |
| `admin-sig` | a Grantor dashboard admin (EOA); a Safe / EIP-1271 wallet is supported as a *library* capability, not yet wired into Grantor's own dashboard | control of a wallet address (**identified**, not pseudonymous) | none, deliberately — [why](sovereign-tier.md#dashboard-login-admin-sig) |

All five user/agent modes verify through one call, `verify_deed`; `admin-sig`
has its own entry point that `verify_deed` refuses. Why each mode exists and
when to pick which: [Sovereign tier](sovereign-tier.md#passkey-login-user-passkey),
[User gating](guide/user-gating.md) for `user-zk`.

Everything ships in TypeScript, Python, Go and Rust — parity is CI-enforced.
[The matrix](sovereign-tier.md#every-capability-every-language).

## Reference

- **Concepts:** [the mental model](guide/concepts.md) — read this first.
- **Machine docs:** [`llms.txt`](llms.txt) (index) · [`llms-full.txt`](llms-full.txt) (everything, one file).
- **Every page here is also Markdown** — same URL, `.md` instead of `.html`.
- **Live, per RP deployment:** an app that accepts deeds publishes its own
  `/.well-known/grantor-deed` discovery document and challenge endpoint — see
  [Sovereign tier § Discovery](sovereign-tier.md#discovery-how-an-agent-finds-all-this).

## Guides

- [Concepts](guide/concepts.md) — the mental model
- [Getting started](guide/getting-started.md)
- [Verify a deed](guide/verify-tokens.md) — the relying-party side
- [Wallet login](guide/wallet-login.md) — `user-sig`, for humans
- [Passkey login](guide/user-passkey.md) — `user-passkey`, phishing-resistant browser login for humans
- [Smart-wallet login & admin](guide/smart-wallet.md) — `user-1271` + Safe/EIP-1271 `admin-sig`, for smart-contract wallets
- [Agent tokens](guide/agent-tokens.md) — `agent-zk`, for machines
- [User gating](guide/user-gating.md) — `user-zk`, anonymous login restricted to an admin-curated allowlist
- [MCP server auth](guide/mcp-server.md) — gate a remote MCP server with a deed, no authorization server
- [Capabilities](guide/capabilities.md) — bounded, delegated authority on top of a deed
- [Software licensing](guide/licensing.md) — a license is a deed, no license server, tiers via capability grants
- [Develop locally](guide/local-devnet.md) — a free, disposable local devnet, no production spend
- [Sovereign tier](sovereign-tier.md) — the full deed reference
- [Chain watcher](guide/chain-watcher.md) — an operator sidecar that watches the registry for revocations/billing changes
- [Errors](guide/errors.md)

## Agents (LLM-first)

- [Agent integration](agents/README.md)
- [Agent onboarding](agents/onboarding.md)

## Internal (contributors)

- [Architecture](internal/architecture.md)
- [Code map](internal/crates.md)
- [Security model](internal/security-model.md)
- [Testing](internal/testing.md)
- [Contributing](internal/contributing.md)

---

**Status: developer preview.** The contract and the full six-language
end-to-end proof run on a local devnet (anvil). It has **not** been deployed to
a public testnet or mainnet, and `grantor-verify` is not yet published to any
package registry — today it resolves by path inside this workspace. It has not
been audited. Do not put it in front of production money.

**Licence: proprietary, all rights reserved.** The source is readable — package
registries distribute source — but that is not a grant of rights. You may use
these libraries to integrate with Grantor; you may not fork, redistribute, or
build a competing service with them. Full terms in `LICENSE`; enquiries for
broader terms are welcome.