@agent-score/commerce 2.4.0 → 2.5.0

package/dist/gate-CWP10xPQ.d.mts

@@ -0,0 +1,339 @@
+import { JWK } from 'jose';
+
+/**
+ * AIP (Agentic Identity Protocol) token types and the claim contract.
+ *
+ * An Agent Identity Token (AIT) is a JWT signed by an Identity Provider (IdP). It binds a
+ * verified human's identity to the specific agent presenting it (via `cnf`, RFC 7800) and
+ * carries the trust level, authentication method, optional intent, and optional identity
+ * claims the IdP attests to.
+ *
+ * This module is the single source of truth for the claim shape on the verifier side. It
+ * encodes the spec's required / recommended / optional claims plus the AgentScore extension
+ * claims (sanctions, jurisdiction, structured id-verification, cross-merchant graph, payment
+ * signer) we carry when we act as a compliance IdP.
+ *
+ * Extensibility contract (per spec): the `identity` object is open. If a claim is present,
+ * the IdP attests to it; verifiers ignore claims they don't recognize. Absence is the
+ * "unknown" signal — IdPs do not ship `null` for "not checked".
+ */
+
+/** Degree of human involvement in issuing this specific AIT. */
+type TrustLevel = 'autonomous' | 'human_present' | 'human_confirmed';
+/**
+ * Authentication Method Reference values (RFC 8176 / IANA AMR registry). Open set — these
+ * are the values relevant to agent identity; others are valid and pass through.
+ */
+type AmrValue = 'face' | 'fpt' | 'hwk' | 'otp' | 'pin' | 'pwd' | 'sms' | 'swk' | 'user' | 'mfa';
+/** RFC 7800 confirmation claim: binds the AIT to the agent's signing key. */
+interface CnfClaim {
+    jwk: JWK;
+}
+/** Agent metadata. `provider` is required; `instance` is recommended. */
+interface AgentClaim {
+    provider: string;
+    instance?: string;
+}
+/** How the user authorized THIS AIT (not prior authentication history). */
+interface AuthClaim {
+    amr?: AmrValue[] | string[];
+    /** When the user authenticated for this token (Unix seconds). Mirrors OIDC `auth_time`. */
+    time?: number;
+}
+/** What the agent intends to do. Optional; verifiers may require it for non-read actions. */
+interface IntentClaim {
+    actions?: string[];
+    description?: string;
+}
+/** AgentScore wallet-binding extension (orthogonal to `cnf`, which binds the agent key). */
+interface PaymentSignerClaim {
+    address: string;
+    network: 'evm' | 'solana';
+    /** Relationship the IdP attests between signer and the operator graph. */
+    match?: 'linked_operator' | 'claimed_operator';
+}
+interface PaymentClaim {
+    signer?: PaymentSignerClaim;
+}
+/**
+ * Identity claims (presence == IdP attestation). Spec-defined fields plus AgentScore
+ * compliance extension claims. Open by contract — unknown fields are allowed and ignored.
+ */
+interface IdentityClaim {
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    phone?: string;
+    phone_verified?: boolean;
+    age_over_18?: boolean;
+    age_over_21?: boolean;
+    id_verified?: boolean;
+    id_verification?: {
+        provider?: string;
+        method?: string;
+        document_type?: string;
+        verified_at?: number;
+    };
+    /** ISO 3166-1 alpha-2, optionally with ISO 3166-2 subdivision (e.g. "US-CA"). */
+    jurisdiction?: string;
+    sanctions_clear?: boolean;
+    sanctions_checked_at?: number;
+    sanctions_providers?: string[];
+    linked_wallets?: Array<{
+        address: string;
+        network: 'evm' | 'solana';
+    }>;
+    merchants_paid?: number;
+    first_seen?: number;
+    [claim: string]: unknown;
+}
+/** The decoded AIT JWT payload. */
+interface AitPayload {
+    aip_version: string;
+    iss: string;
+    sub: string;
+    iat: number;
+    exp: number;
+    cnf: CnfClaim;
+    agent: AgentClaim;
+    trust_level?: TrustLevel;
+    auth?: AuthClaim;
+    intent?: IntentClaim;
+    identity?: IdentityClaim;
+    payment?: PaymentClaim;
+    [claim: string]: unknown;
+}
+/** The decoded AIT JWT header. */
+interface AitHeader {
+    alg: string;
+    typ?: string;
+    kid?: string;
+    [param: string]: unknown;
+}
+/**
+ * Structural validation of a decoded AIT payload. Confirms the required claims are present
+ * and well-typed, and enforces the one normative conditional in the spec: a
+ * `human_confirmed` token MUST carry at least one `auth.amr` value.
+ *
+ * This is shape/contract validation only — it does NOT verify signatures (that's the
+ * verifier pipeline) and does NOT apply trust policy (that's the gate / `/v1/assess`).
+ */
+type AitValidationResult = {
+    ok: true;
+    payload: AitPayload;
+} | {
+    ok: false;
+    reason: AitValidationFailure;
+};
+type AitValidationFailure = 'not_an_object' | 'missing_aip_version' | 'missing_iss' | 'missing_sub' | 'missing_iat' | 'missing_exp' | 'missing_cnf' | 'missing_agent_provider' | 'human_confirmed_without_amr';
+/**
+ * Detect whether a decoded JWT payload is an AIT: per spec, an AIT is discriminated by the
+ * presence of `cnf` + `agent` claims (not the `typ` header).
+ */
+declare const isAitShape: (payload: unknown) => boolean;
+/** Validate the structural contract of a decoded AIT payload. */
+declare const validateAitPayload: (payload: unknown) => AitValidationResult;
+
+/**
+ * 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://agentscore.sh";
+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;
+    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;
+    private refresh;
+}
+
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+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;
+}
+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;
+/**
+ * Build an RFC 9457 problem-details body for an AIP verify failure. Adapters serialize this
+ * as `application/problem+json` with {@link aipErrorStatus}.
+ */
+declare const buildAipErrorBody: (failure: VerifyAitFailure) => {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+};
+
+export { AGENTSCORE_CANONICAL_ISSUER as A, HARD_MAX_CACHE_SECONDS as H, type IdentityClaim as I, JWKS_WELL_KNOWN_PATH as J, type TrustLevel as T, type VerifiedAit as V, AGENT_IDENTITY_HEADER as a, type AipGateOptions as b, type AipGateResult as c, type AitHeader as d, type AitPayload as e, type AitValidationResult as f, type AmrValue as g, type IntentClaim as h, JwksCache as i, type JwksCacheOptions as j, type JwksLookupResult as k, type VerifyAitFailure as l, type VerifyAitOptions as m, type VerifyAitResult as n, type VerifyRequestContext as o, aipErrorCode as p, aipErrorStatus as q, buildAipErrorBody as r, canonicalizeIssuer as s, isAitShape as t, verifyAit as u, validateAitPayload as v, verifyAitRequest as w };

package/dist/gate-CWP10xPQ.d.ts

@@ -0,0 +1,339 @@
+import { JWK } from 'jose';
+
+/**
+ * AIP (Agentic Identity Protocol) token types and the claim contract.
+ *
+ * An Agent Identity Token (AIT) is a JWT signed by an Identity Provider (IdP). It binds a
+ * verified human's identity to the specific agent presenting it (via `cnf`, RFC 7800) and
+ * carries the trust level, authentication method, optional intent, and optional identity
+ * claims the IdP attests to.
+ *
+ * This module is the single source of truth for the claim shape on the verifier side. It
+ * encodes the spec's required / recommended / optional claims plus the AgentScore extension
+ * claims (sanctions, jurisdiction, structured id-verification, cross-merchant graph, payment
+ * signer) we carry when we act as a compliance IdP.
+ *
+ * Extensibility contract (per spec): the `identity` object is open. If a claim is present,
+ * the IdP attests to it; verifiers ignore claims they don't recognize. Absence is the
+ * "unknown" signal — IdPs do not ship `null` for "not checked".
+ */
+
+/** Degree of human involvement in issuing this specific AIT. */
+type TrustLevel = 'autonomous' | 'human_present' | 'human_confirmed';
+/**
+ * Authentication Method Reference values (RFC 8176 / IANA AMR registry). Open set — these
+ * are the values relevant to agent identity; others are valid and pass through.
+ */
+type AmrValue = 'face' | 'fpt' | 'hwk' | 'otp' | 'pin' | 'pwd' | 'sms' | 'swk' | 'user' | 'mfa';
+/** RFC 7800 confirmation claim: binds the AIT to the agent's signing key. */
+interface CnfClaim {
+    jwk: JWK;
+}
+/** Agent metadata. `provider` is required; `instance` is recommended. */
+interface AgentClaim {
+    provider: string;
+    instance?: string;
+}
+/** How the user authorized THIS AIT (not prior authentication history). */
+interface AuthClaim {
+    amr?: AmrValue[] | string[];
+    /** When the user authenticated for this token (Unix seconds). Mirrors OIDC `auth_time`. */
+    time?: number;
+}
+/** What the agent intends to do. Optional; verifiers may require it for non-read actions. */
+interface IntentClaim {
+    actions?: string[];
+    description?: string;
+}
+/** AgentScore wallet-binding extension (orthogonal to `cnf`, which binds the agent key). */
+interface PaymentSignerClaim {
+    address: string;
+    network: 'evm' | 'solana';
+    /** Relationship the IdP attests between signer and the operator graph. */
+    match?: 'linked_operator' | 'claimed_operator';
+}
+interface PaymentClaim {
+    signer?: PaymentSignerClaim;
+}
+/**
+ * Identity claims (presence == IdP attestation). Spec-defined fields plus AgentScore
+ * compliance extension claims. Open by contract — unknown fields are allowed and ignored.
+ */
+interface IdentityClaim {
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    phone?: string;
+    phone_verified?: boolean;
+    age_over_18?: boolean;
+    age_over_21?: boolean;
+    id_verified?: boolean;
+    id_verification?: {
+        provider?: string;
+        method?: string;
+        document_type?: string;
+        verified_at?: number;
+    };
+    /** ISO 3166-1 alpha-2, optionally with ISO 3166-2 subdivision (e.g. "US-CA"). */
+    jurisdiction?: string;
+    sanctions_clear?: boolean;
+    sanctions_checked_at?: number;
+    sanctions_providers?: string[];
+    linked_wallets?: Array<{
+        address: string;
+        network: 'evm' | 'solana';
+    }>;
+    merchants_paid?: number;
+    first_seen?: number;
+    [claim: string]: unknown;
+}
+/** The decoded AIT JWT payload. */
+interface AitPayload {
+    aip_version: string;
+    iss: string;
+    sub: string;
+    iat: number;
+    exp: number;
+    cnf: CnfClaim;
+    agent: AgentClaim;
+    trust_level?: TrustLevel;
+    auth?: AuthClaim;
+    intent?: IntentClaim;
+    identity?: IdentityClaim;
+    payment?: PaymentClaim;
+    [claim: string]: unknown;
+}
+/** The decoded AIT JWT header. */
+interface AitHeader {
+    alg: string;
+    typ?: string;
+    kid?: string;
+    [param: string]: unknown;
+}
+/**
+ * Structural validation of a decoded AIT payload. Confirms the required claims are present
+ * and well-typed, and enforces the one normative conditional in the spec: a
+ * `human_confirmed` token MUST carry at least one `auth.amr` value.
+ *
+ * This is shape/contract validation only — it does NOT verify signatures (that's the
+ * verifier pipeline) and does NOT apply trust policy (that's the gate / `/v1/assess`).
+ */
+type AitValidationResult = {
+    ok: true;
+    payload: AitPayload;
+} | {
+    ok: false;
+    reason: AitValidationFailure;
+};
+type AitValidationFailure = 'not_an_object' | 'missing_aip_version' | 'missing_iss' | 'missing_sub' | 'missing_iat' | 'missing_exp' | 'missing_cnf' | 'missing_agent_provider' | 'human_confirmed_without_amr';
+/**
+ * Detect whether a decoded JWT payload is an AIT: per spec, an AIT is discriminated by the
+ * presence of `cnf` + `agent` claims (not the `typ` header).
+ */
+declare const isAitShape: (payload: unknown) => boolean;
+/** Validate the structural contract of a decoded AIT payload. */
+declare const validateAitPayload: (payload: unknown) => AitValidationResult;
+
+/**
+ * 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://agentscore.sh";
+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;
+    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;
+    private refresh;
+}
+
+/**
+ * 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;
+}
+/**
+ * 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;
+}
+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;
+}
+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;
+/**
+ * Build an RFC 9457 problem-details body for an AIP verify failure. Adapters serialize this
+ * as `application/problem+json` with {@link aipErrorStatus}.
+ */
+declare const buildAipErrorBody: (failure: VerifyAitFailure) => {
+    type: string;
+    title: string;
+    status: number;
+    detail: string;
+};
+
+export { AGENTSCORE_CANONICAL_ISSUER as A, HARD_MAX_CACHE_SECONDS as H, type IdentityClaim as I, JWKS_WELL_KNOWN_PATH as J, type TrustLevel as T, type VerifiedAit as V, AGENT_IDENTITY_HEADER as a, type AipGateOptions as b, type AipGateResult as c, type AitHeader as d, type AitPayload as e, type AitValidationResult as f, type AmrValue as g, type IntentClaim as h, JwksCache as i, type JwksCacheOptions as j, type JwksLookupResult as k, type VerifyAitFailure as l, type VerifyAitOptions as m, type VerifyAitResult as n, type VerifyRequestContext as o, aipErrorCode as p, aipErrorStatus as q, buildAipErrorBody as r, canonicalizeIssuer as s, isAitShape as t, verifyAit as u, validateAitPayload as v, verifyAitRequest as w };