# 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. There is no auth server to
run, trust, page at 3am, or subpoena. Grantor operates no service in this path;
the trust anchor is a contract anyone can read.

> A grantor is the party that grants a right. A **deed** is the artifact that
> records it. The word is deliberately plain and lowercase, the way *passkey*
> is: Grantor is the brand, a deed is the thing.

## 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** | [Verify a deed](guide/verify-tokens.md) |
| Adding **wallet login** for humans | [Wallet login](guide/wallet-login.md) |
| Building an **AI agent** that needs API access | [Agent tokens](guide/agent-tokens.md) · [Agent integration](agents/README.md) |
| Gating a **remote MCP server** | [MCP server auth](guide/mcp-server.md) |
| Wondering **how any of this works** | [Concepts](guide/concepts.md) |
| A **contributor** | [Architecture](internal/architecture.md) · [Contributing](internal/contributing.md) |

## Three 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 |
| `agent-zk` | an enrolled agent | ZK membership of the tenant's registry **without revealing which member** | membership-root recency (revocation) + billing |
| `admin-sig` | a Grantor dashboard admin | control of a wallet address (**identified**, not pseudonymous) | none, deliberately — [why](sovereign-tier.md#dashboard-login-admin-sig) |

`user-sig` and `agent-zk` both verify through one call, `verify_deed`.
`admin-sig` has its own entry point that `verify_deed` **refuses**, so an
ordinary app cannot accept an admin deed even by mistake.

## Every capability, every language

The product rule is **all languages or no go**: a capability that ships in one
language has not shipped. Enforced by `just capability-matrix`, which inspects
the generated binding surfaces rather than the Rust source.

| | TypeScript | Python | Go | Rust |
|---|---|---|---|---|
| `user-sig` holder (wallet login) | ✅ | ✅ | ✅ | ✅ |
| `agent-zk` holder (ZK proving) | ✅ | ✅ | ✅ | ✅ |
| `admin-sig` holder | ✅ | ✅ | ✅ | ✅ |
| Deed verification (your app's side) | ✅ | ✅ | ✅ | ✅ |
| Deed guard (challenge store + single-use burn) | ✅ | ✅ | ✅ | ✅ |

There is no authorization server in this product — the credential
self-certifies and your app verifies it against the public chain.

## 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
- [Agent tokens](guide/agent-tokens.md) — `agent-zk`, for machines
- [MCP server auth](guide/mcp-server.md) — gate a remote MCP server with a deed, no authorization server
- [Sovereign tier](sovereign-tier.md) — the full deed reference
- [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.