@agent-score/commerce 2.4.0 → 2.6.0

package/dist/gate-D2RP6bZg.d.ts

@@ -0,0 +1,307 @@
+import { a as AitPayload, T as TrustLevel } from './types-D1slMt0H.js';
+import { JWK } from 'jose';
+
+/**
+ * AIP IdP key discovery: fetch, cache, and select JWKS signing keys.
+ *
+ * Verifiers resolve an IdP's public keys from `https://{iss}/.well-known/agent-identity/jwks.json`
+ * (the spec's well-known path). This module owns:
+ *
+ *   - **Trusted-issuer enforcement** — only `iss` values on the allowlist are fetched, compared
+ *     after URL canonicalization (lowercase scheme+host, no default port, no trailing slash) so
+ *     `https://issuer.example` and `https://issuer.example/` match.
+ *   - **HTTPS-only** — JWKS over plain HTTP is MITM-vulnerable; we refuse it.
+ *   - **Caching with a HARD cap** — we honor `Cache-Control: max-age` as advisory but never
+ *     cache longer than {@link HARD_MAX_CACHE_SECONDS}, regardless of what the IdP sends. A
+ *     compromised IdP can't pin stale keys with `max-age=31536000`.
+ *   - **kid-miss refresh** — a lookup for a `kid` not in the cached set triggers one refetch
+ *     (rotation may have published a new key inside the cache window).
+ *   - **use:"sig" filtering** — only signing keys are returned.
+ *
+ * Pure-ish: the only I/O is `fetch`, injectable for tests.
+ */
+
+/** The spec's well-known JWKS path, relative to the issuer origin. */
+declare const JWKS_WELL_KNOWN_PATH = "/.well-known/agent-identity/jwks.json";
+/** Hard ceiling on cache age, regardless of IdP-supplied Cache-Control. */
+declare const HARD_MAX_CACHE_SECONDS = 86400;
+type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+}>;
+/** AgentScore's own AIT issuer. ALWAYS trusted by every {@link JwksCache} (and therefore every
+ *  gate/adapter built on it) without the merchant listing it — this SDK is the AgentScore
+ *  verifier, so a merchant can't accidentally fail to trust AgentScore-issued AITs. `trustedIssuers`
+ *  only needs to name ADDITIONAL external issuers. */
+declare const AGENTSCORE_CANONICAL_ISSUER = "https://www.agentscore.com";
+interface JwksCacheOptions {
+    /** ADDITIONAL external issuer URLs to trust beyond AgentScore's own (compared after
+     *  canonicalization). AgentScore's canonical issuer is always trusted; omit/empty to accept
+     *  only AgentScore-issued AITs. */
+    trustedIssuers?: string[];
+    /** Injectable fetch (defaults to global fetch). */
+    fetchImpl?: FetchLike;
+    /** Injectable clock (ms), for tests. */
+    now?: () => number;
+    /** User-Agent for JWKS requests. */
+    userAgent?: string;
+}
+type JwksLookupFailure = 'untrusted_issuer' | 'insecure_issuer' | 'fetch_failed' | 'malformed_jwks' | 'key_not_found';
+type JwksLookupResult = {
+    ok: true;
+    key: JWK;
+} | {
+    ok: false;
+    reason: JwksLookupFailure;
+};
+/**
+ * Canonicalize an issuer URL for trust-list comparison: lowercase scheme + host, drop the
+ * default port for the scheme, strip a trailing slash on an empty path. Returns null if the
+ * input is not a parseable absolute URL.
+ */
+declare const canonicalizeIssuer: (iss: string) => string | null;
+/**
+ * JWKS resolver bound to a trusted-issuer allowlist. One instance can serve many issuers;
+ * each issuer's key set is cached independently.
+ */
+declare class JwksCache {
+    private readonly trusted;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly userAgent;
+    private readonly cache;
+    /** Per-issuer in-flight refresh promise — coalesces concurrent refreshes to ONE upstream fetch.
+     *  Without it, a concurrent burst of distinct-kid lookups on a cold/expired cache each call
+     *  `refresh()` before any has populated the cache → N parallel JWKS GETs (refetch amplification).
+     *  The cooldown only suppresses SEQUENTIAL refetches; single-flight suppresses CONCURRENT ones.
+     *  Entry is cleared in a `finally` once the fetch settles. */
+    private readonly inflight;
+    constructor(opts: JwksCacheOptions);
+    /** Is this issuer on the canonicalized trust list? */
+    isTrusted(iss: string): boolean;
+    /**
+     * Resolve the signing key for `(iss, kid)`. Enforces trust + HTTPS, serves from cache when
+     * fresh, and refetches once on a kid-miss before giving up.
+     */
+    getKey(iss: string, kid: string | undefined): Promise<JwksLookupResult>;
+    private select;
+    /**
+     * Refresh the cached key set for `canonIssuer`, coalescing concurrent callers onto a single
+     * upstream fetch (single-flight). The first caller for an issuer with no in-flight refresh kicks
+     * off the fetch and registers the promise; concurrent callers await that same promise instead of
+     * issuing their own GET. The entry is cleared once the fetch settles so the NEXT cold/expired
+     * lookup can refresh again.
+     */
+    private refresh;
+    private fetchAndCache;
+    /** Stamp the per-issuer refetch cooldown on a FAILED fetch attempt (the negative cache). Any
+     *  previously cached keys + expiry are preserved — a failed kid-miss refetch must not nuke a
+     *  still-fresh key set; only the cooldown and failure reason are updated. */
+    private stampFailure;
+}
+
+/**
+ * AIP Agent Identity Token (AIT) verification pipeline — the verifier orchestrator.
+ *
+ * This is the function a merchant gate calls. It executes the spec's verification steps over
+ * a presented request, composing the three foundation modules:
+ *   - {@link ./jwks}        — trusted-issuer enforcement + key discovery
+ *   - {@link ./http-signature} — RFC 9421 proof-of-possession over the request
+ *   - {@link ./types}       — AIT structural contract
+ *
+ * Steps (per spec):
+ *   1. read the `Agent-Identity` header (one or more)
+ *   2. decode the JWT header (`kid`) + payload; confirm AIT shape (`cnf` + `agent`)
+ *   3. resolve the IdP's signing key from its JWKS (trusted-issuer + HTTPS enforced)
+ *   4. verify the IdP signature on the JWT (reject `alg:none`; key is Ed25519)
+ *   5. check `exp` / `iat` with skew
+ *   6. extract `cnf.jwk`
+ *   7. verify the RFC 9421 HTTP Message Signature with `cnf.jwk`
+ *   8. confirm the signature `keyid` == JWK thumbprint of `cnf.jwk`  (done inside step 7)
+ *
+ * On success it returns the validated, signature-checked claims. On failure it returns a
+ * typed reason that maps onto AIP's wire error codes (the gate turns these into 401/403).
+ */
+
+/** Header that carries the AIT JWT. */
+declare const AGENT_IDENTITY_HEADER = "agent-identity";
+/** Request fields the verifier needs. Framework-agnostic; adapters map their req onto this. */
+interface VerifyRequestContext {
+    method: string;
+    authority: string;
+    path: string;
+    /** All `Agent-Identity` header values present on the request (one per IdP). */
+    agentIdentityHeaders: string[];
+    signatureInput: string | null;
+    signature: string | null;
+}
+interface VerifyAitOptions {
+    jwks: JwksCache;
+    now?: number;
+    maxSkewSeconds?: number;
+    /** Max accepted AIT lifetime (`exp - iat`) in seconds. Defense-in-depth vs an external issuer
+     *  minting a long-lived bearer credential. The spec recommends a 60–300s window; default 300 so a
+     *  stolen AIT's usable window stays short even at the edge (standalone `aipGate`, no `/v1/assess`).
+     *  Our own mint is 300s, so first-party tokens sit exactly at the ceiling. Matches the
+     *  authoritative API verifier's default (the AgentScore API verifier), lowered from 3600. */
+    maxLifetimeSeconds?: number;
+}
+/**
+ * Failure reasons, aligned with AIP wire error codes. The gate maps:
+ *   no_token / malformed_token / invalid_signature / expired_token  → 401
+ *   untrusted_issuer / weak_auth / invalid_claims                   → 403
+ */
+type VerifyAitFailure = 'no_token' | 'malformed_token' | 'untrusted_issuer' | 'key_unavailable' | 'idp_signature_invalid' | 'expired_token' | 'invalid_claims' | 'pop_signature_missing' | 'pop_signature_invalid';
+interface VerifiedAit {
+    payload: AitPayload;
+    /** The issuer (canonical, as presented). */
+    iss: string;
+    /** The agent's bound public key (`cnf.jwk`). */
+    cnfJwk: AitPayload['cnf']['jwk'];
+    /** The raw JWT string that verified (the winning `Agent-Identity` header value, Bearer
+     *  prefix stripped). Lets a gate forward the exact token to `/v1/assess` as `aip_token`. */
+    token: string;
+    /** The RFC 9421 signature material for this request — forwarded to `/v1/assess` as
+     *  `aip_signature` so the API re-verifies proof-of-possession authoritatively (the edge
+     *  check here is only a fail-fast filter; the API is the source of truth). */
+    signatureMaterial: {
+        method: string;
+        authority: string;
+        path: string;
+        signature_input: string;
+        signature: string;
+    };
+}
+type VerifyAitResult = {
+    ok: true;
+    ait: VerifiedAit;
+} | {
+    ok: false;
+    reason: VerifyAitFailure;
+};
+/**
+ * Verify the AIP credential on a request. When multiple `Agent-Identity` headers are present,
+ * each is tried; the first that fully verifies AND whose `cnf.jwk` matches the request's
+ * RFC 9421 signature wins (all AITs on one request must share the same `cnf` key, so the PoP
+ * signature is checked once against the winning key).
+ */
+declare const verifyAit: (ctx: VerifyRequestContext, opts: VerifyAitOptions) => Promise<VerifyAitResult>;
+
+/**
+ * Framework-agnostic AIP gate orchestration.
+ *
+ * `verifyAitRequest` is the one call a framework adapter makes: hand it a standard `Request`
+ * plus a {@link JwksCache}, and it returns the verified AIT claims or a typed failure. The
+ * helpers here also map that failure onto the AIP wire contract — HTTP status + error code +
+ * an RFC 9457 problem-details body — so every adapter renders denials identically.
+ *
+ * This layer does identity *verification* only (is this a real, key-bound AIT from a trusted
+ * IdP?). Policy enrichment — sanctions, jurisdiction, cross-merchant graph — happens when the
+ * merchant additionally feeds the verified claims to `/v1/assess`; that's the gate's choice,
+ * not something this module forces.
+ */
+
+interface AipGateOptions {
+    jwks: JwksCache;
+    now?: number;
+    maxSkewSeconds?: number;
+    /** Expected `@authority` (public hostname) the RFC 9421 signature must cover. When set, the
+     *  verifier binds the signature to this value instead of trusting the inbound `Host` header —
+     *  pin it to your real public host (e.g. `'wine.example.com'`) when behind a proxy or
+     *  multi-vhost listener that does not normalize `Host`, to prevent a captured AIT+signature
+     *  from being replayed to a different virtual host on the same origin. Same semantics as
+     *  Checkout's `AipGateConfig.authority`. */
+    authority?: string;
+    /** Minimum `trust_level` (autonomous < human_present < human_confirmed) the AIT must assert —
+     *  the spec's human-presence gate. Insufficient → 403 weak_auth with `required_trust_level`.
+     *  Enforced by {@link evaluateAipRequest} / {@link evaluateAipParts}. Unset = any trust level. */
+    requireTrustLevel?: TrustLevel;
+    /** Acceptable `auth.amr` methods (RFC 8176); the AIT must carry ≥1. Insufficient → 403 weak_auth
+     *  with `required_amr`. Unset = not enforced. */
+    requireAmr?: string[];
+    /** Identity claims the endpoint needs — surfaced as `required_claims` on insufficient_claims
+     *  denials so the agent can self-correct. Advisory only (enforce by feeding the verified claims
+     *  to your own policy / `/v1/assess`; this gate does identity + trust_level/amr). */
+    requiredClaims?: string[];
+    /** Trusted issuer URLs surfaced as `trusted_issuers` on untrusted_issuer denials. */
+    trustedIssuers?: string[];
+}
+type AipGateResult = {
+    ok: true;
+    ait: VerifiedAit;
+} | {
+    ok: false;
+    failure: VerifyAitFailure;
+};
+/** Verify the AIP credential on a standard Fetch `Request` (Hono / Web / Next.js). */
+declare const verifyAitRequest: (req: Request, opts: AipGateOptions) => Promise<AipGateResult>;
+/** Map an internal verify failure to the AIP wire error code (per spec error taxonomy). */
+declare const aipErrorCode: (failure: VerifyAitFailure) => string;
+/** HTTP status for an AIP verify failure: 503 when our infra couldn't reach the IdP (retryable),
+ *  403 for trust/claims, 401 for auth-presence/signature. */
+declare const aipErrorStatus: (failure: VerifyAitFailure) => 401 | 403 | 503;
+/** RFC 9457 problem-details body for an AIP denial. Known fields are typed; `required_*` /
+ *  `trusted_issuers` escalation extensions ride in the index signature. */
+type AipErrorBody = {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    [k: string]: unknown;
+};
+/** Merchant requirements attached to an AIP escalation body so the agent can self-correct. */
+interface AipErrorRequirements {
+    trustedIssuers?: string[];
+    requiredClaims?: string[];
+    requiredTrustLevel?: TrustLevel;
+    requiredAmr?: string[];
+}
+/**
+ * Build an RFC 9457 problem-details body for an AIP verify failure. Adapters serialize this as
+ * `application/problem+json` with {@link aipErrorStatus}. Optionally carries the merchant's
+ * requirements — `trusted_issuers` on untrusted_issuer; `required_claims` / `required_trust_level` /
+ * `required_amr` on insufficient_claims — so the agent learns what would satisfy the gate.
+ */
+declare const buildAipErrorBody: (failure: VerifyAitFailure, requirements?: AipErrorRequirements) => AipErrorBody;
+/**
+ * Check a verified AIT against the gate's `trust_level` / `auth.amr` requirements (the spec's
+ * human-presence gate). Returns a detail string when insufficient (→ weak_auth), else null.
+ */
+declare const checkTrustRequirements: (payload: {
+    trust_level?: string | undefined;
+    auth?: {
+        amr?: string[] | undefined;
+    } | undefined;
+}, requiredTrustLevel?: TrustLevel, requiredAmr?: string[]) => string | null;
+/** Build an RFC 9457 `weak_auth` body for a token that failed the trust_level / auth.amr gate. */
+declare const buildAipWeakAuthBody: (opts: {
+    detail: string;
+    requiredTrustLevel?: TrustLevel;
+    requiredAmr?: string[];
+    trustedIssuers?: string[];
+}) => AipErrorBody;
+/** A verified AIT, or a ready-to-render RFC 9457 denial body (HTTP status on `body.status`). */
+type AipGateEvaluation = {
+    ok: true;
+    ait: VerifiedAit;
+} | {
+    ok: false;
+    body: AipErrorBody;
+};
+/** Verify + trust-enforce on a standard Fetch `Request` (Hono / Web / Next.js adapters). */
+declare const evaluateAipRequest: (req: Request, opts: AipGateOptions) => Promise<AipGateEvaluation>;
+/** Verify + trust-enforce from Express/Fastify-style parts (Node header map + method + url). */
+declare const evaluateAipParts: (parts: {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    authority?: string;
+}, opts: AipGateOptions) => Promise<AipGateEvaluation>;
+
+export { AGENTSCORE_CANONICAL_ISSUER as A, HARD_MAX_CACHE_SECONDS as H, JWKS_WELL_KNOWN_PATH as J, type VerifiedAit as V, AGENT_IDENTITY_HEADER as a, type AipErrorRequirements as b, type AipGateEvaluation as c, type AipGateOptions as d, type AipGateResult as e, JwksCache as f, type JwksCacheOptions as g, type JwksLookupResult as h, type VerifyAitFailure as i, type VerifyAitOptions as j, type VerifyAitResult as k, type VerifyRequestContext as l, aipErrorCode as m, aipErrorStatus as n, buildAipErrorBody as o, buildAipWeakAuthBody as p, canonicalizeIssuer as q, checkTrustRequirements as r, evaluateAipParts as s, evaluateAipRequest as t, verifyAitRequest as u, verifyAit as v };

package/dist/gate-GCXy4FHI.d.mts

@@ -0,0 +1,307 @@
+import { a as AitPayload, T as TrustLevel } from './types-D1slMt0H.mjs';
+import { JWK } from 'jose';
+
+/**
+ * AIP IdP key discovery: fetch, cache, and select JWKS signing keys.
+ *
+ * Verifiers resolve an IdP's public keys from `https://{iss}/.well-known/agent-identity/jwks.json`
+ * (the spec's well-known path). This module owns:
+ *
+ *   - **Trusted-issuer enforcement** — only `iss` values on the allowlist are fetched, compared
+ *     after URL canonicalization (lowercase scheme+host, no default port, no trailing slash) so
+ *     `https://issuer.example` and `https://issuer.example/` match.
+ *   - **HTTPS-only** — JWKS over plain HTTP is MITM-vulnerable; we refuse it.
+ *   - **Caching with a HARD cap** — we honor `Cache-Control: max-age` as advisory but never
+ *     cache longer than {@link HARD_MAX_CACHE_SECONDS}, regardless of what the IdP sends. A
+ *     compromised IdP can't pin stale keys with `max-age=31536000`.
+ *   - **kid-miss refresh** — a lookup for a `kid` not in the cached set triggers one refetch
+ *     (rotation may have published a new key inside the cache window).
+ *   - **use:"sig" filtering** — only signing keys are returned.
+ *
+ * Pure-ish: the only I/O is `fetch`, injectable for tests.
+ */
+
+/** The spec's well-known JWKS path, relative to the issuer origin. */
+declare const JWKS_WELL_KNOWN_PATH = "/.well-known/agent-identity/jwks.json";
+/** Hard ceiling on cache age, regardless of IdP-supplied Cache-Control. */
+declare const HARD_MAX_CACHE_SECONDS = 86400;
+type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+}>;
+/** AgentScore's own AIT issuer. ALWAYS trusted by every {@link JwksCache} (and therefore every
+ *  gate/adapter built on it) without the merchant listing it — this SDK is the AgentScore
+ *  verifier, so a merchant can't accidentally fail to trust AgentScore-issued AITs. `trustedIssuers`
+ *  only needs to name ADDITIONAL external issuers. */
+declare const AGENTSCORE_CANONICAL_ISSUER = "https://www.agentscore.com";
+interface JwksCacheOptions {
+    /** ADDITIONAL external issuer URLs to trust beyond AgentScore's own (compared after
+     *  canonicalization). AgentScore's canonical issuer is always trusted; omit/empty to accept
+     *  only AgentScore-issued AITs. */
+    trustedIssuers?: string[];
+    /** Injectable fetch (defaults to global fetch). */
+    fetchImpl?: FetchLike;
+    /** Injectable clock (ms), for tests. */
+    now?: () => number;
+    /** User-Agent for JWKS requests. */
+    userAgent?: string;
+}
+type JwksLookupFailure = 'untrusted_issuer' | 'insecure_issuer' | 'fetch_failed' | 'malformed_jwks' | 'key_not_found';
+type JwksLookupResult = {
+    ok: true;
+    key: JWK;
+} | {
+    ok: false;
+    reason: JwksLookupFailure;
+};
+/**
+ * Canonicalize an issuer URL for trust-list comparison: lowercase scheme + host, drop the
+ * default port for the scheme, strip a trailing slash on an empty path. Returns null if the
+ * input is not a parseable absolute URL.
+ */
+declare const canonicalizeIssuer: (iss: string) => string | null;
+/**
+ * JWKS resolver bound to a trusted-issuer allowlist. One instance can serve many issuers;
+ * each issuer's key set is cached independently.
+ */
+declare class JwksCache {
+    private readonly trusted;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly userAgent;
+    private readonly cache;
+    /** Per-issuer in-flight refresh promise — coalesces concurrent refreshes to ONE upstream fetch.
+     *  Without it, a concurrent burst of distinct-kid lookups on a cold/expired cache each call
+     *  `refresh()` before any has populated the cache → N parallel JWKS GETs (refetch amplification).
+     *  The cooldown only suppresses SEQUENTIAL refetches; single-flight suppresses CONCURRENT ones.
+     *  Entry is cleared in a `finally` once the fetch settles. */
+    private readonly inflight;
+    constructor(opts: JwksCacheOptions);
+    /** Is this issuer on the canonicalized trust list? */
+    isTrusted(iss: string): boolean;
+    /**
+     * Resolve the signing key for `(iss, kid)`. Enforces trust + HTTPS, serves from cache when
+     * fresh, and refetches once on a kid-miss before giving up.
+     */
+    getKey(iss: string, kid: string | undefined): Promise<JwksLookupResult>;
+    private select;
+    /**
+     * Refresh the cached key set for `canonIssuer`, coalescing concurrent callers onto a single
+     * upstream fetch (single-flight). The first caller for an issuer with no in-flight refresh kicks
+     * off the fetch and registers the promise; concurrent callers await that same promise instead of
+     * issuing their own GET. The entry is cleared once the fetch settles so the NEXT cold/expired
+     * lookup can refresh again.
+     */
+    private refresh;
+    private fetchAndCache;
+    /** Stamp the per-issuer refetch cooldown on a FAILED fetch attempt (the negative cache). Any
+     *  previously cached keys + expiry are preserved — a failed kid-miss refetch must not nuke a
+     *  still-fresh key set; only the cooldown and failure reason are updated. */
+    private stampFailure;
+}
+
+/**
+ * AIP Agent Identity Token (AIT) verification pipeline — the verifier orchestrator.
+ *
+ * This is the function a merchant gate calls. It executes the spec's verification steps over
+ * a presented request, composing the three foundation modules:
+ *   - {@link ./jwks}        — trusted-issuer enforcement + key discovery
+ *   - {@link ./http-signature} — RFC 9421 proof-of-possession over the request
+ *   - {@link ./types}       — AIT structural contract
+ *
+ * Steps (per spec):
+ *   1. read the `Agent-Identity` header (one or more)
+ *   2. decode the JWT header (`kid`) + payload; confirm AIT shape (`cnf` + `agent`)
+ *   3. resolve the IdP's signing key from its JWKS (trusted-issuer + HTTPS enforced)
+ *   4. verify the IdP signature on the JWT (reject `alg:none`; key is Ed25519)
+ *   5. check `exp` / `iat` with skew
+ *   6. extract `cnf.jwk`
+ *   7. verify the RFC 9421 HTTP Message Signature with `cnf.jwk`
+ *   8. confirm the signature `keyid` == JWK thumbprint of `cnf.jwk`  (done inside step 7)
+ *
+ * On success it returns the validated, signature-checked claims. On failure it returns a
+ * typed reason that maps onto AIP's wire error codes (the gate turns these into 401/403).
+ */
+
+/** Header that carries the AIT JWT. */
+declare const AGENT_IDENTITY_HEADER = "agent-identity";
+/** Request fields the verifier needs. Framework-agnostic; adapters map their req onto this. */
+interface VerifyRequestContext {
+    method: string;
+    authority: string;
+    path: string;
+    /** All `Agent-Identity` header values present on the request (one per IdP). */
+    agentIdentityHeaders: string[];
+    signatureInput: string | null;
+    signature: string | null;
+}
+interface VerifyAitOptions {
+    jwks: JwksCache;
+    now?: number;
+    maxSkewSeconds?: number;
+    /** Max accepted AIT lifetime (`exp - iat`) in seconds. Defense-in-depth vs an external issuer
+     *  minting a long-lived bearer credential. The spec recommends a 60–300s window; default 300 so a
+     *  stolen AIT's usable window stays short even at the edge (standalone `aipGate`, no `/v1/assess`).
+     *  Our own mint is 300s, so first-party tokens sit exactly at the ceiling. Matches the
+     *  authoritative API verifier's default (the AgentScore API verifier), lowered from 3600. */
+    maxLifetimeSeconds?: number;
+}
+/**
+ * Failure reasons, aligned with AIP wire error codes. The gate maps:
+ *   no_token / malformed_token / invalid_signature / expired_token  → 401
+ *   untrusted_issuer / weak_auth / invalid_claims                   → 403
+ */
+type VerifyAitFailure = 'no_token' | 'malformed_token' | 'untrusted_issuer' | 'key_unavailable' | 'idp_signature_invalid' | 'expired_token' | 'invalid_claims' | 'pop_signature_missing' | 'pop_signature_invalid';
+interface VerifiedAit {
+    payload: AitPayload;
+    /** The issuer (canonical, as presented). */
+    iss: string;
+    /** The agent's bound public key (`cnf.jwk`). */
+    cnfJwk: AitPayload['cnf']['jwk'];
+    /** The raw JWT string that verified (the winning `Agent-Identity` header value, Bearer
+     *  prefix stripped). Lets a gate forward the exact token to `/v1/assess` as `aip_token`. */
+    token: string;
+    /** The RFC 9421 signature material for this request — forwarded to `/v1/assess` as
+     *  `aip_signature` so the API re-verifies proof-of-possession authoritatively (the edge
+     *  check here is only a fail-fast filter; the API is the source of truth). */
+    signatureMaterial: {
+        method: string;
+        authority: string;
+        path: string;
+        signature_input: string;
+        signature: string;
+    };
+}
+type VerifyAitResult = {
+    ok: true;
+    ait: VerifiedAit;
+} | {
+    ok: false;
+    reason: VerifyAitFailure;
+};
+/**
+ * Verify the AIP credential on a request. When multiple `Agent-Identity` headers are present,
+ * each is tried; the first that fully verifies AND whose `cnf.jwk` matches the request's
+ * RFC 9421 signature wins (all AITs on one request must share the same `cnf` key, so the PoP
+ * signature is checked once against the winning key).
+ */
+declare const verifyAit: (ctx: VerifyRequestContext, opts: VerifyAitOptions) => Promise<VerifyAitResult>;
+
+/**
+ * Framework-agnostic AIP gate orchestration.
+ *
+ * `verifyAitRequest` is the one call a framework adapter makes: hand it a standard `Request`
+ * plus a {@link JwksCache}, and it returns the verified AIT claims or a typed failure. The
+ * helpers here also map that failure onto the AIP wire contract — HTTP status + error code +
+ * an RFC 9457 problem-details body — so every adapter renders denials identically.
+ *
+ * This layer does identity *verification* only (is this a real, key-bound AIT from a trusted
+ * IdP?). Policy enrichment — sanctions, jurisdiction, cross-merchant graph — happens when the
+ * merchant additionally feeds the verified claims to `/v1/assess`; that's the gate's choice,
+ * not something this module forces.
+ */
+
+interface AipGateOptions {
+    jwks: JwksCache;
+    now?: number;
+    maxSkewSeconds?: number;
+    /** Expected `@authority` (public hostname) the RFC 9421 signature must cover. When set, the
+     *  verifier binds the signature to this value instead of trusting the inbound `Host` header —
+     *  pin it to your real public host (e.g. `'wine.example.com'`) when behind a proxy or
+     *  multi-vhost listener that does not normalize `Host`, to prevent a captured AIT+signature
+     *  from being replayed to a different virtual host on the same origin. Same semantics as
+     *  Checkout's `AipGateConfig.authority`. */
+    authority?: string;
+    /** Minimum `trust_level` (autonomous < human_present < human_confirmed) the AIT must assert —
+     *  the spec's human-presence gate. Insufficient → 403 weak_auth with `required_trust_level`.
+     *  Enforced by {@link evaluateAipRequest} / {@link evaluateAipParts}. Unset = any trust level. */
+    requireTrustLevel?: TrustLevel;
+    /** Acceptable `auth.amr` methods (RFC 8176); the AIT must carry ≥1. Insufficient → 403 weak_auth
+     *  with `required_amr`. Unset = not enforced. */
+    requireAmr?: string[];
+    /** Identity claims the endpoint needs — surfaced as `required_claims` on insufficient_claims
+     *  denials so the agent can self-correct. Advisory only (enforce by feeding the verified claims
+     *  to your own policy / `/v1/assess`; this gate does identity + trust_level/amr). */
+    requiredClaims?: string[];
+    /** Trusted issuer URLs surfaced as `trusted_issuers` on untrusted_issuer denials. */
+    trustedIssuers?: string[];
+}
+type AipGateResult = {
+    ok: true;
+    ait: VerifiedAit;
+} | {
+    ok: false;
+    failure: VerifyAitFailure;
+};
+/** Verify the AIP credential on a standard Fetch `Request` (Hono / Web / Next.js). */
+declare const verifyAitRequest: (req: Request, opts: AipGateOptions) => Promise<AipGateResult>;
+/** Map an internal verify failure to the AIP wire error code (per spec error taxonomy). */
+declare const aipErrorCode: (failure: VerifyAitFailure) => string;
+/** HTTP status for an AIP verify failure: 503 when our infra couldn't reach the IdP (retryable),
+ *  403 for trust/claims, 401 for auth-presence/signature. */
+declare const aipErrorStatus: (failure: VerifyAitFailure) => 401 | 403 | 503;
+/** RFC 9457 problem-details body for an AIP denial. Known fields are typed; `required_*` /
+ *  `trusted_issuers` escalation extensions ride in the index signature. */
+type AipErrorBody = {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+    [k: string]: unknown;
+};
+/** Merchant requirements attached to an AIP escalation body so the agent can self-correct. */
+interface AipErrorRequirements {
+    trustedIssuers?: string[];
+    requiredClaims?: string[];
+    requiredTrustLevel?: TrustLevel;
+    requiredAmr?: string[];
+}
+/**
+ * Build an RFC 9457 problem-details body for an AIP verify failure. Adapters serialize this as
+ * `application/problem+json` with {@link aipErrorStatus}. Optionally carries the merchant's
+ * requirements — `trusted_issuers` on untrusted_issuer; `required_claims` / `required_trust_level` /
+ * `required_amr` on insufficient_claims — so the agent learns what would satisfy the gate.
+ */
+declare const buildAipErrorBody: (failure: VerifyAitFailure, requirements?: AipErrorRequirements) => AipErrorBody;
+/**
+ * Check a verified AIT against the gate's `trust_level` / `auth.amr` requirements (the spec's
+ * human-presence gate). Returns a detail string when insufficient (→ weak_auth), else null.
+ */
+declare const checkTrustRequirements: (payload: {
+    trust_level?: string | undefined;
+    auth?: {
+        amr?: string[] | undefined;
+    } | undefined;
+}, requiredTrustLevel?: TrustLevel, requiredAmr?: string[]) => string | null;
+/** Build an RFC 9457 `weak_auth` body for a token that failed the trust_level / auth.amr gate. */
+declare const buildAipWeakAuthBody: (opts: {
+    detail: string;
+    requiredTrustLevel?: TrustLevel;
+    requiredAmr?: string[];
+    trustedIssuers?: string[];
+}) => AipErrorBody;
+/** A verified AIT, or a ready-to-render RFC 9457 denial body (HTTP status on `body.status`). */
+type AipGateEvaluation = {
+    ok: true;
+    ait: VerifiedAit;
+} | {
+    ok: false;
+    body: AipErrorBody;
+};
+/** Verify + trust-enforce on a standard Fetch `Request` (Hono / Web / Next.js adapters). */
+declare const evaluateAipRequest: (req: Request, opts: AipGateOptions) => Promise<AipGateEvaluation>;
+/** Verify + trust-enforce from Express/Fastify-style parts (Node header map + method + url). */
+declare const evaluateAipParts: (parts: {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+    authority?: string;
+}, opts: AipGateOptions) => Promise<AipGateEvaluation>;
+
+export { AGENTSCORE_CANONICAL_ISSUER as A, HARD_MAX_CACHE_SECONDS as H, JWKS_WELL_KNOWN_PATH as J, type VerifiedAit as V, AGENT_IDENTITY_HEADER as a, type AipErrorRequirements as b, type AipGateEvaluation as c, type AipGateOptions as d, type AipGateResult as e, JwksCache as f, type JwksCacheOptions as g, type JwksLookupResult as h, type VerifyAitFailure as i, type VerifyAitOptions as j, type VerifyAitResult as k, type VerifyRequestContext as l, aipErrorCode as m, aipErrorStatus as n, buildAipErrorBody as o, buildAipWeakAuthBody as p, canonicalizeIssuer as q, checkTrustRequirements as r, evaluateAipParts as s, evaluateAipRequest as t, verifyAitRequest as u, verifyAit as v };

package/dist/identity/express.d.mts

@@ -1,5 +1,9 @@
+import { d as AipGateOptions, o as buildAipErrorBody, V as VerifiedAit } from '../gate-GCXy4FHI.mjs';
 import { AgentScoreCoreOptions, AgentIdentity, DenialReason, CreateSessionOnMissing, AssessResult, FailOpenInfraReason, GateQuotaInfo, SignerVerdict } from '../core.mjs';
 import { Request, Response, NextFunction } from 'express';
+import '../types-D1slMt0H.mjs';
+import 'jose';
+import '@agent-score/sdk';
 import '../signer-3FAit11j.mjs';
 
 interface AgentScoreGateOptions extends Omit<AgentScoreCoreOptions, 'createSessionOnMissing'> {
@@ -60,5 +64,28 @@ declare function getSignerVerdict(req: Request): SignerVerdict | undefined;
  *  unauthenticated and the handler emits a 402 with all rails; settle legs
  *  trigger the full gate. */
 declare function conditionalAgentscoreGate(options: AgentScoreGateOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+interface AipGateExpressOptions extends AipGateOptions {
+    /** Custom denial responder. Defaults to a 401/403 `application/problem+json` body. */
+    onDenied?: (req: Request, res: Response, body: ReturnType<typeof buildAipErrorBody>) => void;
+}
+/**
+ * Express middleware that requires a valid AIT on every request it guards.
+ *
+ * ```ts
+ * import { JwksCache } from '@agent-score/commerce';
+ * import { aipGate, getVerifiedAit } from '@agent-score/commerce/identity/express';
+ *
+ * const jwks = new JwksCache({ trustedIssuers: ['https://issuer.example'] }); // AgentScore always trusted
+ * app.post('/checkout', aipGate({ jwks }), (req, res) => {
+ *   const ait = getVerifiedAit(req)!;
+ *   res.json({ buyer: ait.payload.identity?.email });
+ * });
+ * ```
+ */
+declare function aipGate(options: AipGateExpressOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/** Wrap {@link aipGate} so it only runs when an `Agent-Identity` header is present. */
+declare function conditionalAipGate(options: AipGateExpressOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/** Read the verified AIT attached to an Express request by {@link aipGate}. */
+declare function getVerifiedAit(req: Request): VerifiedAit | undefined;
 
-export { agentscoreGate, captureWallet, conditionalAgentscoreGate, getAgentScoreData, getGateDegradedState, getGateQuotaInfo, getSignerVerdict };
+export { type AipGateExpressOptions, agentscoreGate, aipGate, captureWallet, conditionalAgentscoreGate, conditionalAipGate, getAgentScoreData, getGateDegradedState, getGateQuotaInfo, getSignerVerdict, getVerifiedAit };