@agentidentitytrustprotocol/aitp 0.2.0

package/README.md

@@ -0,0 +1,160 @@
+# aitp — Node.js SDK
+
+Node.js bindings for the **Agent Identity & Trust Protocol (AITP)**, built on
+the pure-Rust `aitp-rs` protocol crates via [NAPI-rs](https://napi.rs).
+
+A thin SDK: an `AitpAgent` plus initiator/responder session objects whose
+methods take and return JSON strings — the HTTP request/response bodies — so
+agent code never handles a Rust type across the FFI boundary. The API is the
+symmetric counterpart of the Python SDK (`buildManifest` ↔ `build_manifest`).
+
+## Build
+
+This crate is **not** part of the `aitp-rs` Cargo workspace. Build it with
+the [NAPI-rs CLI](https://napi.rs):
+
+```bash
+npm install
+npm run build:debug                  # default `.node` (v0.1 surface only)
+npm run build:experimental:debug     # default + post-v0.1 features
+# Release:
+npm run build                        # default release
+npm run build:experimental           # default + experimental, release
+```
+
+This produces `aitp.node` and `index.js` in the package root. Generated
+TypeScript typings (`index.d.ts`) include the experimental surface only
+when the artifact was built with the `experimental` feature.
+
+### Cargo features
+
+The default `.node` exposes the v0.1 surface (handshake, TCT, delegation,
+manifest verify, revocation-list signing, OIDC identity). Three post-v0.1
+capabilities live behind opt-in Cargo features:
+
+| Feature                   | Enables                                                                  | RFC                  |
+|---------------------------|--------------------------------------------------------------------------|----------------------|
+| `experimental-renewal`    | `AitpAgent.buildRenewalRequest` / `processRenewalRequest`                | RFC-AITP-0005 §10    |
+| `experimental-bundle`     | `SessionBundleBuilder`, `verifySessionBundle`                            | RFC-AITP-0010        |
+| `experimental-pinning`    | `computeSpkiHash`, `SpkiPinVerifier`                                     | HPKP (RFC 7469)      |
+| `experimental-multihop-delegation` | `verifyDelegationExperimentalMultihop`                          | RFC-AITP-0011        |
+| `experimental` (umbrella) | All four above                                                           |                      |
+
+Each post-v0.1 capability does **not** promise wire stability until the
+underlying RFC graduates.
+
+## Usage
+
+```javascript
+import { AitpAgent } from '@agentidentitytrustprotocol/aitp';
+
+const initiator = AitpAgent.generate();
+const responder = AitpAgent.generate();
+
+initiator.buildManifest({
+  displayName: 'initiator',
+  handshakeEndpoint: 'http://localhost:8100/aitp/handshake/',
+  offeredCaps: ['demo.echo'],
+});
+const respManifest = responder.buildManifest({
+  displayName: 'responder',
+  handshakeEndpoint: 'http://localhost:8200/aitp/handshake/',
+  offeredCaps: ['demo.write'],
+});
+
+// Four-message mutual handshake — each call's output is the next peer's input.
+const sess  = initiator.newSession();
+const rsess = responder.newResponder();
+
+const hello                   = sess.buildHello(respManifest, ['demo.write']);
+const { ackJson: helloAck, sessionId } = rsess.processHello(hello);
+const commit                  = sess.processHelloAck(helloAck, sessionId);
+const { ackJson: commitAck }   = rsess.processCommit(commit);
+const initiatorHeldTct         = sess.complete(commitAck);
+
+// Each peer now holds a TCT the other issued it.
+const ident = initiator.verifyTct(initiatorHeldTct, 'demo.write');
+console.log(ident.peerAid, ident.grants);
+```
+
+In a real deployment each message moves over HTTP: `buildHello` returns the
+`POST /aitp/handshake/hello` body, `processHello` returns the response body
+plus the value for the `X-Aitp-Session-Id` header, and so on.
+
+## API
+
+The full public surface is described in the generated `index.d.ts`; below
+is a summary. All `*Json` parameters and return values are JSON strings.
+
+| Type                      | Default? | Notes                                                                                                          |
+|---------------------------|:--------:|----------------------------------------------------------------------------------------------------------------|
+| `AitpAgent`               |    ✅    | `generate(opts?)` / `fromSeed(buffer, opts?)` (`opts.suite = "ed25519" \| "p256"`), `aid`, `buildManifest(opts)`, `newSession(jwks?, opts?)`, `newResponder(jwks?, opts?)`, `verifyTct(...)`, `buildDelegation(...)`, `issueTctForDelegatee(...)`, `signRevocationList(...)` |
+| `InitiatorSession`        |    ✅    | `buildHello(peerManifest, grants, oidcMintJwt?)`, `processHelloAck(...)`, `complete(...)`                       |
+| `ResponderSession`        |    ✅    | `processHello(hello, oidcMintJwt?)` → `{ ackJson, sessionId }`, `processCommit(commit)` → `{ ackJson, tctJson }` |
+| `TctIdentity`             |    ✅    | `peerAid`, `grants`, `expiresAt`, `jti`                                                                          |
+| `DelegationVerified`      |    ✅    | `delegator`, `delegatee`, `issuedBy`, `grants`, `expiresAt`, `cnf`                                              |
+| `JwksProvider`            |    ✅    | OIDC JWKS map. `upsert(issuer, keys)`, `remove(issuer)`, `issuers()`                                            |
+| `TctStore` / `verifyTctCached()` | ✅ | Hot-path verify cache: skips the signature check for a byte-identical, still-valid TCT (keyed by SHA-256 of the envelope) |
+| `verifyDelegation()`      |    ✅    | RFC-AITP-0006 — strict v0.1 single-hop; rejects any multi-hop `chain`                                          |
+| `verifyManifestJson()`    |    ✅    | Control-plane manifest enrollment                                                                               |
+| `buildRenewalRequest()` / `processRenewalRequest()`           | `experimental-renewal` | RFC-AITP-0005 §10 |
+| `SessionBundleBuilder`, `verifySessionBundle()`               | `experimental-bundle`  | RFC-AITP-0010      |
+| `computeSpkiHash()`, `SpkiPinVerifier`                        | `experimental-pinning` | HPKP outbound pinning |
+| `verifyDelegationExperimentalMultihop()`                      | `experimental-multihop-delegation` | RFC-AITP-0011 (draft) multi-hop opt-in |
+
+### OIDC identity (RFC-AITP-0002)
+
+```javascript
+import { AitpAgent, JwksProvider } from '@agentidentitytrustprotocol/aitp';
+
+const jwks = new JwksProvider({
+  'https://idp.example/': [{ kty: 'OKP', crv: 'Ed25519', x: '...', kid: 'k1', alg: 'EdDSA' }],
+});
+
+const agent = AitpAgent.generate();
+agent.buildManifest({
+  displayName: 'alice',
+  handshakeEndpoint: 'https://alice.example/aitp/handshake/',
+  offeredCaps: ['demo.echo'],
+  identityType: 'oidc',
+  oidcIssuer: 'https://idp.example/',
+  oidcSubject: 'alice',
+});
+const sess = agent.newSession(jwks);
+
+const mintJwt = (nonce) => myIdp.mintJwtSync({ nonce, sub: 'alice', aud: peerAid });
+const hello = sess.buildHello(peerManifest, ['demo.echo'], mintJwt);
+```
+
+### P-256 signing (RFC-AITP-0001 §5.4.3)
+
+```javascript
+const agent = AitpAgent.generate({ suite: 'p256' });   // aid:pubkey:p256:<44>
+// Deterministic from a seed:
+const seeded = AitpAgent.fromSeed(seed, { suite: 'p256' });
+// All other methods identical; signatures emitted as `p256.<86b64u>`.
+```
+
+> **Breaking change in v0.2:** `AitpAgent.generateP256()` and
+> `AitpAgent.fromP256Seed(seed)` were removed in favor of the
+> parameterized `generate({ suite })` / `fromSeed(seed, { suite })`
+> API. This matches the Python SDK's
+> `AitpAgent.generate(suite="p256")` shape — CLAUDE.md mandates SDK
+> symmetry. Migration: replace `generateP256()` with
+> `generate({ suite: 'p256' })` and `fromP256Seed(seed)` with
+> `fromSeed(seed, { suite: 'p256' })`.
+
+> **Note.** In v0.1 the `pinned_key` identity_hint embeds an Ed25519 raw
+> public key. P-256 agents must therefore use `identityType: 'oidc'` until
+> the manifest's identity_hint shape is extended.
+
+## Tests
+
+```bash
+npm install
+npm run build:debug
+npm test                 # node --test tests/*.mjs
+```
+
+The cross-language interop suite (Python ↔ Node) lives in
+[`../interop`](../interop) — run it with `make interop` from the repo root.

package/index.d.ts

@@ -0,0 +1,403 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * 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
+  /**
+   * Unix seconds when the issuing peer revoked the TCT.
+   * Defaults to the current time when omitted.
+   */
+  revokedAt?: number
+  /** Optional human-readable reason. Not used in trust decisions. */
+  reason?: 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>
+}
+/**
+ * Trust-anchor override for `newSession` / `newResponder`.
+ *
+ * JWKS provider is passed as a separate argument (napi-rs can't put a
+ * class reference inside an `#[napi(object)]` struct).
+ */
+export interface SessionOpts {
+  /**
+   * Override the agent manifest's accepted_trust_anchors. `null`
+   * reuses the manifest's list.
+   */
+  trustAnchors?: Array<string>
+}
+/**
+ * Options for `AitpAgent.generate` and `AitpAgent.fromSeed`.
+ *
+ * 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 interface GenerateOpts {
+  /**
+   * Signing suite. Accepted values: `"ed25519"` (default) or
+   * `"p256"` (RFC-AITP-0001 §5.4.3).
+   */
+  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>
+}
+/**
+ * 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 token's salient fields. Returned from
+ * `verifyDelegation` and consumed by `AitpAgent.issueTctForDelegatee`.
+ */
+export interface JsDelegationVerified {
+  /**
+   * AID of the ultimate grantor (the original TCT issuer that gave grants
+   * to `issuedBy`). The responder side checks this matches its own AID
+   * before redeeming.
+   */
+  delegator: string
+  /** AID of the recipient (C) — who will receive a fresh TCT. */
+  delegatee: string
+  /** AID of the agent that issued this delegation (B in the RFC). */
+  issuedBy: string
+  /** Capabilities being delegated. Always a subset of the source TCT's grants. */
+  grants: Array<string>
+  /** Unix-seconds expiry of the delegation token itself. */
+  expiresAt: number
+  /**
+   * Delegatee's raw Ed25519 / P-256 public key, base64url-encoded. This is
+   * the `cnf` binding — proves which key the issuer should bind to the
+   * fresh TCT it mints.
+   */
+  cnf: string
+}
+/**
+ * Verify a `DelegationEnvelope` JSON under **strict AITP v0.1**
+ * (RFC-AITP-0006 single-hop). `verifierAid` is the verifier's own AID
+ * string — verification fails if it doesn't match the token's `delegator`
+ * field.
+ *
+ * Any token carrying a non-empty `chain` (a draft RFC-AITP-0011 multi-hop
+ * delegation) is **rejected** with `DELEGATION_MULTIHOP_NOT_SUPPORTED`,
+ * matching the Rust core default. To opt into multi-hop, build the SDK with
+ * the `experimental-multihop-delegation` feature and call
+ * `verifyDelegationExperimentalMultihop`.
+ */
+export declare function verifyDelegation(envelopeJson: string, verifierAid: string): JsDelegationVerified
+/**
+ * Verify a `DelegationEnvelope` JSON allowing **draft RFC-AITP-0011
+ * multi-hop** chains up to `maxHops` total hops (`chain.length + 1`).
+ *
+ * This opts into behavior that is **not** part of AITP v0.1. It is only
+ * compiled in under the `experimental-multihop-delegation` feature; a
+ * default build exposes only the strict `verifyDelegation`.
+ *
+ * `maxHops` defaults to `DEFAULT_MAX_HOPS` (3, the RFC-AITP-0011 §2
+ * recommended ceiling). Pass a smaller value for a tighter bound;
+ * `maxHops = 0` reverts to strict v0.1 (rejects any non-empty chain).
+ */
+export declare function verifyDelegationExperimentalMultihop(envelopeJson: string, verifierAid: string, maxHops?: number | undefined | null): JsDelegationVerified
+/**
+ * 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`
+ * claim when proving the key binding (RFC-AITP-0002 §2.2.1).
+ *
+ * Works for both Ed25519 (`aid:pubkey:ed25519:...`) and P-256
+ * (`aid:pubkey:p256:...`) AIDs. Use this from your OIDC minter
+ * closure so the bound peer correctly verifies the cnf binding —
+ * implementing curve arithmetic by hand to derive the thumbprint
+ * 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
+/** 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
+}
+/** Result of `processCommit`: response body plus the held TCT. */
+export interface JsCommitAckResult {
+  /** `MUTUAL_COMMIT_ACK` envelope JSON — set as the HTTP response body. */
+  ackJson: string
+  /** `TctEnvelope` JSON the initiator issued to us. */
+  tctJson: string
+}
+/** The verified peer identity carried by a TCT. */
+export interface JsTctIdentity {
+  /** AID of the agent that issued (and is bound by) the TCT. */
+  peerAid: string
+  /** Capability grants the TCT authorizes. */
+  grants: Array<string>
+  /** Expiry, Unix seconds. */
+  expiresAt: number
+  /** TCT unique identifier (`jti`). */
+  jti: string
+}
+/**
+ * Verify a `ManifestEnvelope` JSON string. Throws on signature,
+ * proof-of-possession, expiry, or identity-hint shape failures.
+ * Used by the AITP Control Plane during agent enrollment.
+ */
+export declare function verifyManifestJson(manifestEnvelopeJson: string): 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 TCT JSON string and require `requiredGrant`. Rejects on
+   * an invalid, mis-audienced, expired, 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 `audience` field as `expectedAudience` (in v0.1 this
+   * equals `subject`).
+   */
+  verifyTct(tctJson: string, requiredGrant: string, expectedAudience?: 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)
+   * still run on every call; only the signature check is elided.
+   */
+  verifyTctCached(tctJson: string, requiredGrant: string, store: JsTctStore, expectedAudience?: string | undefined | null): JsTctIdentity
+  /** Build a `DelegationEnvelope` JSON from a held TCT (RFC-AITP-0006). */
+  buildDelegation(heldTctEnvelopeJson: string, delegateeAid: string, delegateePubkeyB64U: string, scope: Array<string>, ttlSecs?: number | undefined | null): string
+  /**
+   * Mint a fresh `TctEnvelope` JSON for a delegatee after the verifier has
+   * confirmed the delegation. The subject_pubkey binding is taken from the
+   * verified token's `cnf` field.
+   */
+  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 `currentTctEnvelopeJson` (RFC-AITP-0005 §10).
+   *
+   * **Gated by the `experimental-renewal` Cargo feature.** Off in
+   * the default `.node` artifact; build with
+   * `napi build --release -- --features experimental-renewal`.
+   */
+  buildRenewalRequest(currentTctEnvelopeJson: string): string
+  /**
+   * Issuer side: verify a `TctRenewalPayload` JSON request and mint a
+   * fresh `TctEnvelope` JSON.
+   *
+   * **Gated by the `experimental-renewal` Cargo feature.**
+   */
+  processRenewalRequest(requestPayloadJson: string, manifestExpUnixSecs: number, newTtlSecs: number): string
+}
+export type SessionBundleBuilderJs = SessionBundleBuilder
+/**
+ * Fluent builder for issuing a `SessionBundleEnvelope`. Constructed
+ * from the coordinator's `AitpAgent`.
+ *
+ * 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 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. `tctEnvelopeJson` is a TctEnvelope JSON. */
+  participant(aid: string, tctEnvelopeJson: string): this
+  /** Construct, sign, and return the `SessionBundleEnvelope` JSON. */
+  build(): string
+}
+/**
+ * In-memory OIDC JWKS provider — issuer URL → list of JWK objects.
+ *
+ * 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 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)
+  /**
+   * 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>
+}
+/**
+ * Holds a list of 32-byte SPKI pins. `isPinned(certDer)` returns true
+ * iff the cert's SPKI hash is in the list.
+ */
+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 `TctEnvelope`
+   * JSON the peer issued to us.
+   */
+  complete(commitAckJson: string): string
+}
+/** 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
+/**
+ * A bounded, in-memory cache of **successful** TCT verifications, keyed by
+ * the SHA-256 of the exact TCT envelope JSON bytes.
+ *
+ * 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.
+ *
+ * **Safety.** The key is a cryptographic hash of the exact signed bytes, so
+ * only a byte-identical envelope — 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 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
+}

package/index.js

@@ -0,0 +1,327 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'aitp.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./aitp.android-arm64.node')
+          } else {
+            nativeBinding = require('@agentidentitytrustprotocol/aitp-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'aitp.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./aitp.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('@agentidentitytrustprotocol/aitp-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'aitp.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./aitp.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('@agentidentitytrustprotocol/aitp-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'aitp.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./aitp.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('@agentidentitytrustprotocol/aitp-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'aitp.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./aitp.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('@agentidentitytrustprotocol/aitp-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'aitp.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./aitp.darwin-universal.node')
+      } else {
+        nativeBinding = require('@agentidentitytrustprotocol/aitp-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'aitp.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./aitp.darwin-x64.node')
+          } else {
+            nativeBinding = require('@agentidentitytrustprotocol/aitp-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'aitp.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./aitp.darwin-arm64.node')
+          } else {
+            nativeBinding = require('@agentidentitytrustprotocol/aitp-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'aitp.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./aitp.freebsd-x64.node')
+      } else {
+        nativeBinding = require('@agentidentitytrustprotocol/aitp-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'aitp.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./aitp.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('@agentidentitytrustprotocol/aitp-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'aitp.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./aitp.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('@agentidentitytrustprotocol/aitp-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'aitp.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./aitp.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('@agentidentitytrustprotocol/aitp-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'aitp.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./aitp.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('@agentidentitytrustprotocol/aitp-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'aitp.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./aitp.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('@agentidentitytrustprotocol/aitp-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'aitp.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./aitp.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('@agentidentitytrustprotocol/aitp-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'aitp.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./aitp.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('@agentidentitytrustprotocol/aitp-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'aitp.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./aitp.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('@agentidentitytrustprotocol/aitp-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'aitp.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./aitp.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('@agentidentitytrustprotocol/aitp-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { AitpAgent, SessionBundleBuilder, verifySessionBundle, verifyDelegation, verifyDelegationExperimentalMultihop, computeAidJkt, JwksProvider, computeSpkiHash, SpkiPinVerifier, JsInitiatorSession, JsResponderSession, TctStore, verifyManifestJson } = nativeBinding
+
+module.exports.AitpAgent = AitpAgent
+module.exports.SessionBundleBuilder = SessionBundleBuilder
+module.exports.verifySessionBundle = verifySessionBundle
+module.exports.verifyDelegation = verifyDelegation
+module.exports.verifyDelegationExperimentalMultihop = verifyDelegationExperimentalMultihop
+module.exports.computeAidJkt = computeAidJkt
+module.exports.JwksProvider = JwksProvider
+module.exports.computeSpkiHash = computeSpkiHash
+module.exports.SpkiPinVerifier = SpkiPinVerifier
+module.exports.JsInitiatorSession = JsInitiatorSession
+module.exports.JsResponderSession = JsResponderSession
+module.exports.TctStore = TctStore
+module.exports.verifyManifestJson = verifyManifestJson

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@agentidentitytrustprotocol/aitp",
+  "version": "0.2.0",
+  "description": "Agent Identity Trust Protocol — Node.js SDK",
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentidentitytrustprotocol/aitp-rs.git",
+    "directory": "bindings/aitp-node"
+  },
+  "homepage": "https://github.com/agentidentitytrustprotocol/aitp-rs/tree/main/bindings/aitp-node",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "type": "commonjs",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "napi": {
+    "name": "aitp",
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-apple-darwin",
+        "aarch64-apple-darwin",
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-gnu"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform",
+    "build:experimental": "napi build --platform --release --features experimental",
+    "build:experimental:debug": "napi build --platform --features experimental",
+    "artifacts": "napi artifacts",
+    "prepublishOnly": "napi prepublish -t npm",
+    "version": "napi version",
+    "test": "node --test tests/*.mjs"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.0",
+    "node-forge": "^1.4.0"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "jose": "^6.2.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "optionalDependencies": {
+    "@agentidentitytrustprotocol/aitp-darwin-x64": "0.2.0",
+    "@agentidentitytrustprotocol/aitp-darwin-arm64": "0.2.0",
+    "@agentidentitytrustprotocol/aitp-linux-x64-gnu": "0.2.0",
+    "@agentidentitytrustprotocol/aitp-linux-arm64-gnu": "0.2.0"
+  }
+}