Skip to content
Merged
Show file tree
Hide file tree
Changes from 23 commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
8735216
Grant signing accepts the Delegated SD-JWT layout and the newer key-b…
Nov 19, 2026
eb44535
Test the Delegated layout's "nothing behind the gap" refusal for real…
Nov 19, 2026
92858dd
Replay a real Multipaz Wallet answer as a test: its sd_hash matches t…
Nov 19, 2026
65383a4
Spend a grant signed in the Delegated layout, and verify it at the me…
Nov 19, 2026
c282dec
Changelog: say merchants on 0.6.0 refuse these permissions, and what …
Nov 19, 2026
379a8ca
Refuse a key binding that is not three parts at signing (review of #474)
Nov 19, 2026
590edbf
Comments, messages and the draft citation say what the code does (rev…
Nov 19, 2026
32dec42
Name the simulator option like its siblings, and throw when it would …
Nov 19, 2026
435159c
Test that a hop naming no further key must be typed terminal (review …
Nov 19, 2026
0e6da94
Pin the key binding's character set, say the wallet is a development …
Nov 19, 2026
32684c8
Pin `+` and `/` in the key binding's check, and correct its comment (…
Nov 19, 2026
ded3e14
Accept both spellings of the terminal key-binding type, like AP2's ve…
Nov 19, 2026
aba1d9b
The signing page does not accept the terminal `kb-sd-jwt`; the change…
Nov 19, 2026
9b0cf05
Say why the signing page still lets `kb+sd-jwt` through, and pin it (…
Nov 20, 2026
0d8f23f
Header and changelog say what the code does about the older terminal …
Nov 20, 2026
fa38964
Clearer wallet-type refusal, one list of wallet types, and a real-ans…
Nov 20, 2026
6cf8170
Changelog: say the page now accepts what it used to refuse, and tell …
Nov 20, 2026
2879b2e
Decode the key binding strictly again, and tighten the replay test an…
Nov 20, 2026
94e09ca
Changelog: custom backends get the wallet's raw answer, and may refus…
Nov 20, 2026
c7684d6
Test the earlier layout's strict key-binding read, and say only 0.6.0…
Nov 20, 2026
b585718
One split, one stored string: drop `normalized`, split the guard, rea…
Nov 21, 2026
6d03ab3
Docs: name the backend type in the README, shorten the backend note, …
Nov 21, 2026
5758051
Say the page now also refuses a padded or respelled signature, say "b…
Nov 21, 2026
d7b245b
Changelog: what 0.6.0 did with a signature outside base64url, for eac…
dzuluaga Nov 21, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,9 +83,38 @@ npm actually serves with `npm view @openmobilehub/credentagent-gate version`.
built from the gate's `walletOrigin`, so a wallet origin on plain `http:` anywhere else (a LAN
address, a `.local` name, a `*.localhost` subdomain) no longer gets the buttons: serve it over
`https:` or use `localhost` (#434).
- `verifyDelegatedPurchase` accepts the agent's last hop typed `kb-sd-jwt` as well as `kb+sd-jwt`
(before, only `kb+sd-jwt`), as AP2's own verifier does; `cnf` still decides whether a hop ends the
chain. This reaches only agents built without this package: the gate's own agent signs
`kb+sd-jwt`. The signing page does not accept `kb-sd-jwt`, because it sees only the wallet's hop
(#473).

### Fixed

- Signing a spending grant with the updated Multipaz Wallet (a development build, not released yet)
no longer ends in "presentation carries no key-binding JWT" (#473). That wallet sends its
signature in the middle of the answer, followed by the mandate disclosures (the Delegated SD-JWT
layout of the Delegate SD-JWT draft, §5.1.1), where the signing page looked for it at the end.
The page reads both layouts. It refuses what it refused before, except that it now accepts the
new layout and the new type spelling below. Checked against a real answer captured on a phone
from a development build of that wallet, which is replayed as a test.
- The page already refused a key binding with the wrong number of parts. It now also refuses,
in either layout, one whose signature is padded with `=` or written with `+` or `/`: 0.6.0
authorized such a grant, and the merchant then refused it when the agent spent it.
Comment thread
dzuluaga marked this conversation as resolved.
Resolved
- The wallet types its signature `kb-sd-jwt+kb`, a spelling the draft uses in §6 (§5.1.4 writes
`kb+sd-jwt+kb`). The signing page and the merchant's chain verifier (`verifyDelegatedPurchase`)
now accept either. The gate does not choose the wallet's type; the wallet does.
- **Update the gate and merchants together.** A merchant still on 0.6.0 accepts only
`kb+sd-jwt+kb`, so it refuses a spending grant this wallet signed, with `code: "typ"`, when the
agent spends it, after the user has left.
- If you call `verifyIntentPresentation` with your own `IntentVerifyBackend`, wrap
`inGateBackend`; it reads both layouts and both type spellings.
- `verifyIntentPresentation` now returns `intent.presentation` re-serialized for the new layout,
in the earlier shape (`<credential>~<disclosures>~<key binding>`), so the code that spends it
is unchanged.
- New test-only options on the simulated wallet, `devSimulateWalletSignature`:
`delegatedLayout`, `overrideKbDisclosure` and `breakKbEncoding`.

- Creating a spending grant from claude.ai no longer hangs with a product grid where the grant card
should be. Three causes, fixed together:
- On a client that can ask the person questions itself (MCP 2026-07-28 with `elicitation`, which
Expand Down
9 changes: 5 additions & 4 deletions packages/credentagent-gate/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -887,10 +887,11 @@ that was never device-signed can never spend; a spend always traces to the exact
Content from its own grant record to require the wallet signed those exact terms. What is **still
demo** is the trust **anchor**: the gate does **not** check who issued the payment credential (that
hardening is issue #14), so a self-crafted credential would pass. The
verify runs through a **seam** — the in-gate backend attests `device-signed` / `verifiedBy: "gate"`;
wiring an external verifier (the `DelegatedVerifier` seam) that reports a stronger, issuer-backed level
is the fast-follow, and the gate **relays** that level verbatim with the attestor recorded in
`verifiedBy`.
verify runs through a **seam**, the `IntentVerifyBackend` type, which only direct callers of
`verifyIntentPresentation` can plug into (the signing route always uses the in-gate backend). The
in-gate backend attests `device-signed` / `verifiedBy: "gate"`; wiring an external verifier (the
`DelegatedVerifier` seam) that reports a stronger, issuer-backed level is the fast-follow, and the
gate **relays** that level verbatim with the attestor recorded in `verifiedBy`.

Test the whole flow **with no phone** using the exported simulated wallet — see
[`examples/device-signed-grants.mjs`](https://github.com/openmobilehub/credentagent/blob/main/examples/device-signed-grants.mjs)
Expand Down
3 changes: 2 additions & 1 deletion packages/credentagent-gate/src/ap2/chain/purchase.ts
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,8 @@ export class DelegatedIntent {
this.disclosures = disclosures;
}

/** From what the intent-sign rail holds after the ceremony: `vp_token` and the request's disclosures. */
/** From what the intent-sign rail holds after the ceremony: the wallet's answer, kept with its key
* binding last whichever layout the wallet sent, and the request's disclosures. */
static fromWalletPresentation(args: { presentation: string; disclosures: readonly string[] }): DelegatedIntent {
const byVct = (vct: string) => args.disclosures.find((d) => decodeDisclosure(d)?.vct === vct);
const checkout = byVct(VCT.openCheckout);
Expand Down
11 changes: 7 additions & 4 deletions packages/credentagent-gate/src/ap2/chain/serialize.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ export interface ChainLink {
disclosures: string[];
}

const isCompactJwt = (s: string): boolean => /^[\w-]+\.[\w-]+\.[\w-]+$/.test(s);
/** Exactly three dot-separated base64url parts — what the chain code can split, spend and re-serialize. */
export const isCompactJwt = (s: string): boolean => /^[\w-]+\.[\w-]+\.[\w-]+$/.test(s);

/**
* Join links, each an SD-JWT serialization ending in `~`, into one dSD-JWT.
Expand Down Expand Up @@ -62,9 +63,11 @@ export function splitChain(token: string): ChainLink[] | undefined {
* disclosures the request carried.
*
* The wallet's key binding IS the second link (Delegate SD-JWT §4: "the KB-JWT in the preceding
* SD-JWT+KB fulfils the role of the Issuer-JWT for the next"). Its disclosures were never on
* the wire — the verifier sent them in the request — so they are re-attached here, one at a
* time: §5.1.4 requires exactly one delegate payload disclosed per chain.
* SD-JWT+KB fulfils the role of the Issuer-JWT for the next"). `presentation` is held in the
* earlier layout, key binding last: the intent-sign rail stores a Delegated-layout answer that way
* and drops the mandate disclosures behind its key binding. The disclosures the verifier sent in
* the request are re-attached here, one at a time: §5.1.4 requires exactly one delegate payload
* disclosed per chain.
*/
export function walletChain(presentation: string, disclosure: string): string | undefined {
const cut = presentation.lastIndexOf("~");
Expand Down
53 changes: 51 additions & 2 deletions packages/credentagent-gate/src/ap2/chain/verify.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -159,10 +159,22 @@ describe("each hop is bound to the one before it", () => {
});

describe("typ and disclosure rules (§5.1.4, §6)", () => {
// Draft -00 §6 writes the delegable `typ` `kb-sd-jwt+kb`, and Multipaz sends it (#473).
// AP2's Python SDK accepts both, so this chain verifier does too.
it("accepts a wallet hop typed with the hyphen spelling, `kb-sd-jwt+kb`", async () => {
const { chain } = await chainFor({ walletTyp: "kb-sd-jwt+kb" });
expect(await verify(chain)).toMatchObject({ ok: true });
});

it("still refuses a spelling that is neither (bypass)", async () => {
const { chain } = await chainFor({ walletTyp: "kb+sd-jwt-kb" });
expect(await verify(chain)).toMatchObject({ ok: false, code: "typ" });
});

// A wallet hop that names the agent's key in `cnf` is one that may be delegated again, so it
// must say so. `kb+sd-jwt` means "the end of the chain" — and the AP2 Python SDK refuses it.
it("refuses a wallet hop typed as terminal while naming a next key (bypass)", async () => {
const { chain } = await chainFor({ walletTyp: "kb+sd-jwt" });
it.each(["kb+sd-jwt", "kb-sd-jwt"])("refuses a wallet hop typed as terminal (`%s`) while naming a next key (bypass)", async (walletTyp) => {
const { chain } = await chainFor({ walletTyp });
expect(await verify(chain)).toMatchObject({ ok: false, code: "typ", detail: expect.stringMatching(/^link 1/) });
});

Expand Down Expand Up @@ -198,6 +210,43 @@ describe("typ and disclosure rules (§5.1.4, §6)", () => {
expect(await verify(chain)).toMatchObject({ ok: false, code: "typ", detail: expect.stringMatching(/^link 2/) });
});

// AP2's Python SDK accepts `kb-sd-jwt` for a hop that ends the chain, and draft -00 §6 writes it
// that way, so a merchant on this gate must not refuse the last hop AP2's verifier accepts.
it("accepts an agent hop with no further key typed `kb-sd-jwt`, the draft's other spelling", async () => {
const { prefix, g } = await chainFor();
const hop = await sdJwtInstance({ privateKey: g.agent.privateKey }).issue(
{
iat: Math.floor(Date.now() / 1000),
aud: MERCHANT,
nonce: "n-1",
sd_hash: bindingHash(splitChain(prefix)!.at(-1)!),
delegate_payload: [closedCheckout],
} as never,
{ delegate_payload: { _sd: [0] } } as never,
{ header: { typ: "kb-sd-jwt" } },
);
expect(await verify(joinChain([prefix, hop]))).toMatchObject({ ok: true });
});

// The other half of the same rule: a hop that names no further key ends the chain, so it must be
// typed terminal. A delegable type on it claims a next hop that does not exist. Deleting the
// no-`cnf` arm of the `typ` check leaves every other test green; this one fails (#474 review).
it.each(["kb+sd-jwt+kb", "kb-sd-jwt+kb", "kb+jwt"])("refuses an agent hop with no further key typed `%s` (bypass)", async (wrongTyp) => {
const { prefix, g } = await chainFor();
const hop = await sdJwtInstance({ privateKey: g.agent.privateKey }).issue(
{
iat: Math.floor(Date.now() / 1000),
aud: MERCHANT,
nonce: "n-1",
sd_hash: bindingHash(splitChain(prefix)!.at(-1)!),
delegate_payload: [closedCheckout],
} as never,
{ delegate_payload: { _sd: [0] } } as never,
{ header: { typ: wrongTyp } },
);
expect(await verify(joinChain([prefix, hop]))).toMatchObject({ ok: false, code: "typ", detail: expect.stringMatching(/^link 2/) });
});

// §5.1.4: "exactly one of these MUST be disclosed". Disclosing both open mandates would let the
// agent's single closed hop sit under whichever one a verifier happened to read.
it("refuses a wallet hop that discloses both open mandates (bypass)", async () => {
Expand Down
7 changes: 3 additions & 4 deletions packages/credentagent-gate/src/ap2/chain/verify.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import { X509Certificate, type KeyObject } from "node:crypto";
import { importVerifyKey, type PublicJwkP256 } from "../keys.js";
import { libraryRefusal, sdJwtInstance } from "../sdjwt.js";
import { linkToString, splitChain, type ChainLink } from "./serialize.js";
import { DELEGATE_KB_TYP, DELEGATE_PAYLOAD_CLAIM } from "../delegate.js";
import { DELEGABLE_KB_TYPS, DELEGATE_PAYLOAD_CLAIM, TERMINAL_KB_TYPS, isDelegableKbTyp, isTerminalKbTyp } from "../delegate.js";
import { bindingHash, peekLink } from "./hop.js";

export type ChainRefusalCode =
Expand Down Expand Up @@ -150,9 +150,8 @@ export async function verifyChain(token: string, opts: VerifyChainOptions): Prom
// the key that would do it. A wallet hop typed terminal while naming the agent is refused —
// it is also what the AP2 Python SDK refuses.
const typ = peekLink(links[i])?.header.typ;
const wants = element.cnf ? DELEGATE_KB_TYP.delegable : DELEGATE_KB_TYP.terminal;
if (typ !== wants)
return refuse("typ", `link ${i}: typed ${String(typ)} but ${element.cnf ? "names" : "names no"} further key — expected ${wants}`);
if (element.cnf ? !isDelegableKbTyp(typ) : !isTerminalKbTyp(typ))
return refuse("typ", `link ${i}: typed ${String(typ)} but ${element.cnf ? "names" : "names no"} further key — expected ${(element.cnf ? DELEGABLE_KB_TYPS : TERMINAL_KB_TYPS).join(" or ")}`);
if (last && element.cnf) return refuse("typ", `link ${i}: the last hop names a further key, so the chain is not finished`);
if (!last && !element.cnf) return refuse("typ", `link ${i}: names no key for the next hop`);

Expand Down
36 changes: 36 additions & 0 deletions packages/credentagent-gate/src/ap2/delegate.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,3 +18,39 @@ export const DELEGATE_PAYLOAD_CLAIM = "delegate_payload";
* the tell that the delegation extension was never applied.
*/
export const DELEGATE_KB_TYP = { delegable: "kb+sd-jwt+kb", terminal: "kb+sd-jwt" } as const;

/**
* Both spellings of the delegable `typ` a verifier accepts. Draft -00 itself uses both: §2.2, §5.1.4
* and its IANA section say `kb+sd-jwt+kb`, and §6 (steps 1.1, 3.e and 4.2) says `kb-sd-jwt+kb`. A
* review of multipaz#2178 reports that a later draft settled on the `-`. Multipaz sends the hyphen
* form, and AP2's Python SDK accepts both (as reported there; this repo never runs it). The gate
* accepts either, so a wallet on one spelling is not refused for a difference the draft itself contains.
*/
export const DELEGABLE_KB_TYPS: readonly string[] = [DELEGATE_KB_TYP.delegable, "kb-sd-jwt+kb"];

/**
* What the signing page accepts for the WALLET's hop: either delegable spelling, and the terminal
* `kb+sd-jwt`, kept because 0.6.0 accepted it. That terminal type passes only where the caller
* lets it: `ceremony/intent-sign/verify.ts` refuses it for a grant whose key the agent holds. The
* other terminal spelling, `kb-sd-jwt`, is for the agent's last hop and is not accepted here.
*/
export const WALLET_KB_TYPS: readonly string[] = [...DELEGABLE_KB_TYPS, DELEGATE_KB_TYP.terminal];

/**
* Both spellings of the terminal `typ`, for a hop that ends the chain. The same difference sits
* here: §5.1.4 says `kb+sd-jwt`, §6 step 4.2 says `kb-sd-jwt`, and AP2's Python SDK accepts both
* (`TYP_TERMINAL` in `kb_sd_jwt.py`, read at google-agentic-commerce/AP2@b4587ac). A merchant on
* this gate would otherwise refuse a last hop that AP2's own verifier accepts. The gate emits
* `DELEGATE_KB_TYP.terminal`.
*/
export const TERMINAL_KB_TYPS: readonly string[] = [DELEGATE_KB_TYP.terminal, "kb-sd-jwt"];
Comment thread
TheBlackBit marked this conversation as resolved.
Resolved

/** Whether `typ` marks a hop that ends the chain — the terminal `typ`, either spelling. */
export function isTerminalKbTyp(typ: unknown): boolean {
return typeof typ === "string" && TERMINAL_KB_TYPS.includes(typ);
}

/** Whether `typ` marks a hop whose payload names a further key — the delegable `typ`, either spelling. */
export function isDelegableKbTyp(typ: unknown): boolean {
return typeof typ === "string" && DELEGABLE_KB_TYPS.includes(typ);
}
22 changes: 20 additions & 2 deletions packages/credentagent-gate/src/ceremony/intent-sign/dev-wallet.ts
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,13 @@ export function delegateKeyBinding(args: {
typ?: string;
/** The bytes `sd_hash` covers. Defaults to `presented`; a test passes others to break it. */
sdHashOver?: string;
/** Present the Delegated SD-JWT layout (`<SD-JWT>~~<KB-JWT>~<disclosure>~…`, draft §5.1.1) with
* these disclosures behind the key binding, as the Multipaz SDK's `presentWithKbDisclosures`
* does. Omitted: the earlier layout, key binding last. */
kbDisclosures?: string[];
/** TEST-ONLY: sign a key binding whose body carries one extra base64url character. The signature
* is valid over it, a lenient reader gets the same claims, and a strict decoder refuses it. */
malformBody?: boolean;
iat?: number;
}): string {
const b64uJson = (v: unknown) => Buffer.from(JSON.stringify(v), "utf-8").toString("base64url");
Expand All @@ -83,7 +90,18 @@ export function delegateKeyBinding(args: {
sd_hash: Buffer.from(hasher(args.sdHashOver ?? args.presented, "sha-256")).toString("base64url"),
[DELEGATE_PAYLOAD_CLAIM]: args.delegatePayload,
};
const signingInput = `${b64uJson(header)}.${b64uJson(payload)}`;
let body = b64uJson(payload);
if (args.malformBody) {
// Pad the JSON with spaces until its base64url length is a multiple of four, then add one
// character: the length becomes 4n+1, which a lenient `Buffer` read ignores and a strict decoder
// refuses, so the claims read back the same.
let json = JSON.stringify(payload);
while (Buffer.from(json, "utf-8").toString("base64url").length % 4 !== 0) json += " ";
body = `${Buffer.from(json, "utf-8").toString("base64url")}A`;
}
const signingInput = `${b64uJson(header)}.${body}`;
// The package's own ES256 signer, so a dev wallet signs exactly as the gate verifies.
return `${args.presented}${signingInput}.${es256Signer(args.holderKey)(signingInput)}`;
const kbJwt = `${signingInput}.${es256Signer(args.holderKey)(signingInput)}`;
if (args.kbDisclosures) return `${args.presented}~${kbJwt}~${args.kbDisclosures.map((d) => `${d}~`).join("")}`;
return `${args.presented}${kbJwt}`;
}
Loading
Loading