Architecture#

A map for contributors: the polyglot split, the components, the trust flow, both grant flows module-by-module, the on-chain gate + cache, and the client registry seam. For the product-level pitch see docs/index.md; for the full design rationale see docs/superpowers/specs/2026-07-21-passport-web3-oauth-design.md (the "spec"); for a code-level map of each unit see crates.md.

The polyglot split (AD-1)#

On-chain = Solidity (the EVM's native language). Everything off-chain = Rust-first. TypeScript only at the SDK edge (the relying-app SDK, because web apps are JS/TS). — spec §12, AD-1

This is not a style preference, it is the trust boundary:

• On-chain = trust + money. GrantorRegistry (Solidity, contracts/) is the one place that holds value and the one place that says which issuer keys are legitimate. It is deliberately small, immutable where possible, and reviewed like money-handling code (heavy Foundry invariant/fuzz coverage — see contracts/test/GrantorRegistry.invariant.t.sol).
• Off-chain = auth, in Rust. The issuer (grantor-issuer) and the shared verify core (grantor-verify) are Rust. A login never writes to the chain; it only reads the registry. AD-4 picked Poem (poem-openapi) for the issuer's typed HTTP handlers + OpenAPI; AD-5 put JWT verification and the on-chain trust check in one shared Rust crate so there is a single source of truth for what "a valid, trusted Grantor token" means.
• TypeScript only at the edge. The escape hatch for a Rust contract exists (Arbitrum Stylus, spec AD-1) but is not used by default — the default on-chain language stays Solidity. TS shows up only where the runtime forces it: browser wallet interaction (assets/grantor-login.js, viem + WalletConnect) and the future relying-app SDK, which per AD-5 will wrap the same grantor-verify logic compiled to WASM rather than reimplementing it.

Components#

                 reads paid/registered (public RPC, no operator infra)
   ┌───────────────┐ ───────────────────────────────────► ┌──────────────────┐
   │ grantor-         │                                       │ GrantorRegistry    │
   │ issuer (Rust)  │ ◄─────────────────────────────────── │  (Solidity, L2)  │
   │  Poem HTTP     │        isActive / isAgentKey          │  trust anchor +  │
   └───────┬────────┘                                       │  billing         │
           │ mints ES256 JWT                                └──────────────────┘
           ▼                                                       ▲
   end-user / app / agent                                          │ isActive(keyId)
           │                                                       │ (client-side, any RPC)
           ▼ verifies via /jwks + on-chain check                   │
   ┌────────────────────┐                                          │
   │ grantor-verify       │ ─────────────────────────────────────────┘
   │ (Rust; used by the │
   │  issuer directly,  │
   │  → WASM for the    │
   │  TS SDK later)     │
   └────────────────────┘

• contracts/ — GrantorRegistry. The canonical trust anchor and billing engine (contracts/src/GrantorRegistry.sol). Maps an issuer keyId to a tenant, derives tenant Status (Active/Grace/Inactive) from periodEnd/graceWindow/now (never stored stale — status(), GrantorRegistry.sol:95), and exposes the one view the rest of the system depends on: isActive(bytes32 keyId) → bool (GrantorRegistry.sol:105). Also tracks the multiwallet agent-key registry (isAgentKey, a public mapping) and per-tenant usage caps (apps/issuer keys/agents) and a time-boxed free-trial window.
• crates/grantor-verify. Pure, chain-free Rust: verify_jwt (ES256 + exp/aud), issuer_key_id (RFC 7638 JWK thumbprint — the exact [u8; 32] value GrantorRegistry stores as keyId), the TrustSource trait, and verify (JWT check + thumbprint + trust check, composed). No network, no alloy dependency — deliberately, so it can later compile to WASM (AD-5) for the TS relying-app SDK.
• crates/grantor-issuer. The OIDC/OAuth2 issuer: holds the ES256 signing key, publishes /jwks, mints JWTs, and gates every mint on the on-chain check. Depends on grantor-verify (for issuer_key_id, and its unit tests round-trip through verify_jwt) plus alloy (chain reads), poem (HTTP), and siwe (EIP-4361). See crates.md for the module breakdown.

The trust flow#

Every mint and every verification reduces to the same question the registry answers: is this issuer key registered to a tenant that is paid up?

1. Mint side (issuer). Before minting, grantor-issuer calls its TrustGate (crates/grantor-issuer/src/gate.rs), which ultimately reads GrantorRegistry.isActive(keyId) over RPC. keyId is always this issuer's own key (AppState.key.key_id, crates/grantor-issuer/src/state.rs:21). If the tenant isn't Active/Grace, the issuer refuses to mint (403 {"error":"inactive"}).
2. Verify side (relying app). A relying app fetches /jwks (crates/grantor-issuer/src/http/discovery.rs), verifies the JWT signature/claims the standard OIDC way, and — for revocation awareness beyond the token TTL — can independently read isActive(kid) from any public RPC via grantor-verify::verify + a TrustSource impl. No call to any operator-run service is required; the registry is the only shared dependency, and it's public.

The keyId is the hinge: it is simultaneously the JWKS kid (token.rs::IssuerKey::key_id_hex, embedded in the JWT header) and the on-chain registry key (issuerKeyToTenant in GrantorRegistry.sol:52), computed identically on both sides by issuer_key_id (RFC 7638 thumbprint).

Request flow — Grant A (Authorization Code + SIWE, humans)#

Request flow — Grant C (Client Credentials, agents)#

Both flows pause at exactly one shared checkpoint — TrustGate::is_active — where billing, revocation, and the freeloader-fork defense all live (spec §5).

The on-chain gate + cache#

TrustGate (trait, gate.rs)           — object-safe async trait: is_active, is_agent_key
  └─ ChainGate (production impl)     — gate.rs
       ├─ is_active  → CachedIsActive<AlloyReader, SystemClock>   (cache.rs)
       │                    └─ AlloyReader::is_active              (chain.rs)
       └─ is_agent_key → AlloyReader::is_agent_key (uncached)       (chain.rs)

• AlloyReader (crates/grantor-issuer/src/chain.rs) wraps an RPC URL + registry address and calls GrantorRegistry through alloy's sol! bindings (isActive(bytes32), isAgentKey(uint256,address)). It is async by nature (an RPC round-trip), which is why it's a distinct type from the synchronous grantor_verify::TrustSource.
• CachedIsActive<S, C> (cache.rs) wraps is_active reads with a short-TTL cache and the fail-closed semantics from spec §10: a fresh hit is served without an RPC call (bounding revocation latency to ttl_secs); on a transient RPC failure it serves the last good value while within staleness_secs; past that bound (or with no cached value at all) it fails closed — returns false, i.e. "not trusted." Clock is injectable (SystemClock in production) so this is unit-tested without a live chain.
• ChainGate (gate.rs) is the production TrustGate: is_active goes through CachedIsActive; is_agent_key is read live, uncached, because agent-key registration changes at admin-tx frequency, not per-login frequency. Both readers share one underlying RPC/registry (AlloyReader is Clone).
• gate.rs's own test (is_active_fails_closed_when_rpc_is_down) exercises the cold-cache + RPC-down case end-to-end through ChainGate.

The client registry seam (ClientStore)#

crates/grantor-issuer/src/clients.rs defines a second, deliberately off-chain allowlist: which relying-app client_id → redirect_uris (Grant A) and which resource audiences (Grant C) this issuer will actually issue tokens for.

pub trait ClientStore: Send + Sync {
    fn is_valid_redirect(&self, client_id: &str, redirect_uri: &str) -> bool;
    fn is_allowed_audience(&self, audience: &str) -> bool;
}

Why off-chain: GrantorRegistry.registerApp only counts apps toward a tier's usage cap (GrantorRegistry.sol:261) — it never stores redirect URIs or audience strings. Exact-match redirect/audience validation is what closes the open-redirect and audience-spoofing gaps (see docs/superpowers/specs/2026-07-22-passport-client-registry-design.md), and that's a lookup problem, not a trust/money problem, so there's no reason to pay gas for it or route it through the chain's block-time latency.

FileClientStore is the only implementation today: it loads a TOML file (CLIENTS_FILE) at startup and is fail-closed — main.rs propagates FileClientStore::load's error with ?, so a missing or malformed file refuses to boot rather than booting with an empty (or worse, permissive) allowlist. Being behind a trait is the point: a hosted, multi-tenant service can later swap in a DbClientStore without touching any HTTP handler. (Known current limitation, tracked in the build ledger: the registry is global per issuer process — correct for today's single-tenant deploy, but it will need to become tenant-scoped for a future hosted service.)

See also#

• crates.md — per-module code map (what/API/depends-on) for every unit named above.
• docs/guide/concepts.md — the product-facing mental model (same trust flow, written for integrators rather than contributors).
• docs/llms-full.txt — the full machine reference (endpoints, claims, error codes, config).