@agentidentitytrustprotocol/aitp 0.9.0 → 0.11.0

package/index.d.ts

@@ -1,165 +1,248 @@
-/* tslint:disable */
-/* eslint-disable */
-
 /* auto-generated by NAPI-RS */
+/* eslint-disable */
+/** An AITP agent: a signing key and (once built) its Manifest. */
+export declare class AitpAgent {
+  /**
+   * Generate an agent with a fresh random signing key.
+   *
+   * `opts.suite` selects the algorithm — `"ed25519"` (default) or
+   * `"p256"`. Symmetric with the Python SDK's
+   * `AitpAgent.generate(suite="ed25519")`.
+   *
+   * ```ts
+   * const ed = AitpAgent.generate();                       // Ed25519
+   * const p  = AitpAgent.generate({ suite: 'p256' });      // P-256
+   * ```
+   */
+  static generate(opts?: GenerateOpts | undefined | null): AitpAgent
+  /**
+   * Construct an agent from a 32-byte seed (deterministic).
+   *
+   * `opts.suite` matches `AitpAgent.generate`. For `"p256"`, a tiny
+   * fraction of 32-byte seeds are not valid private scalars (zero
+   * or ≥ curve order) and raise.
+   *
+   * Note: the prior `AitpAgent.fromP256Seed` factory and the
+   * no-arg `AitpAgent.generate*` variants were removed in favor of
+   * this parameterized API so the Node SDK matches the Python SDK
+   * surface (CLAUDE.md mandates SDK symmetry).
+   */
+  static fromSeed(seed: Buffer, opts?: GenerateOpts | undefined | null): AitpAgent
+  /** The agent's AID string (`aid:pubkey:...`). */
+  get aid(): string
+  /**
+   * Build and sign the agent's Manifest. Returns `ManifestEnvelope`
+   * JSON and caches the Manifest for `newSession` / `newResponder`.
+   *
+   * See `ManifestOpts.identityType` for the OIDC switch.
+   */
+  buildManifest(opts: ManifestOpts): string
+  /**
+   * Create a new outbound (initiator) handshake session.
+   *
+   * `jwks` is an optional `JwksProvider` used when the peer's
+   * manifest advertises an OIDC identity. `opts.trustAnchors`
+   * overrides the manifest's `accepted_trust_anchors`.
+   */
+  newSession(jwks?: JwksProvider | undefined | null, opts?: SessionOpts | undefined | null): JsInitiatorSession
+  /**
+   * Create a new inbound (responder) handshake session. Mirror of
+   * `newSession`.
+   */
+  newResponder(jwks?: JwksProvider | undefined | null, opts?: SessionOpts | undefined | null): JsResponderSession
+  /**
+   * Verify a compact-JWS TCT token and require `requiredGrant`.
+   * Rejects on an invalid, mis-audienced, expired, revoked, or
+   * under-scoped TCT.
+   *
+   * `expectedAudience` defaults to `null`, which means "verify as the
+   * holder" (RFC-AITP-0005 §9 receipt model — `this.aid` is used).
+   * Resource servers verifying a TCT presented by a peer should pass
+   * the TCT's own `aud` claim as `expectedAudience` (in v0.2 this
+   * equals `sub`).
+   *
+   * `revokedJtis` (F-1) is an optional list of revoked TCT `jti`
+   * strings; any TCT whose `jti` is in the list is rejected even if
+   * otherwise valid. Omit (or pass `null`) to disable the revocation
+   * gate. The caller is responsible for sourcing the revoked set (e.g.
+   * from a `RevocationList` it fetched and verified).
+   */
+  verifyTct(tctToken: string, requiredGrant: string, expectedAudience?: string | undefined | null, revokedJtis?: Array<string> | undefined | null): JsTctIdentity
+  /**
+   * Like `verifyTct`, but consults a `TctStore` first: a byte-identical,
+   * already-verified, still-valid TCT skips the signature check (the
+   * verification hot path for an agent that sees the same TCT on many
+   * requests). All cheap policy checks (expiry, audience, required grant,
+   * and the optional `revokedJtis` gate) still run on every call; only the
+   * signature check is elided.
+   */
+  verifyTctCached(tctToken: string, requiredGrant: string, store: JsTctStore, expectedAudience?: string | undefined | null, revokedJtis?: Array<string> | undefined | null): JsTctIdentity
+  /**
+   * Build a delegation compact-JWS token from a held **grant voucher**
+   * (RFC-AITP-0006). `voucherToken` is the `grantVoucher` surfaced by
+   * `complete()` / `processCommit()`. The delegatee's key binding is
+   * derived from `delegateeAid` itself, so no separate public-key
+   * argument is needed in v0.2.
+   */
+  buildDelegation(voucherToken: string, delegateeAid: string, scope: Array<string>, ttlSecs?: number | undefined | null): string
+  /**
+   * Mint a fresh compact-JWS TCT for a delegatee after the verifier has
+   * confirmed the delegation. The subject-key binding is derived from
+   * the verified delegation's `delegatee` AID.
+   */
+  issueTctForDelegatee(verified: JsDelegationVerified, ttlSecs?: number | undefined | null): string
+  /**
+   * Sign a `RevocationList` with this agent's key. `entries` carries
+   * the revoked-TCT records; `expiresInSecs` defaults to 3600 s.
+   * Returns the on-wire `RevocationListEnvelope` JSON.
+   */
+  signRevocationList(entries: Array<RevocationEntryInput>, expiresInSecs?: number | undefined | null): string
+  /**
+   * Holder side: build a `TctRenewalPayload` JSON for an in-band
+   * renewal of `currentTctToken` — the holder's current TCT as a
+   * compact-JWS string (RFC-AITP-0013).
+   *
+   * Behind the `renewal` Cargo feature, which is **on by default**; a
+   * `--no-default-features` build omits it.
+   */
+  buildRenewalRequest(currentTctToken: string): string
+  /**
+   * Issuer side: verify a `TctRenewalPayload` JSON request and mint a
+   * fresh TCT, returned as a compact-JWS token string.
+   *
+   * Behind the `renewal` Cargo feature (on by default).
+   */
+  processRenewalRequest(requestPayloadJson: string, manifestExpUnixSecs: number, newTtlSecs: number): string
+}
 
-/**
- * Input shape for `signRevocationList`. Field names map to spec
- * `RevocationEntry` (jti, revoked_at, reason).
- */
-export interface RevocationEntryInput {
-  /** JTI of the revoked TCT (UUID string). */
-  jti: string
+/** Outbound handshake session — drives the initiator side. */
+export declare class JsInitiatorSession {
   /**
-   * Unix seconds when the issuing peer revoked the TCT.
-   * Defaults to the current time when omitted.
+   * Step 1 — build the `MUTUAL_HELLO` envelope.
+   *
+   * `oidcMintJwt`: required for OIDC agents. Receives the handshake-
+   * generated `pop_nonce` (string) and must return the JWT (string).
    */
-  revokedAt?: number
-  /** Optional human-readable reason. Not used in trust decisions. */
-  reason?: string
+  buildHello(peerManifestJson: string, requestedGrants: Array<string>, oidcMintJwt?: ((arg: string) => string) | undefined | null): string
+  /** Step 2 — process `MUTUAL_HELLO_ACK`, produce `MUTUAL_COMMIT`. */
+  processHelloAck(helloAckJson: string, sessionId: string): string
+  /**
+   * Step 3 — process `MUTUAL_COMMIT_ACK`. Returns the completed
+   * handshake: the TCT the peer issued to us (opaque compact-JWS
+   * token plus its decoded claims) and the optional grant voucher.
+   */
+  complete(commitAckJson: string): JsCompletedHandshake
 }
-/** Options for `buildManifest`. */
-export interface ManifestOpts {
-  /** Human-readable agent name; also the pinned-key identity subject. */
-  displayName: string
-  /** Absolute URL of this agent's handshake endpoint. */
-  handshakeEndpoint: string
-  /** Capabilities this agent offers to peers. */
-  offeredCaps: Array<string>
-  /** Capabilities a peer must grant back (optional). */
-  requiredCaps?: Array<string>
-  /** Manifest TTL in seconds (optional; defaults to 3600). */
-  ttlSecs?: number
-  /** Identity presentation type — `"pinned_key"` (default) or `"oidc"`. */
-  identityType?: string
-  /** OIDC issuer URL (required when `identityType="oidc"`). */
-  oidcIssuer?: string
-  /** OIDC subject identifier (required when `identityType="oidc"`). */
-  oidcSubject?: string
+
+/** Inbound handshake session — drives the responder side. */
+export declare class JsResponderSession {
   /**
-   * Override the manifest's accepted_trust_anchors list. Defaults to
-   * `[oidc_issuer]` for OIDC mode and `[]` for pinned-key mode.
+   * Process an incoming `MUTUAL_HELLO` envelope.
+   *
+   * `oidcMintJwt`: required for OIDC agents (see `JsInitiatorSession.buildHello`).
    */
-  acceptedTrustAnchors?: Array<string>
+  processHello(helloJson: string, oidcMintJwt?: ((arg: string) => string) | undefined | null): JsHelloAckResult
+  /** Process an incoming `MUTUAL_COMMIT` envelope. */
+  processCommit(commitJson: string): JsCommitAckResult
 }
+
 /**
- * Trust-anchor override for `newSession` / `newResponder`.
+ * In-memory OIDC JWKS provider — issuer URL → list of JWK objects.
  *
- * JWKS provider is passed as a separate argument (napi-rs can't put a
- * class reference inside an `#[napi(object)]` struct).
+ * The Node caller fetches the JWKS (the SDK has no HTTP client) and
+ * hands the parsed objects to this provider. Implements `JwksResolver`
+ * internally so the handshake state machine can dispatch through it.
  */
-export interface SessionOpts {
+export declare class JwksProvider {
   /**
-   * Override the agent manifest's accepted_trust_anchors. `null`
-   * reuses the manifest's list.
+   * Construct from an object mapping issuer URLs to arrays of JWK
+   * objects. Each JWK must be a standard RFC 7517 representation
+   * (`kty`, `crv`, `x`, ...). Pass `{}` for an empty provider and
+   * `upsert` later.
    */
-  trustAnchors?: Array<string>
+  constructor(keys?: unknown | undefined | null)
+  /**
+   * Add or replace the JWKs for an issuer. `keys` is a JS array of
+   * JWK objects.
+   */
+  upsert(issuer: string, keys: unknown): void
+  /** Drop all keys for an issuer. */
+  remove(issuer: string): void
+  /** Return the issuer URLs currently registered. */
+  issuers(): Array<string>
 }
+
 /**
- * Options for `AitpAgent.generate` and `AitpAgent.fromSeed`.
+ * Fluent builder for issuing a `SessionBundleEnvelope`. Constructed
+ * from the coordinator's `AitpAgent`.
  *
- * Mirrors the Python SDK's `suite="ed25519"|"p256"` keyword argument so
- * the two SDKs share one shape per operation. `null`/omitted defaults
- * to `"ed25519"`.
+ * The Rust struct is suffixed `Js` to avoid a name collision with the
+ * `aitp_session_bundle::SessionBundleBuilder` imported above; the
+ * `#[napi(js_name)]` attribute exposes it to JavaScript under the
+ * plain name `SessionBundleBuilder` for parity with the Python SDK.
  */
-export interface GenerateOpts {
+export declare class SessionBundleBuilder {
+  /** Construct a builder backed by `coordinator`'s signing key. */
+  constructor(coordinator: AitpAgent)
+  /** Set the session ID (UUIDv4 string). Defaults to a fresh one. */
+  sessionId(uuidStr: string): this
+  /** Override `issued_at` (unix seconds). Defaults to "now" at build. */
+  issuedAt(unixSecs: number): this
   /**
-   * Signing suite. Accepted values: `"ed25519"` (default) or
-   * `"p256"` (RFC-AITP-0001 §5.4.3).
+   * Add a participant entry. `tctToken` is the participant's TCT as an
+   * opaque compact-JWS string (the `tct` field returned by `complete()`
+   * / `processCommit()`), carried into the bundle verbatim.
    */
-  suite?: string
-}
-/**
- * Outcome shape returned by `verifySessionBundle`. `kind` is `"clear"`
- * or `"degraded"`; `droppedAids` is empty in the `"clear"` case.
- */
-export interface JsBundleOutcome {
-  kind: string
-  activeAids: Array<string>
-  droppedAids: Array<string>
+  participant(aid: string, tctToken: string): this
+  /** Construct, sign, and return the `SessionBundleEnvelope` JSON. */
+  build(): string
 }
+export type SessionBundleBuilderJs = SessionBundleBuilder
+
 /**
- * Verify a `SessionBundleEnvelope` JSON. `nowUnixSecs` defaults to
- * the system clock. `revocationCheck` receives a JTI string and
- * returns true if revoked.
- */
-export declare function verifySessionBundle(bundleEnvelopeJson: string, verifierAid: string, nowUnixSecs?: number | undefined | null, revocationCheck?: (...args: any[]) => any | undefined | null): JsBundleOutcome
-/**
- * The verified delegation's salient fields. Returned from
- * `verifyDelegation` and consumed by `AitpAgent.issueTctForDelegatee`.
+ * Holds a list of 32-byte SPKI pins. `isPinned(certDer)` returns true
+ * iff the cert's SPKI hash is in the list.
  */
-export interface JsDelegationVerified {
+export declare class SpkiPinVerifier {
   /**
-   * AID of the ultimate grantor (the original TCT issuer that gave
-   * grants to `issuedBy`). Equal to the delegation's `aud` and to the
-   * embedded voucher's `iss`. The responder side checks this matches
-   * its own AID before redeeming.
+   * Construct from an array of 32-byte Buffers. Throws if any pin is
+   * not exactly 32 bytes.
    */
-  delegator: string
-  /** AID of the recipient (C) — who will receive a fresh TCT (`sub`). */
-  delegatee: string
-  /** AID of the agent that issued this delegation (B in the RFC) (`iss`). */
-  issuedBy: string
-  /**
-   * Capabilities being delegated (`scope`). Always a subset of the
-   * root voucher's grants.
-   */
-  grants: Array<string>
-  /** Unix-seconds expiry of the delegation token itself (`exp`). */
-  expiresAt: number
-  /**
-   * RFC 7638 JWK thumbprint of the delegatee's key (`cnf.jkt`). In
-   * v0.2 this is derived from — and must match — the key encoded in
-   * `delegatee`'s AID; the fresh TCT's key binding is taken from the
-   * AID, not from this field.
-   */
-  cnfJkt: string
+  constructor(pins: Array<Buffer>)
+  /** Returns true iff the SPKI hash of `certDer` is in the pin list. */
+  isPinned(certDer: Buffer): boolean
+  /** Number of pins currently held. */
+  get len(): number
 }
+
 /**
- * Verify a delegation compact JWS under **strict AITP v0.2**
- * (RFC-AITP-0006 single-hop). `verifierAid` is the verifier's own AID
- * string — it MUST equal the delegation's `aud` (the root grantor), and
- * the embedded voucher MUST verify under the verifier's own key.
- *
- * Any token carrying a non-empty `chain` (an RFC-AITP-0011 multi-hop
- * delegation) is **rejected** with `DELEGATION_MULTIHOP_NOT_SUPPORTED`,
- * matching the Rust core default. To allow multi-hop chains, call
- * `verifyDelegationMultihop` instead.
- *
- * `revokedJtis` is an optional list of revoked `jti` strings — the
- * verifier's own deny list. When non-empty, a token whose
- * `voucher.src_jti` is in it is rejected after every signature check passes
- * (RFC-AITP-0006 §4 step 7, ordered per RFC-AITP-0008 §3.3). **Verifiers
- * SHOULD supply it.** Omitting it silently redeems a delegation whose
- * source TCT has been revoked, which step 7 states as a MUST-reject.
- */
-export declare function verifyDelegation(token: string, verifierAid: string, revokedJtis?: Array<string> | undefined | null): JsDelegationVerified
-/**
- * Verify a delegation compact JWS allowing **RFC-AITP-0011 multi-hop**
- * chains up to `maxDelegationHops` total hops (`chain.length + 1`).
- *
- * The strict single-hop `verifyDelegation` is the safe default; this
- * function additionally allows multi-hop chains. Present by default (the
- * `multihop-delegation` feature); a `--no-default-features` build omits it.
- *
- * `maxDelegationHops` defaults to `DEFAULT_MAX_DELEGATION_HOPS` (3, the RFC-AITP-0011 §2
- * recommended ceiling). Pass a smaller value for a tighter bound;
- * `maxDelegationHops = 0` reverts to strict single-hop (rejects any non-empty chain).
+ * A bounded, in-memory cache of **successful** TCT verifications, keyed by
+ * the SHA-256 of the exact compact-JWS TCT token bytes.
  *
- * `revokedJtis`, when non-empty, is consulted twice — both only after every
- * signature check: once for the root `voucher.src_jti` (RFC-AITP-0006 §4
- * step 7), and once for every hop's `jti`, meaning each chain entry and the
- * outer token (RFC-AITP-0011 §6). Both are MUST-rejects, and a revoked hop
- * invalidates every hop downstream of it — there is no partial-validity
- * model.
+ * Purpose: a high-throughput verifier (e.g. a writer agent checking a
+ * capability on every request) that repeatedly sees the *same* TCT can skip
+ * the Ed25519/P-256 signature verification after the first time.
  *
- * Note that §6 specifies each hop `jti` be checked against the deny list of
- * *that hop's issuer*, which one flat list cannot express, so it is applied
- * to every hop regardless of issuer. That can only reject more, never
- * accept a revoked hop, but it does mean a list aggregated across several
- * issuers lets any contributor revoke any hop.
+ * **Safety.** The key is a cryptographic hash of the exact signed bytes, so
+ * only a byte-identical token — whose signature was already verified once
+ * — can hit. A tampered token hashes differently, misses, and is fully
+ * verified. The cheap policy checks (expiry, audience, required grant) are
+ * re-run on **every** hit; only the signature check is elided. Eviction is
+ * FIFO once `maxEntries` is reached.
  */
-export declare function verifyDelegationMultihop(token: string, verifierAid: string, maxDelegationHops?: number | undefined | null, revokedJtis?: Array<string> | undefined | null): JsDelegationVerified
+export declare class TctStore {
+  /**
+   * Create a cache holding at most `maxEntries` verified TCTs (FIFO
+   * eviction). `maxEntries` must be >= 1.
+   */
+  constructor(maxEntries: number)
+  /** Number of cached verifications currently held. */
+  len(): number
+  /** Drop all cached entries. */
+  clear(): void
+}
+export type JsTctStore = TctStore
+
 /**
  * Compute the RFC 7638 JWK thumbprint of the public key embedded in
  * an AID — the value an OIDC IdP MUST place in the JWT's `cnf.jkt`
@@ -172,65 +255,49 @@ export declare function verifyDelegationMultihop(token: string, verifierAid: str
  * in JavaScript is both error-prone and a divergence risk.
  */
 export declare function computeAidJkt(aid: string): string
+
 /**
  * Compute the SHA-256 SPKI hash for an X.509 DER certificate. Returns
  * a 32-byte Buffer. Throws if `certDer` is not a parseable certificate.
  */
 export declare function computeSpkiHash(certDer: Buffer): Buffer
+
 /**
- * Verify a `RevocationListEnvelope` JSON string against a pinned issuer.
- *
- * Resolves on success; on failure throws an `Error` whose **`code`** property
- * is one of `signature_invalid`, `issuer_mismatch`, `version_unknown`,
- * `expired`, `malformed`. Branch on `error.code`, never on `error.message`:
- * the code is the contract, the message wording is not.
+ * Options for `AitpAgent.generate` and `AitpAgent.fromSeed`.
  *
- * Establishes **authenticity and non-expiry only** — that the snapshot was
- * signed by the holder of `expectedIssuerAid` and that its `expires_at` has
- * not passed. It deliberately does not check `published_at` staleness:
- * RFC-AITP-0008 §3 puts freshness policy at the consuming peer, and
- * collapsing authenticity and freshness into a single switch is how a
- * `soft_fail` mode ends up reporting a *forged* snapshot as not-revoked.
- * The caller owns the staleness budget.
+ * Mirrors the Python SDK's `suite="ed25519"|"p256"` keyword argument so
+ * the two SDKs share one shape per operation. `null`/omitted defaults
+ * to `"ed25519"`.
  */
-export declare function verifyRevocationList(envelopeJson: string, expectedIssuerAid: string, nowUnixSecs?: number | undefined | null): void
+export interface GenerateOpts {
+  /**
+   * Signing suite. Accepted values: `"ed25519"` (default) or
+   * `"p256"` (RFC-AITP-0001 §5.4.3).
+   */
+  suite?: string
+}
+
 /**
- * The exact bytes a revocation snapshot's signature is computed over:
- * `JCS(revocation_list)` — the **inner** body, not the transport wrapper.
- *
- * Exposed so a caller needing the signed bytes (an independent verifier, an
- * HSM signing path, a debugging tool) obtains them rather than reconstructing
- * the shape at the call site. Reconstructing it is how signer, verifier and
- * conformance fixture drifted apart before 0.5.0.
+ * Outcome shape returned by `verifySessionBundle`. `kind` is `"clear"`
+ * or `"degraded"`; `droppedAids` is empty in the `"clear"` case.
  */
-export declare function revocationSigningBytes(envelopeJson: string): Buffer
-/** Result of `processHello`: response body plus session id. */
-export interface JsHelloAckResult {
-  /** `MUTUAL_HELLO_ACK` envelope JSON — set as the HTTP response body. */
-  ackJson: string
-  /** Correlation id — set as the `X-Aitp-Session-Id` response header. */
-  sessionId: string
+export interface JsBundleOutcome {
+  kind: string
+  activeAids: Array<string>
+  droppedAids: Array<string>
 }
+
 /**
- * The salient claims of a TCT obtained at handshake completion. Mirrors
- * `aitp_tct::TctClaims`; timestamps are Unix seconds as JS `number`s.
+ * Result of `processCommit`: response body plus the completed handshake
+ * (held TCT token, its claims, and the optional grant voucher).
  */
-export interface JsHandshakeTctClaims {
-  /** Issuer AID (`iss`) — the peer that minted and is bound by the TCT. */
-  iss: string
-  /** Subject AID (`sub`) — the holder the TCT authorizes. */
-  sub: string
-  /** Audience AID (`aud`). In v0.2 this equals `sub`. */
-  aud: string
-  /** Capability grants the TCT authorizes. */
-  grants: Array<string>
-  /** Issued-at, Unix seconds (`iat`). */
-  iat: number
-  /** Expiry, Unix seconds (`exp`). */
-  exp: number
-  /** TCT unique identifier (`jti`, UUID string). */
-  jti: string
+export interface JsCommitAckResult {
+  /** `MUTUAL_COMMIT_ACK` envelope JSON — set as the HTTP response body. */
+  ackJson: string
+  /** The TCT (and voucher) the initiator issued to us. */
+  completed: JsCompletedHandshake
 }
+
 /**
  * A completed handshake: the TCT the peer issued to us (as an opaque
  * compact-JWS token plus its decoded claims) and the optional companion
@@ -252,16 +319,68 @@ export interface JsCompletedHandshake {
    */
   grantVoucher?: string
 }
+
 /**
- * Result of `processCommit`: response body plus the completed handshake
- * (held TCT token, its claims, and the optional grant voucher).
+ * The verified delegation's salient fields. Returned from
+ * `verifyDelegation` and consumed by `AitpAgent.issueTctForDelegatee`.
  */
-export interface JsCommitAckResult {
-  /** `MUTUAL_COMMIT_ACK` envelope JSON — set as the HTTP response body. */
+export interface JsDelegationVerified {
+  /**
+   * AID of the ultimate grantor (the original TCT issuer that gave
+   * grants to `issuedBy`). Equal to the delegation's `aud` and to the
+   * embedded voucher's `iss`. The responder side checks this matches
+   * its own AID before redeeming.
+   */
+  delegator: string
+  /** AID of the recipient (C) — who will receive a fresh TCT (`sub`). */
+  delegatee: string
+  /** AID of the agent that issued this delegation (B in the RFC) (`iss`). */
+  issuedBy: string
+  /**
+   * Capabilities being delegated (`scope`). Always a subset of the
+   * root voucher's grants.
+   */
+  grants: Array<string>
+  /** Unix-seconds expiry of the delegation token itself (`exp`). */
+  expiresAt: number
+  /**
+   * RFC 7638 JWK thumbprint of the delegatee's key (`cnf.jkt`). In
+   * v0.2 this is derived from — and must match — the key encoded in
+   * `delegatee`'s AID; the fresh TCT's key binding is taken from the
+   * AID, not from this field.
+   */
+  cnfJkt: string
+}
+
+/**
+ * The salient claims of a TCT obtained at handshake completion. Mirrors
+ * `aitp_tct::TctClaims`; timestamps are Unix seconds as JS `number`s.
+ */
+export interface JsHandshakeTctClaims {
+  /** Issuer AID (`iss`) — the peer that minted and is bound by the TCT. */
+  iss: string
+  /** Subject AID (`sub`) — the holder the TCT authorizes. */
+  sub: string
+  /** Audience AID (`aud`). In v0.2 this equals `sub`. */
+  aud: string
+  /** Capability grants the TCT authorizes. */
+  grants: Array<string>
+  /** Issued-at, Unix seconds (`iat`). */
+  iat: number
+  /** Expiry, Unix seconds (`exp`). */
+  exp: number
+  /** TCT unique identifier (`jti`, UUID string). */
+  jti: string
+}
+
+/** Result of `processHello`: response body plus session id. */
+export interface JsHelloAckResult {
+  /** `MUTUAL_HELLO_ACK` envelope JSON — set as the HTTP response body. */
   ackJson: string
-  /** The TCT (and voucher) the initiator issued to us. */
-  completed: JsCompletedHandshake
+  /** Correlation id — set as the `X-Aitp-Session-Id` response header. */
+  sessionId: string
 }
+
 /** The verified peer identity carried by a TCT. */
 export interface JsTctIdentity {
   /** AID of the agent that issued (and is bound by) the TCT (`iss`). */
@@ -273,255 +392,158 @@ export interface JsTctIdentity {
   /** TCT unique identifier (`jti`). */
   jti: string
 }
+
+/** Options for `buildManifest`. */
+export interface ManifestOpts {
+  /** Human-readable agent name; also the pinned-key identity subject. */
+  displayName: string
+  /** Absolute URL of this agent's handshake endpoint. */
+  handshakeEndpoint: string
+  /** Capabilities this agent offers to peers. */
+  offeredCaps: Array<string>
+  /** Capabilities a peer must grant back (optional). */
+  requiredCaps?: Array<string>
+  /** Manifest TTL in seconds (optional; defaults to 3600). */
+  ttlSecs?: number
+  /** Identity presentation type — `"pinned_key"` (default) or `"oidc"`. */
+  identityType?: string
+  /** OIDC issuer URL (required when `identityType="oidc"`). */
+  oidcIssuer?: string
+  /** OIDC subject identifier (required when `identityType="oidc"`). */
+  oidcSubject?: string
+  /**
+   * Override the manifest's accepted_trust_anchors list. Defaults to
+   * `[oidc_issuer]` for OIDC mode and `[]` for pinned-key mode.
+   */
+  acceptedTrustAnchors?: Array<string>
+}
+
 /**
- * Verify a `ManifestEnvelope` JSON string. Used by the AITP Control Plane
- * during agent enrollment, and by any consumer reading an AID or endpoint
- * out of a peer's manifest.
- *
- * On failure throws an `Error` whose **`code`** property is one of
- * `signature_invalid`, `pop_failed`, `aid_mismatch`, `expired`,
- * `version_unknown`, `identity_hint_malformed`,
- * `incompatible_identity_type`, `malformed`. Branch on `error.code`, never
- * on `error.message`: the code is the contract, the wording is not.
- *
- * `nowUnixSecs` overrides the verification clock — omit it to use the
- * system clock, or pass a pinned value in tests. Matches
- * `verifyRevocationList`'s `nowUnixSecs` parameter.
+ * Input shape for `signRevocationList`. Field names map to spec
+ * `RevocationEntry` (jti, revoked_at, reason).
  */
-export declare function verifyManifestJson(manifestEnvelopeJson: string, nowUnixSecs?: number | undefined | null): void
-/** An AITP agent: a signing key and (once built) its Manifest. */
-export declare class AitpAgent {
-  /**
-   * Generate an agent with a fresh random signing key.
-   *
-   * `opts.suite` selects the algorithm — `"ed25519"` (default) or
-   * `"p256"`. Symmetric with the Python SDK's
-   * `AitpAgent.generate(suite="ed25519")`.
-   *
-   * ```ts
-   * const ed = AitpAgent.generate();                       // Ed25519
-   * const p  = AitpAgent.generate({ suite: 'p256' });      // P-256
-   * ```
-   */
-  static generate(opts?: GenerateOpts | undefined | null): AitpAgent
-  /**
-   * Construct an agent from a 32-byte seed (deterministic).
-   *
-   * `opts.suite` matches `AitpAgent.generate`. For `"p256"`, a tiny
-   * fraction of 32-byte seeds are not valid private scalars (zero
-   * or ≥ curve order) and raise.
-   *
-   * Note: the prior `AitpAgent.fromP256Seed` factory and the
-   * no-arg `AitpAgent.generate*` variants were removed in favor of
-   * this parameterized API so the Node SDK matches the Python SDK
-   * surface (CLAUDE.md mandates SDK symmetry).
-   */
-  static fromSeed(seed: Buffer, opts?: GenerateOpts | undefined | null): AitpAgent
-  /** The agent's AID string (`aid:pubkey:...`). */
-  get aid(): string
-  /**
-   * Build and sign the agent's Manifest. Returns `ManifestEnvelope`
-   * JSON and caches the Manifest for `newSession` / `newResponder`.
-   *
-   * See `ManifestOpts.identityType` for the OIDC switch.
-   */
-  buildManifest(opts: ManifestOpts): string
-  /**
-   * Create a new outbound (initiator) handshake session.
-   *
-   * `jwks` is an optional `JwksProvider` used when the peer's
-   * manifest advertises an OIDC identity. `opts.trustAnchors`
-   * overrides the manifest's `accepted_trust_anchors`.
-   */
-  newSession(jwks?: JwksProvider | undefined | null, opts?: SessionOpts | undefined | null): JsInitiatorSession
-  /**
-   * Create a new inbound (responder) handshake session. Mirror of
-   * `newSession`.
-   */
-  newResponder(jwks?: JwksProvider | undefined | null, opts?: SessionOpts | undefined | null): JsResponderSession
-  /**
-   * Verify a compact-JWS TCT token and require `requiredGrant`.
-   * Rejects on an invalid, mis-audienced, expired, revoked, or
-   * under-scoped TCT.
-   *
-   * `expectedAudience` defaults to `null`, which means "verify as the
-   * holder" (RFC-AITP-0005 §9 receipt model — `this.aid` is used).
-   * Resource servers verifying a TCT presented by a peer should pass
-   * the TCT's own `aud` claim as `expectedAudience` (in v0.2 this
-   * equals `sub`).
-   *
-   * `revokedJtis` (F-1) is an optional list of revoked TCT `jti`
-   * strings; any TCT whose `jti` is in the list is rejected even if
-   * otherwise valid. Omit (or pass `null`) to disable the revocation
-   * gate. The caller is responsible for sourcing the revoked set (e.g.
-   * from a `RevocationList` it fetched and verified).
-   */
-  verifyTct(tctToken: string, requiredGrant: string, expectedAudience?: string | undefined | null, revokedJtis?: Array<string> | undefined | null): JsTctIdentity
-  /**
-   * Like `verifyTct`, but consults a `TctStore` first: a byte-identical,
-   * already-verified, still-valid TCT skips the signature check (the
-   * verification hot path for an agent that sees the same TCT on many
-   * requests). All cheap policy checks (expiry, audience, required grant,
-   * and the optional `revokedJtis` gate) still run on every call; only the
-   * signature check is elided.
-   */
-  verifyTctCached(tctToken: string, requiredGrant: string, store: JsTctStore, expectedAudience?: string | undefined | null, revokedJtis?: Array<string> | undefined | null): JsTctIdentity
-  /**
-   * Build a delegation compact-JWS token from a held **grant voucher**
-   * (RFC-AITP-0006). `voucherToken` is the `grantVoucher` surfaced by
-   * `complete()` / `processCommit()`. The delegatee's key binding is
-   * derived from `delegateeAid` itself, so no separate public-key
-   * argument is needed in v0.2.
-   */
-  buildDelegation(voucherToken: string, delegateeAid: string, scope: Array<string>, ttlSecs?: number | undefined | null): string
-  /**
-   * Mint a fresh compact-JWS TCT for a delegatee after the verifier has
-   * confirmed the delegation. The subject-key binding is derived from
-   * the verified delegation's `delegatee` AID.
-   */
-  issueTctForDelegatee(verified: JsDelegationVerified, ttlSecs?: number | undefined | null): string
-  /**
-   * Sign a `RevocationList` with this agent's key. `entries` carries
-   * the revoked-TCT records; `expiresInSecs` defaults to 3600 s.
-   * Returns the on-wire `RevocationListEnvelope` JSON.
-   */
-  signRevocationList(entries: Array<RevocationEntryInput>, expiresInSecs?: number | undefined | null): string
-  /**
-   * Holder side: build a `TctRenewalPayload` JSON for an in-band
-   * renewal of `currentTctToken` — the holder's current TCT as a
-   * compact-JWS string (RFC-AITP-0013).
-   *
-   * Behind the `renewal` Cargo feature, which is **on by default**; a
-   * `--no-default-features` build omits it.
-   */
-  buildRenewalRequest(currentTctToken: string): string
+export interface RevocationEntryInput {
+  /** JTI of the revoked TCT (UUID string). */
+  jti: string
   /**
-   * Issuer side: verify a `TctRenewalPayload` JSON request and mint a
-   * fresh TCT, returned as a compact-JWS token string.
-   *
-   * Behind the `renewal` Cargo feature (on by default).
+   * Unix seconds when the issuing peer revoked the TCT.
+   * Defaults to the current time when omitted.
    */
-  processRenewalRequest(requestPayloadJson: string, manifestExpUnixSecs: number, newTtlSecs: number): string
+  revokedAt?: number
+  /** Optional human-readable reason. Not used in trust decisions. */
+  reason?: string
 }
-export type SessionBundleBuilderJs = SessionBundleBuilder
+
 /**
- * Fluent builder for issuing a `SessionBundleEnvelope`. Constructed
- * from the coordinator's `AitpAgent`.
+ * The exact bytes a revocation snapshot's signature is computed over:
+ * `JCS(revocation_list)` — the **inner** body, not the transport wrapper.
  *
- * The Rust struct is suffixed `Js` to avoid a name collision with the
- * `aitp_session_bundle::SessionBundleBuilder` imported above; the
- * `#[napi(js_name)]` attribute exposes it to JavaScript under the
- * plain name `SessionBundleBuilder` for parity with the Python SDK.
+ * Exposed so a caller needing the signed bytes (an independent verifier, an
+ * HSM signing path, a debugging tool) obtains them rather than reconstructing
+ * the shape at the call site. Reconstructing it is how signer, verifier and
+ * conformance fixture drifted apart before 0.5.0.
  */
-export declare class SessionBundleBuilder {
-  /** Construct a builder backed by `coordinator`'s signing key. */
-  constructor(coordinator: AitpAgent)
-  /** Set the session ID (UUIDv4 string). Defaults to a fresh one. */
-  sessionId(uuidStr: string): this
-  /** Override `issued_at` (unix seconds). Defaults to "now" at build. */
-  issuedAt(unixSecs: number): this
-  /**
-   * Add a participant entry. `tctToken` is the participant's TCT as an
-   * opaque compact-JWS string (the `tct` field returned by `complete()`
-   * / `processCommit()`), carried into the bundle verbatim.
-   */
-  participant(aid: string, tctToken: string): this
-  /** Construct, sign, and return the `SessionBundleEnvelope` JSON. */
-  build(): string
-}
+export declare function revocationSigningBytes(envelopeJson: string): Buffer
+
 /**
- * In-memory OIDC JWKS provider — issuer URL → list of JWK objects.
+ * Trust-anchor override for `newSession` / `newResponder`.
  *
- * The Node caller fetches the JWKS (the SDK has no HTTP client) and
- * hands the parsed objects to this provider. Implements `JwksResolver`
- * internally so the handshake state machine can dispatch through it.
+ * JWKS provider is passed as a separate argument (napi-rs can't put a
+ * class reference inside an `#[napi(object)]` struct).
  */
-export declare class JwksProvider {
-  /**
-   * Construct from an object mapping issuer URLs to arrays of JWK
-   * objects. Each JWK must be a standard RFC 7517 representation
-   * (`kty`, `crv`, `x`, ...). Pass `{}` for an empty provider and
-   * `upsert` later.
-   */
-  constructor(keys?: unknown | undefined | null)
+export interface SessionOpts {
   /**
-   * Add or replace the JWKs for an issuer. `keys` is a JS array of
-   * JWK objects.
+   * Override the agent manifest's accepted_trust_anchors. `null`
+   * reuses the manifest's list.
    */
-  upsert(issuer: string, keys: unknown): void
-  /** Drop all keys for an issuer. */
-  remove(issuer: string): void
-  /** Return the issuer URLs currently registered. */
-  issuers(): Array<string>
+  trustAnchors?: Array<string>
 }
+
 /**
- * Holds a list of 32-byte SPKI pins. `isPinned(certDer)` returns true
- * iff the cert's SPKI hash is in the list.
+ * Verify a delegation compact JWS under **strict AITP v0.2**
+ * (RFC-AITP-0006 single-hop). `verifierAid` is the verifier's own AID
+ * string — it MUST equal the delegation's `aud` (the root grantor), and
+ * the embedded voucher MUST verify under the verifier's own key.
+ *
+ * Any token carrying a non-empty `chain` (an RFC-AITP-0011 multi-hop
+ * delegation) is **rejected** with `DELEGATION_MULTIHOP_NOT_SUPPORTED`,
+ * matching the Rust core default. To allow multi-hop chains, call
+ * `verifyDelegationMultihop` instead.
+ *
+ * `revokedJtis` is an optional list of revoked `jti` strings — the
+ * verifier's own deny list. When non-empty, a token whose
+ * `voucher.src_jti` is in it is rejected after every signature check passes
+ * (RFC-AITP-0006 §4 step 7, ordered per RFC-AITP-0008 §3.3). **Verifiers
+ * SHOULD supply it.** Omitting it silently redeems a delegation whose
+ * source TCT has been revoked, which step 7 states as a MUST-reject.
  */
-export declare class SpkiPinVerifier {
-  /**
-   * Construct from an array of 32-byte Buffers. Throws if any pin is
-   * not exactly 32 bytes.
-   */
-  constructor(pins: Array<Buffer>)
-  /** Returns true iff the SPKI hash of `certDer` is in the pin list. */
-  isPinned(certDer: Buffer): boolean
-  /** Number of pins currently held. */
-  get len(): number
-}
-/** Outbound handshake session — drives the initiator side. */
-export declare class JsInitiatorSession {
-  /**
-   * Step 1 — build the `MUTUAL_HELLO` envelope.
-   *
-   * `oidcMintJwt`: required for OIDC agents. Receives the handshake-
-   * generated `pop_nonce` (string) and must return the JWT (string).
-   */
-  buildHello(peerManifestJson: string, requestedGrants: Array<string>, oidcMintJwt?: (...args: any[]) => any | undefined | null): string
-  /** Step 2 — process `MUTUAL_HELLO_ACK`, produce `MUTUAL_COMMIT`. */
-  processHelloAck(helloAckJson: string, sessionId: string): string
-  /**
-   * Step 3 — process `MUTUAL_COMMIT_ACK`. Returns the completed
-   * handshake: the TCT the peer issued to us (opaque compact-JWS
-   * token plus its decoded claims) and the optional grant voucher.
-   */
-  complete(commitAckJson: string): JsCompletedHandshake
-}
-/** Inbound handshake session — drives the responder side. */
-export declare class JsResponderSession {
-  /**
-   * Process an incoming `MUTUAL_HELLO` envelope.
-   *
-   * `oidcMintJwt`: required for OIDC agents (see `JsInitiatorSession.buildHello`).
-   */
-  processHello(helloJson: string, oidcMintJwt?: (...args: any[]) => any | undefined | null): JsHelloAckResult
-  /** Process an incoming `MUTUAL_COMMIT` envelope. */
-  processCommit(commitJson: string): JsCommitAckResult
-}
-export type JsTctStore = TctStore
+export declare function verifyDelegation(token: string, verifierAid: string, revokedJtis?: Array<string> | undefined | null): JsDelegationVerified
+
 /**
- * A bounded, in-memory cache of **successful** TCT verifications, keyed by
- * the SHA-256 of the exact compact-JWS TCT token bytes.
+ * Verify a delegation compact JWS allowing **RFC-AITP-0011 multi-hop**
+ * chains up to `maxDelegationHops` total hops (`chain.length + 1`).
  *
- * Purpose: a high-throughput verifier (e.g. a writer agent checking a
- * capability on every request) that repeatedly sees the *same* TCT can skip
- * the Ed25519/P-256 signature verification after the first time.
+ * The strict single-hop `verifyDelegation` is the safe default; this
+ * function additionally allows multi-hop chains. Present by default (the
+ * `multihop-delegation` feature); a `--no-default-features` build omits it.
  *
- * **Safety.** The key is a cryptographic hash of the exact signed bytes, so
- * only a byte-identical token — whose signature was already verified once
- * — can hit. A tampered token hashes differently, misses, and is fully
- * verified. The cheap policy checks (expiry, audience, required grant) are
- * re-run on **every** hit; only the signature check is elided. Eviction is
- * FIFO once `maxEntries` is reached.
+ * `maxDelegationHops` defaults to `DEFAULT_MAX_DELEGATION_HOPS` (3, the RFC-AITP-0011 §2
+ * recommended ceiling). Pass a smaller value for a tighter bound;
+ * `maxDelegationHops = 0` reverts to strict single-hop (rejects any non-empty chain).
+ *
+ * `revokedJtis`, when non-empty, is consulted twice — both only after every
+ * signature check: once for the root `voucher.src_jti` (RFC-AITP-0006 §4
+ * step 7), and once for every hop's `jti`, meaning each chain entry and the
+ * outer token (RFC-AITP-0011 §6). Both are MUST-rejects, and a revoked hop
+ * invalidates every hop downstream of it — there is no partial-validity
+ * model.
+ *
+ * Note that §6 specifies each hop `jti` be checked against the deny list of
+ * *that hop's issuer*, which one flat list cannot express, so it is applied
+ * to every hop regardless of issuer. That can only reject more, never
+ * accept a revoked hop, but it does mean a list aggregated across several
+ * issuers lets any contributor revoke any hop.
  */
-export declare class TctStore {
-  /**
-   * Create a cache holding at most `maxEntries` verified TCTs (FIFO
-   * eviction). `maxEntries` must be >= 1.
-   */
-  constructor(maxEntries: number)
-  /** Number of cached verifications currently held. */
-  len(): number
-  /** Drop all cached entries. */
-  clear(): void
-}
+export declare function verifyDelegationMultihop(token: string, verifierAid: string, maxDelegationHops?: number | undefined | null, revokedJtis?: Array<string> | undefined | null): JsDelegationVerified
+
+/**
+ * Verify a `ManifestEnvelope` JSON string. Used by the AITP Control Plane
+ * during agent enrollment, and by any consumer reading an AID or endpoint
+ * out of a peer's manifest.
+ *
+ * On failure throws an `Error` whose **`code`** property is one of
+ * `signature_invalid`, `pop_failed`, `aid_mismatch`, `expired`,
+ * `version_unknown`, `identity_hint_malformed`,
+ * `incompatible_identity_type`, `malformed`. Branch on `error.code`, never
+ * on `error.message`: the code is the contract, the wording is not.
+ *
+ * `nowUnixSecs` overrides the verification clock — omit it to use the
+ * system clock, or pass a pinned value in tests. Matches
+ * `verifyRevocationList`'s `nowUnixSecs` parameter.
+ */
+export declare function verifyManifestJson(manifestEnvelopeJson: string, nowUnixSecs?: number | undefined | null): void
+
+/**
+ * Verify a `RevocationListEnvelope` JSON string against a pinned issuer.
+ *
+ * Resolves on success; on failure throws an `Error` whose **`code`** property
+ * is one of `signature_invalid`, `issuer_mismatch`, `version_unknown`,
+ * `expired`, `malformed`. Branch on `error.code`, never on `error.message`:
+ * the code is the contract, the message wording is not.
+ *
+ * Establishes **authenticity and non-expiry only** — that the snapshot was
+ * signed by the holder of `expectedIssuerAid` and that its `expires_at` has
+ * not passed. It deliberately does not check `published_at` staleness:
+ * RFC-AITP-0008 §3 puts freshness policy at the consuming peer, and
+ * collapsing authenticity and freshness into a single switch is how a
+ * `soft_fail` mode ends up reporting a *forged* snapshot as not-revoked.
+ * The caller owns the staleness budget.
+ */
+export declare function verifyRevocationList(envelopeJson: string, expectedIssuerAid: string, nowUnixSecs?: number | undefined | null): void
+
+/**
+ * Verify a `SessionBundleEnvelope` JSON. `nowUnixSecs` defaults to
+ * the system clock. `revocationCheck` receives a JTI string and
+ * returns true if revoked.
+ */
+export declare function verifySessionBundle(bundleEnvelopeJson: string, verifierAid: string, nowUnixSecs?: number | undefined | null, revocationCheck?: ((arg: string) => boolean) | undefined | null): JsBundleOutcome