@goodmeta/agent-verifier 0.2.0 → 0.5.0

package/dist/ap2/keys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Root-token trust anchoring: x5c (certificate chain) or kid lookup.
+ *
+ * Wire format follows AP2's `chain.py::X5cOrKidPublicKeyProvider` (H7): the x5c
+ * header is a list of **base64url**-DER certs, leaf first, `cert[i]` signed by
+ * `cert[i+1]`, and the chain is anchored when the LAST cert is signed by a
+ * trusted root that is itself NOT in the chain.
+ *
+ * Trust is STRICTER than AP2 (H2 — AP2's x5c path FAILS OPEN: with no configured
+ * roots it accepts a self-signed leaf, and it checks no validity / CA / curve /
+ * name chaining). We fail closed:
+ *   - `trustedRoots` is MANDATORY when an x5c is present (else refuse, no fail-open).
+ *   - every cert must be inside its validity window;
+ *   - each issuer cert must assert `basicConstraints CA:TRUE`;
+ *   - issuer/subject names must chain (`checkIssued`) AND signatures verify;
+ *   - the leaf must be an EC P-256 key;
+ *   - the chain must anchor to a trusted root (AP2-compatible: root not in chain).
+ *
+ * KNOWN LIMITATION: node's `X509Certificate` does not expose the basic
+ * KeyUsage / pathLenConstraint extensions (`.keyUsage` returns only EXTENDED key
+ * usage), so we cannot enforce `keyCertSign` / `digitalSignature` / pathLen
+ * without hand-parsing DER. We rely on `CA:TRUE` for the CA constraint and leave
+ * basic-keyUsage enforcement as a documented refinement (PLAN §5 H2).
+ */
+import { X509Certificate } from "node:crypto";
+import type { RootKeyProvider } from "./chain.js";
+import type { VerificationKey } from "./sd-jwt.js";
+export interface X5cKidProviderOptions {
+    /** REQUIRED whenever a root token presents an x5c header (fail-closed, H2). */
+    trustedRoots?: X509Certificate[];
+    /** Resolve a verification key by `kid` when no x5c is present. */
+    kidLookup?: (kid: string) => VerificationKey | null;
+    /** Validity-window reference time; defaults to the current time. */
+    currentTime?: Date;
+}
+/**
+ * Build a root-key provider that resolves an x5c chain (fail-closed) or, absent
+ * x5c, a `kid` via `kidLookup`. Plug into `verifyChain(tokens, provider, …)`.
+ */
+export declare function x5cOrKidProvider(opts?: X5cKidProviderOptions): RootKeyProvider;
+//# sourceMappingURL=keys.d.ts.map

package/dist/ap2/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/ap2/keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,eAAe,EAAE,CAAC;IACjC,kEAAkE;IAClE,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,eAAe,GAAG,IAAI,CAAC;IACpD,oEAAoE;IACpE,WAAW,CAAC,EAAE,IAAI,CAAC;CACpB;AA+DD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,qBAA0B,GAAG,eAAe,CAmBlF"}

package/dist/ap2/keys.js

@@ -0,0 +1,114 @@
+/**
+ * Root-token trust anchoring: x5c (certificate chain) or kid lookup.
+ *
+ * Wire format follows AP2's `chain.py::X5cOrKidPublicKeyProvider` (H7): the x5c
+ * header is a list of **base64url**-DER certs, leaf first, `cert[i]` signed by
+ * `cert[i+1]`, and the chain is anchored when the LAST cert is signed by a
+ * trusted root that is itself NOT in the chain.
+ *
+ * Trust is STRICTER than AP2 (H2 — AP2's x5c path FAILS OPEN: with no configured
+ * roots it accepts a self-signed leaf, and it checks no validity / CA / curve /
+ * name chaining). We fail closed:
+ *   - `trustedRoots` is MANDATORY when an x5c is present (else refuse, no fail-open).
+ *   - every cert must be inside its validity window;
+ *   - each issuer cert must assert `basicConstraints CA:TRUE`;
+ *   - issuer/subject names must chain (`checkIssued`) AND signatures verify;
+ *   - the leaf must be an EC P-256 key;
+ *   - the chain must anchor to a trusted root (AP2-compatible: root not in chain).
+ *
+ * KNOWN LIMITATION: node's `X509Certificate` does not expose the basic
+ * KeyUsage / pathLenConstraint extensions (`.keyUsage` returns only EXTENDED key
+ * usage), so we cannot enforce `keyCertSign` / `digitalSignature` / pathLen
+ * without hand-parsing DER. We rely on `CA:TRUE` for the CA constraint and leave
+ * basic-keyUsage enforcement as a documented refinement (PLAN §5 H2).
+ */
+import { Buffer } from "node:buffer";
+import { X509Certificate } from "node:crypto";
+const MAX_X5C_CHAIN = 8;
+function isP256(cert) {
+    const key = cert.publicKey;
+    return key.asymmetricKeyType === "ec" && key.asymmetricKeyDetails?.namedCurve === "prime256v1";
+}
+/** `validFromDate`/`validToDate` exist at runtime (Node 18.13+) but aren't in the
+ * pinned `@types/node`; fall back to parsing the string form. */
+function certDate(cert, which) {
+    const runtime = cert[which === "from" ? "validFromDate" : "validToDate"];
+    return runtime instanceof Date ? runtime : new Date(which === "from" ? cert.validFrom : cert.validTo);
+}
+function withinValidity(cert, now) {
+    return now >= certDate(cert, "from") && now <= certDate(cert, "to");
+}
+function resolveX5cKey(x5c, trustedRoots, now) {
+    if (!Array.isArray(x5c) || x5c.length === 0)
+        throw new Error("x5c header must be a non-empty array");
+    if (x5c.length > MAX_X5C_CHAIN)
+        throw new Error(`x5c chain too long (> ${MAX_X5C_CHAIN})`);
+    const certs = x5c.map((b64, i) => {
+        if (typeof b64 !== "string")
+            throw new Error(`x5c[${i}] must be a base64url string`);
+        return new X509Certificate(Buffer.from(b64, "base64url")); // base64url to match AP2's decoder
+    });
+    // Every cert must be inside its validity window.
+    certs.forEach((c, i) => {
+        if (!withinValidity(c, now))
+            throw new Error(`x5c cert ${i} is outside its validity window`);
+    });
+    // Chain links: cert[i] is signed by, and named-chained to, cert[i+1]; the
+    // issuer must be a CA.
+    for (let i = 0; i < certs.length - 1; i++) {
+        const sub = certs[i];
+        const iss = certs[i + 1];
+        if (!sub.verify(iss.publicKey))
+            throw new Error(`x5c cert ${i} signature is not from cert ${i + 1}`);
+        // CA check first: node's checkIssued also rejects a non-CA issuer, so the
+        // explicit constraint must run before it to surface the precise reason.
+        if (!iss.ca)
+            throw new Error(`x5c cert ${i + 1} is not a CA (basicConstraints CA:TRUE required)`);
+        if (!sub.checkIssued(iss))
+            throw new Error(`x5c cert ${i} does not chain (issuer name) to cert ${i + 1}`);
+    }
+    // The leaf (signing) cert must be an EC P-256 key.
+    if (!isP256(certs[0]))
+        throw new Error("x5c leaf is not an EC P-256 key");
+    // Trust anchor (H7, AP2-compatible): the last cert must be signed by some
+    // trusted root that is NOT part of the chain.
+    const last = certs[certs.length - 1];
+    const anchored = trustedRoots.some((root) => {
+        try {
+            return last.verify(root.publicKey) && last.checkIssued(root);
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!anchored)
+        throw new Error("x5c chain does not chain to a trusted root");
+    return certs[0].publicKey; // leaf public key verifies the root SD-JWT signature
+}
+/**
+ * Build a root-key provider that resolves an x5c chain (fail-closed) or, absent
+ * x5c, a `kid` via `kidLookup`. Plug into `verifyChain(tokens, provider, …)`.
+ */
+export function x5cOrKidProvider(opts = {}) {
+    const now = opts.currentTime ?? new Date();
+    return (root) => {
+        const header = root.header;
+        if ("x5c" in header) {
+            if (!opts.trustedRoots || opts.trustedRoots.length === 0) {
+                throw new Error("x5c present but no trustedRoots configured — refusing to fail open");
+            }
+            return resolveX5cKey(header["x5c"], opts.trustedRoots, now);
+        }
+        const kid = header["kid"];
+        if (typeof kid !== "string" || kid === "") {
+            throw new Error("Root token header has neither 'x5c' nor a usable 'kid'");
+        }
+        if (!opts.kidLookup)
+            throw new Error("Root token uses 'kid' but no kidLookup is configured");
+        const key = opts.kidLookup(kid);
+        if (!key)
+            throw new Error(`No key registered for kid: ${kid}`);
+        return key;
+    };
+}
+//# sourceMappingURL=keys.js.map

package/dist/ap2/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../../src/ap2/keys.ts"],"names":[],"mappings":"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"}

package/dist/ap2/max-flow.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Line-items constraint via bipartite max-flow — line-for-line port of AP2's
+ * `sdk/max_flow_helper.py` (commit e1ea56d), Dinic variant (AP2's default).
+ *
+ * A checkout satisfies a `checkout.line_items` constraint when every cart item
+ * can be assigned to a requirement slot that accepts it (an item matches if its
+ * id is in the requirement's `acceptable_items`, or the requirement is a
+ * wildcard — empty `acceptable_items`), each requirement filled up to its
+ * `quantity`, and no cart unit assigned twice. A fast greedy pass resolves
+ * degree-1 items; the remaining ambiguous ("complex") items go through max-flow.
+ * Violation strings match AP2 byte-for-byte.
+ */
+export interface CartLineItem {
+    item: {
+        id: string;
+    };
+    quantity: number;
+}
+export interface LineItemRequirement {
+    acceptable_items: {
+        id: string;
+    }[];
+    quantity: number;
+}
+export declare function evaluateLineItemsMaxFlow(checkoutItems: CartLineItem[], requirements: LineItemRequirement[]): string[];
+//# sourceMappingURL=max-flow.d.ts.map

package/dist/ap2/max-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"max-flow.d.ts","sourceRoot":"","sources":["../../src/ap2/max-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;CAClB;AACD,MAAM,WAAW,mBAAmB;IAClC,gBAAgB,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACnC,QAAQ,EAAE,MAAM,CAAC;CAClB;AAID,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,YAAY,EAAE,EAAE,YAAY,EAAE,mBAAmB,EAAE,GAAG,MAAM,EAAE,CA0ErH"}

package/dist/ap2/max-flow.js

@@ -0,0 +1,173 @@
+/**
+ * Line-items constraint via bipartite max-flow — line-for-line port of AP2's
+ * `sdk/max_flow_helper.py` (commit e1ea56d), Dinic variant (AP2's default).
+ *
+ * A checkout satisfies a `checkout.line_items` constraint when every cart item
+ * can be assigned to a requirement slot that accepts it (an item matches if its
+ * id is in the requirement's `acceptable_items`, or the requirement is a
+ * wildcard — empty `acceptable_items`), each requirement filled up to its
+ * `quantity`, and no cart unit assigned twice. A fast greedy pass resolves
+ * degree-1 items; the remaining ambiguous ("complex") items go through max-flow.
+ * Violation strings match AP2 byte-for-byte.
+ */
+const INF = 1e15;
+export function evaluateLineItemsMaxFlow(checkoutItems, requirements) {
+    const cartQty = new Map();
+    for (const li of checkoutItems) {
+        const sku = li.item.id;
+        cartQty.set(sku, (cartQty.get(sku) ?? 0) + li.quantity);
+    }
+    const skuList = [...cartQty.keys()];
+    const reqAcceptable = requirements.map((req) => req.acceptable_items.length ? new Set(req.acceptable_items.map((ai) => ai.id)) : new Set());
+    const reqIsWildcard = requirements.map((req) => req.acceptable_items.length === 0);
+    const violations = [];
+    const hasWildcard = reqIsWildcard.some(Boolean);
+    const allAcceptable = new Set();
+    if (!hasWildcard)
+        for (const acc of reqAcceptable)
+            for (const x of acc)
+                allAcceptable.add(x);
+    for (const [sku, qty] of cartQty) {
+        if (qty <= 0)
+            continue;
+        if (!hasWildcard && !allAcceptable.has(sku)) {
+            violations.push(`Item ${sku} not in any requirement's acceptable items`);
+        }
+    }
+    if (violations.length)
+        return violations;
+    // Greedy elimination of degree-1 matches.
+    const reqRemaining = requirements.map((req) => req.quantity);
+    const complexSkus = [];
+    const unassigned = [];
+    for (const sku of skuList) {
+        const qty = cartQty.get(sku);
+        if (qty <= 0)
+            continue;
+        let matchIdx = -1;
+        let isComplex = false;
+        for (let j = 0; j < requirements.length; j++) {
+            if (reqIsWildcard[j] || reqAcceptable[j].has(sku)) {
+                if (matchIdx === -1)
+                    matchIdx = j;
+                else {
+                    isComplex = true;
+                    break;
+                }
+            }
+        }
+        if (matchIdx !== -1 && !isComplex) {
+            const assigned = Math.min(qty, reqRemaining[matchIdx]);
+            reqRemaining[matchIdx] -= assigned;
+            const leftover = qty - assigned;
+            if (leftover > 0)
+                unassigned.push(`${sku} (${leftover})`);
+        }
+        else {
+            complexSkus.push(sku);
+        }
+    }
+    if (complexSkus.length) {
+        const { maxFlow, residual } = lineItemsMaxFlow(complexSkus, cartQty, requirements, reqAcceptable, reqIsWildcard, reqRemaining);
+        const totalComplexCart = complexSkus.reduce((s, sku) => s + cartQty.get(sku), 0);
+        if (maxFlow < totalComplexCart) {
+            const source = 0;
+            const skuOffset = 1;
+            complexSkus.forEach((sku, i) => {
+                const remaining = residual[source].get(skuOffset + i) ?? 0;
+                if (remaining > 0)
+                    unassigned.push(`${sku} (${remaining})`);
+            });
+        }
+    }
+    if (unassigned.length) {
+        violations.push(`Cannot satisfy line item constraints: ${unassigned.join(", ")} could not be assigned to any requirement slot`);
+    }
+    return violations;
+}
+function lineItemsMaxFlow(skuList, cartQty, requirements, reqAcceptable, reqIsWildcard, reqRemaining) {
+    const sCount = skuList.length;
+    const rCount = requirements.length;
+    const n = 1 + sCount + rCount + 1;
+    const source = 0;
+    const sink = n - 1;
+    const skuOffset = 1;
+    const reqOffset = skuOffset + sCount;
+    const graph = Array.from({ length: n }, () => new Map());
+    // 1. source -> SKUs
+    skuList.forEach((sku, i) => {
+        graph[source].set(skuOffset + i, cartQty.get(sku));
+        graph[skuOffset + i].set(source, 0);
+    });
+    // 2. SKUs -> requirements
+    skuList.forEach((sku, i) => {
+        for (let j = 0; j < requirements.length; j++) {
+            if (reqIsWildcard[j] || reqAcceptable[j].has(sku)) {
+                graph[skuOffset + i].set(reqOffset + j, INF);
+                graph[reqOffset + j].set(skuOffset + i, 0);
+            }
+        }
+    });
+    // 3. requirements -> sink
+    for (let j = 0; j < requirements.length; j++) {
+        graph[reqOffset + j].set(sink, reqRemaining[j]);
+        graph[sink].set(reqOffset + j, 0);
+    }
+    return { maxFlow: dinic(graph, source, sink, n), residual: graph };
+}
+function dinic(graph, source, sink, n) {
+    const adjNodes = graph.map((m) => [...m.keys()]);
+    function bfsLevel() {
+        const level = new Array(n).fill(-1);
+        level[source] = 0;
+        const q = [source];
+        let head = 0;
+        while (head < q.length) {
+            const u = q[head++];
+            for (const v of adjNodes[u]) {
+                if (level[v] === -1 && (graph[u].get(v) ?? 0) > 0) {
+                    level[v] = level[u] + 1;
+                    q.push(v);
+                }
+            }
+        }
+        return level[sink] !== -1 ? level : null;
+    }
+    function dfsBlock(u, pushed, level, it) {
+        if (u === sink || pushed === 0)
+            return pushed;
+        let totalPushed = 0;
+        while (it[u] < adjNodes[u].length) {
+            const v = adjNodes[u][it[u]];
+            const cap = graph[u].get(v) ?? 0;
+            if (level[v] === level[u] + 1 && cap > 0) {
+                const d = dfsBlock(v, Math.min(pushed, cap), level, it);
+                if (d > 0) {
+                    graph[u].set(v, (graph[u].get(v) ?? 0) - d);
+                    graph[v].set(u, (graph[v].get(u) ?? 0) + d);
+                    totalPushed += d;
+                    pushed -= d;
+                    if (pushed === 0)
+                        break;
+                }
+            }
+            it[u]++;
+        }
+        return totalPushed;
+    }
+    let total = 0;
+    for (;;) {
+        const level = bfsLevel();
+        if (level === null)
+            break;
+        const it = new Array(n).fill(0);
+        for (;;) {
+            const f = dfsBlock(source, INF, level, it);
+            if (f === 0)
+                break;
+            total += f;
+        }
+    }
+    return total;
+}
+//# sourceMappingURL=max-flow.js.map

package/dist/ap2/max-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"max-flow.js","sourceRoot":"","sources":["../../src/ap2/max-flow.ts"],"names":[],"mappings":"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"}

package/dist/ap2/parse.d.ts

@@ -0,0 +1,35 @@
+/**
+ * dSD-JWT parsing + canonical serialization.
+ *
+ * Byte-exact port of AP2's `sdjwt/common.py` (`ParsedToken`, `parse_token`) and
+ * `mandate.py` (`_canonical_chain_segment`). The canonical strings produced here
+ * feed the binding hashes (hash.ts), so a 1-byte divergence breaks every
+ * `sd_hash`/`issuer_jwt_hash` comparison — these are tested byte-exact against
+ * vectors minted by AP2's own SDK (test/fixtures/ap2-hash-pairs.json).
+ */
+export interface ParsedToken {
+    issuerJwt: string;
+    disclosures: string[];
+    kbJwt: string | null;
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+    /** `_sd_alg` from the payload, if a string. */
+    sdAlg?: string;
+    /** `issuer_jwt + '~' + disclosures.join('~') + '~'` (no KB segment). */
+    sdJwt: string;
+    /** `sdJwt + kbJwt` when a trailing KB-JWT is present, else `sdJwt`. */
+    canonical: string;
+    /** `typ` from the protected header, if a string. */
+    typ?: string;
+}
+/** Parse + canonicalize a compact SD-JWT token (one chain segment). */
+export declare function parseToken(token: string): ParsedToken;
+/**
+ * Restore the trailing `~` that the `~~` join consumed from a non-final segment.
+ * Port of `_canonical_chain_segment`: leave it alone if it's the final segment,
+ * already ends with `~`, or ends in a 3-part KB-JWT; otherwise append `~`.
+ */
+export declare function canonicalChainSegment(segment: string, index: number, total: number): string;
+/** Split a compact dSD-JWT chain on `~~`, restore each segment, and parse. */
+export declare function splitChain(compact: string): ParsedToken[];
+//# sourceMappingURL=parse.d.ts.map

package/dist/ap2/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/ap2/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAeD,uEAAuE;AACvE,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CAmCrD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM3F;AAED,8EAA8E;AAC9E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAGzD"}

package/dist/ap2/parse.js

@@ -0,0 +1,78 @@
+/**
+ * dSD-JWT parsing + canonical serialization.
+ *
+ * Byte-exact port of AP2's `sdjwt/common.py` (`ParsedToken`, `parse_token`) and
+ * `mandate.py` (`_canonical_chain_segment`). The canonical strings produced here
+ * feed the binding hashes (hash.ts), so a 1-byte divergence breaks every
+ * `sd_hash`/`issuer_jwt_hash` comparison — these are tested byte-exact against
+ * vectors minted by AP2's own SDK (test/fixtures/ap2-hash-pairs.json).
+ */
+const JWT_PARTS = 3;
+function decodeSegment(segment, part) {
+    let decoded;
+    try {
+        decoded = JSON.parse(Buffer.from(segment, "base64url").toString("utf8"));
+    }
+    catch (e) {
+        throw new Error(`Cannot parse JWT ${part}: ${e.message}`);
+    }
+    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+        throw new Error(`JWT ${part} must decode to a JSON object`);
+    }
+    return decoded;
+}
+/** Parse + canonicalize a compact SD-JWT token (one chain segment). */
+export function parseToken(token) {
+    if (token.startsWith("~"))
+        throw new Error("Malformed SD-JWT: empty issuer JWT");
+    if (!token.includes("~"))
+        throw new Error("Malformed SD-JWT: missing disclosure separator");
+    const parts = token.split("~");
+    const issuerJwt = parts[0];
+    const disclosureParts = parts.slice(1, -1);
+    if (disclosureParts.some((d) => d === "")) {
+        throw new Error("Malformed SD-JWT: empty disclosure segment");
+    }
+    let kbJwt;
+    if (token.endsWith("~")) {
+        kbJwt = null;
+    }
+    else {
+        kbJwt = parts[parts.length - 1];
+        if (kbJwt.split(".").length !== JWT_PARTS) {
+            throw new Error("Malformed KB-JWT: expected header.payload.signature");
+        }
+    }
+    const disclosures = disclosureParts;
+    const jwtParts = issuerJwt.split(".");
+    if (jwtParts.length !== JWT_PARTS) {
+        throw new Error("Malformed SD-JWT: issuer JWT must have header.payload.signature");
+    }
+    const header = decodeSegment(jwtParts[0], "header");
+    const payload = decodeSegment(jwtParts[1], "payload");
+    const sdAlg = typeof payload["_sd_alg"] === "string" ? payload["_sd_alg"] : undefined;
+    const sdJwt = disclosures.length ? `${issuerJwt}~${disclosures.join("~")}~` : `${issuerJwt}~`;
+    const canonical = kbJwt ? sdJwt + kbJwt : sdJwt;
+    const typ = typeof header["typ"] === "string" ? header["typ"] : undefined;
+    return { issuerJwt, disclosures, kbJwt, header, payload, sdAlg, sdJwt, canonical, typ };
+}
+/**
+ * Restore the trailing `~` that the `~~` join consumed from a non-final segment.
+ * Port of `_canonical_chain_segment`: leave it alone if it's the final segment,
+ * already ends with `~`, or ends in a 3-part KB-JWT; otherwise append `~`.
+ */
+export function canonicalChainSegment(segment, index, total) {
+    if (index === total - 1 || segment.endsWith("~"))
+        return segment;
+    const idx = segment.lastIndexOf("~");
+    const last = idx === -1 ? segment : segment.slice(idx + 1);
+    if (last.split(".").length === JWT_PARTS)
+        return segment;
+    return segment + "~";
+}
+/** Split a compact dSD-JWT chain on `~~`, restore each segment, and parse. */
+export function splitChain(compact) {
+    const segs = compact.split("~~");
+    return segs.map((s, i) => parseToken(canonicalChainSegment(s, i, segs.length)));
+}
+//# sourceMappingURL=parse.js.map

package/dist/ap2/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../../src/ap2/parse.ts"],"names":[],"mappings":"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"}

package/dist/ap2/sd-jwt.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Root SD-JWT verification + disclosure resolution.
+ *
+ * Signatures: verified by jose, ES256-pinned, key supplied out-of-band — never
+ * by a disclosure library, never resolving a header `jwk`/`jku`/`x5u`/`kid`.
+ *
+ * Disclosure resolution mirrors AP2's actual reference behavior, which is a
+ * hybrid of THREE layers (AP2's golden vectors are minted by the Python
+ * `sd_jwt` lib + AP2's own post-passes, so we mirror that exact stack, not the
+ * unrelated TS `@sd-jwt` lib):
+ *
+ *   A. Standard RFC 9901 unpack — port of `sd_jwt` lib
+ *      `SDJWTVerifier._unpack_disclosed_claims`: resolve `{"...": digest}` array
+ *      elements ([salt, value]) and `_sd: [digest]` object members
+ *      ([salt, name, value]) against the token's disclosures; strip `_sd` /
+ *      `_sd_alg`; reject duplicate disclosure hashes, duplicate `_sd` digests,
+ *      and duplicate disclosed keys. Only sha-256 (the lib rejects others).
+ *   B. AP2 delegate-item resolution — port of `chain.py::_resolve_delegate_items`
+ *      + `_inline_sd_claims`: walk a resolved `delegate_payload` array; for dict
+ *      items, inline any remaining object-property `_sd` digests; decode any
+ *      bare-string items into their dict value.
+ *   C. CMWallet quirk — port of `kb_sd_jwt.py::_resolve_delegate_payload` +
+ *      `_try_resolve_digest`: `delegate_payload` items that are bare digest
+ *      STRINGS get replaced in place by the dict value of the matching
+ *      disclosure (used by KB hops in P3).
+ *
+ * Validated byte-exact against `test/fixtures/ap2-vectors.json`
+ * (`expectedPayloads`), minted from AP2's own SDK.
+ */
+import { type CryptoKey, type JWK as JoseJwk, type KeyObject } from "jose";
+import type { ParsedToken } from "./parse.js";
+import { type Jwk } from "./jwk.js";
+/** A jose-importable verification key, or a bare JWK jose imports for us. */
+export type VerificationKey = CryptoKey | KeyObject | JoseJwk | Uint8Array;
+type Json = Record<string, unknown>;
+/**
+ * Resolve all disclosures in an issuer-verified payload (Layer A). Mirrors
+ * `_extract_sd_claims`: rejects a non-sha-256 `_sd_alg` (the lib supports only
+ * sha-256), then unpacks.
+ */
+export declare function resolveDisclosures(payload: Json, disclosures: string[], sdAlg: string | undefined): Json;
+/**
+ * Resolve bare digest-string items inside `delegate_payload` in place. Port of
+ * `kb_sd_jwt.py::_resolve_delegate_payload`: dict items are left unchanged;
+ * string items are replaced by the matching disclosure's dict value (or kept
+ * as-is when no disclosure matches).
+ */
+export declare function resolveDelegatePayload(payload: Json, token: ParsedToken): void;
+/**
+ * Resolve the effective delegate items from a verified payload's
+ * `delegate_payload`. Port of `chain.py::_resolve_delegate_items`.
+ */
+export declare function resolveDelegateItems(delegatePayload: unknown, token: ParsedToken): Json[];
+export interface ResolvedToken {
+    /** The parsed token this resolution belongs to. */
+    token: ParsedToken;
+    /** Full issuer-verified payload after Layer A disclosure resolution. */
+    verifiedPayload: Json;
+    /** Effective delegate items (Layer B) — `[OpenMandate]` for a payment root. */
+    delegateItems: Json[];
+}
+/** Verify one ES256 compact JWS signature; throws on any failure. Key is supplied
+ * out-of-band — a header `jwk`/`jku`/`x5u`/`kid` is NEVER trusted to pick it. */
+export declare function verifyEs256(issuerJwt: string, key: VerificationKey): Promise<void>;
+/**
+ * Verify the root issuer JWT signature (ES256, pinned) and resolve its
+ * disclosures. `key` is the issuer's public key, supplied out-of-band (x5c/kid
+ * trust is resolved by the caller in P4).
+ */
+export declare function verifyRootSdJwt(token: ParsedToken, key: VerificationKey): Promise<ResolvedToken>;
+/**
+ * Resolve the `cnf.jwk` that the NEXT hop must be signed under. Port of AP2's
+ * `common.py::_find_cnf` (3-tier: delegate_items[*].cnf → verified
+ * delegate_payload[*].cnf → top-level cnf), returned as a strict EC-P256 JWK.
+ *
+ * Hardening H3 (stricter than AP2's first-match): reject if MORE THAN ONE
+ * delegate item carries a `cnf` — a disclosure-injected second `cnf` must not be
+ * able to silently win. (The signed-`_sd` binding refinement is pending a
+ * crafted ambiguous-cnf vector.)
+ */
+export declare function cnfJwk(resolved: ResolvedToken): Jwk;
+export {};
+//# sourceMappingURL=sd-jwt.d.ts.map

package/dist/ap2/sd-jwt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sd-jwt.d.ts","sourceRoot":"","sources":["../../src/ap2/sd-jwt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAiB,KAAK,SAAS,EAAE,KAAK,GAAG,IAAI,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1F,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,UAAU,CAAC;AAE9C,6EAA6E;AAC7E,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,UAAU,CAAC;AAU3E,KAAK,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AA8GpC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAMxG;AAsBD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,CAW9E;AAmCD;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,eAAe,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI,EAAE,CAazF;AAID,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,KAAK,EAAE,WAAW,CAAC;IACnB,wEAAwE;IACxE,eAAe,EAAE,IAAI,CAAC;IACtB,+EAA+E;IAC/E,aAAa,EAAE,IAAI,EAAE,CAAC;CACvB;AAED;iFACiF;AACjF,wBAAsB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAExF;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAKtG;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,QAAQ,EAAE,aAAa,GAAG,GAAG,CAanD"}