@integraledger/agent-guard 0.9.0

package/dist/proposal-ack.d.ts

@@ -0,0 +1,111 @@
+/**
+ * The ACK buyer surface: read an ACK-Pay `PaymentReceiptCredential` and say which rung of the record each
+ * half of it feeds.
+ *
+ * **There is deliberately no `GateProposal` here, and that is a finding about ACK rather than a gap.** Every
+ * other parser in this package turns a PROPOSAL into the typed inputs a buyer decides on. ACK has no
+ * proposal-time carrier to turn: read live at `agentcommercekit/ack@main` on 2026-07-30,
+ * `packages/ack-pay/src/schemas/valibot.ts` declares `paymentRequestSchema` as
+ * `{ id, description?, serviceCallback?, expiresAt?, paymentOptions }` — no `metadata`, no open field, no
+ * extension point anywhere on the request. The open map (`v.optional(v.record(v.string(), v.unknown()))`)
+ * exists on `paymentReceiptClaimSchema` ALONE. So an LCP reference reaches an ACK document only at receipt
+ * time, and manufacturing a `GateProposal` from a receipt would name a decision the buyer no longer has:
+ * the payment has already settled. What the receipt genuinely supports is post-settlement verification, and
+ * that is what this module produces.
+ *
+ * An ACK buyer that wants a decision BEFORE paying gets it the same way any Level 1–2 buyer does: from the
+ * seller's `/.well-known/legal-context.json` (LCP §2), which is out of band from ACK entirely.
+ */
+import type { Artifact } from "@integraledger/lcp-evidence";
+/**
+ * The DID methods ACK's own resolver registers — `packages/did/src/did-resolvers/get-did-resolver.ts`
+ * composes exactly four (`key-did-resolver`, `./web-did-resolver`, `jwks-did-resolver`,
+ * `./pkh-did-resolver`), read live 2026-07-30. A receipt naming any other method is one ACK's own chain
+ * could not have verified, so it is refused here rather than carried into a record as an identity nobody
+ * can resolve. `did:jwks` was still pending when earlier surveys of ACK were written and has since landed,
+ * which is why this list is cut from ACK's own resolver code rather than from any survey of it.
+ */
+export declare const ACK_DID_METHODS: readonly string[];
+/** What an issued ACK receipt yields, before anything is decided about it. */
+export interface AckReceiptFacts {
+    /** The reference recovered from `credentialSubject.metadata`, through the placement's own manifest. */
+    readonly atrHash: `0x${string}`;
+    /** ACK's join key: the signed payment request this receipt attests, and no other. */
+    readonly paymentRequestToken: string;
+    /** Which of the request's `paymentOptions` was taken. */
+    readonly paymentOptionId: string;
+    /** `credentialSubject.id` — the payer DID the receipt attributes the payment to. */
+    readonly payerDid: string;
+    /** The payer DID's method, narrowed to `ACK_DID_METHODS`. */
+    readonly payerDidMethod: string;
+    /** `issuer.id` — the receipt service that signed. Recorded; never mistaken for the payer. */
+    readonly issuerDid: string;
+    /**
+     * The other keys ACK's own audit trail put in the same map, in wire order — `policyRef`, `mandateRef`,
+     * `executionRef`, `executionReceiptHash`, `settlementNetwork`, `settlementReference` and whatever else a
+     * deployment added. Reported because a record composer wants to know what else this receipt
+     * cross-references, and because naming them is the honest form of "we are a guest in this map": we read
+     * exactly one key and own none of the rest.
+     */
+    readonly siblingRefKeys: readonly string[];
+}
+/**
+ * Parse an ISSUED `PaymentReceiptCredential` into its facts. Fail-fast on every departure from what ACK's
+ * own code emits — a receipt this cannot read is one ACK's verification chain could not have produced.
+ *
+ * **The unissued receipt is refused, and it is the mirror of the seller's rule.**
+ * `placement-ack.place` refuses a credential that ALREADY carries a `proof`, because a field added after
+ * issuance either breaks the embedded signature or falls outside the JWT payload ACK treats as
+ * authoritative. This refuses one that does NOT YET carry one, because a credential nobody signed attests
+ * nothing and must not reach a record as evidence of a payment. Between the two rules the reference can
+ * only ever ride a receipt the issuer signed over. The predicate is ACK's own — `isDecodedCredential`
+ * accepts a value iff `"proof" in value && value.proof != null` — mirrored, so a `null` proof is unissued
+ * by the host's rule and is unissued here.
+ */
+export declare function parseAckReceipt(credential: unknown): AckReceiptFacts;
+/**
+ * The receipt's contribution to a post-settlement `verify` call, with each field naming the rung it feeds.
+ *
+ * The first of ACK's two hard edges, answered in code rather than in prose: the `PaymentReceiptCredential` is
+ * **both** an evidence artifact and an identity input, and the split is here.
+ */
+export interface AckReceiptContribution {
+    /** Feeds `VerifyInput.placement` — the reference recovered from the host protocol's OWN document. */
+    readonly placement: {
+        readonly extracted: unknown;
+    };
+    /**
+     * RCS-4 → one `evidence.Artifact` under the `settlement` role.
+     *
+     * `settlement` rather than `attestation`: an ACK receipt IS ACK's settlement artifact — the credential
+     * that attests the payment happened, carrying the `paymentRequestToken` it settled and, by convention,
+     * ACK's own `settlementNetwork`/`settlementReference`. `settlement` is one of `RCS4_REQUIRED_ROLES`, so
+     * filing it correctly is what lets an ACK record's evidence package be complete; filing it under
+     * `attestation` would leave the settlement role empty while double-filling one that is already occupied
+     * by the identity attestation.
+     */
+    readonly artifact: Artifact;
+    /** IDN-1 → the payer `resolve-party` attributes the payment to. */
+    readonly payerDid: string;
+    /**
+     * The payer DID's method — and NOT an assurance level.
+     *
+     * ACK's second hard edge: `did:web` / `did:jwks` resolution reuses the existing identity path rather than
+     * minting a second one, and that path authors identity SELLER-side — the record's IDN content is
+     * seller-authored. A buyer verifying a record reads the assurance the record already states; restating it
+     * here would be a second authority on the same fact. The mapping from ACK's four DID methods to an
+     * `authority.Assurance` therefore lives once, on the seller side, and this surface stops at the method.
+     */
+    readonly payerDidMethod: string;
+    /** The receipt service that signed. Recorded on the record; never the payer. */
+    readonly issuerDid: string;
+    /** ACK's join key — the guard against reading a receipt against a payment request it never attested. */
+    readonly paymentRequestToken: string;
+}
+/**
+ * Split an issued receipt into its two rungs. `receiptBytes` are the retained credential exactly as it was
+ * received — the artifact is the bytes, not a re-serialization of the parse, because what the evidence
+ * package must hold is what the issuer signed.
+ */
+export declare function ackReceiptContribution(credential: unknown, receiptBytes: Uint8Array): AckReceiptContribution;
+//# sourceMappingURL=proposal-ack.d.ts.map

package/dist/proposal-ack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-ack.d.ts","sourceRoot":"","sources":["../src/proposal-ack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,6BAA6B,CAAC;AAG5D;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAkC,CAAC;AAwBhF,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,uGAAuG;IACvG,QAAQ,CAAC,OAAO,EAAE,KAAK,MAAM,EAAE,CAAC;IAChC,qFAAqF;IACrF,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,yDAAyD;IACzD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6DAA6D;IAC7D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,6FAA6F;IAC7F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,OAAO,GAAG,eAAe,CAiEpE;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,qGAAqG;IACrG,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IACpD;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wGAAwG;IACxG,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;CACtC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,OAAO,EACnB,YAAY,EAAE,UAAU,GACvB,sBAAsB,CAUxB"}

package/dist/proposal-ack.js

@@ -0,0 +1,114 @@
+/**
+ * The ACK buyer surface: read an ACK-Pay `PaymentReceiptCredential` and say which rung of the record each
+ * half of it feeds.
+ *
+ * **There is deliberately no `GateProposal` here, and that is a finding about ACK rather than a gap.** Every
+ * other parser in this package turns a PROPOSAL into the typed inputs a buyer decides on. ACK has no
+ * proposal-time carrier to turn: read live at `agentcommercekit/ack@main` on 2026-07-30,
+ * `packages/ack-pay/src/schemas/valibot.ts` declares `paymentRequestSchema` as
+ * `{ id, description?, serviceCallback?, expiresAt?, paymentOptions }` — no `metadata`, no open field, no
+ * extension point anywhere on the request. The open map (`v.optional(v.record(v.string(), v.unknown()))`)
+ * exists on `paymentReceiptClaimSchema` ALONE. So an LCP reference reaches an ACK document only at receipt
+ * time, and manufacturing a `GateProposal` from a receipt would name a decision the buyer no longer has:
+ * the payment has already settled. What the receipt genuinely supports is post-settlement verification, and
+ * that is what this module produces.
+ *
+ * An ACK buyer that wants a decision BEFORE paying gets it the same way any Level 1–2 buyer does: from the
+ * seller's `/.well-known/legal-context.json` (LCP §2), which is out of band from ACK entirely.
+ */
+import { readAtPath } from "@integraledger/lcp-binding-core";
+import { ACK_PLACEMENT, ackPlacement } from "@integraledger/lcp-placement-ack";
+/**
+ * The DID methods ACK's own resolver registers — `packages/did/src/did-resolvers/get-did-resolver.ts`
+ * composes exactly four (`key-did-resolver`, `./web-did-resolver`, `jwks-did-resolver`,
+ * `./pkh-did-resolver`), read live 2026-07-30. A receipt naming any other method is one ACK's own chain
+ * could not have verified, so it is refused here rather than carried into a record as an identity nobody
+ * can resolve. `did:jwks` was still pending when earlier surveys of ACK were written and has since landed,
+ * which is why this list is cut from ACK's own resolver code rather than from any survey of it.
+ */
+export const ACK_DID_METHODS = ["key", "web", "jwks", "pkh"];
+/**
+ * The leaf key names the LCP placement owns — DERIVED from the manifest so the two cannot drift.
+ *
+ * `readAlso` is OPTIONAL on `PlacementManifest` and manifests legitimately omit it, so `[]` is the CORRECT
+ * value for "this placement owns no alias keys" — under it `siblingRefKeys` rightly reports the un-owned key
+ * as one of ACK's own. Total handling of an optional field, not a fallback path: there is nothing here to
+ * fail loudly about. `ACK_PLACEMENT` declares an alias today, which is why the arm is unreached.
+ */
+function lcpKeys() {
+    const leaf = (path) => path.slice(path.lastIndexOf(".") + 1);
+    return [
+        leaf(ACK_PLACEMENT.field),
+        ...(ACK_PLACEMENT.readAlso ?? []).map((alias) => leaf(alias.path)),
+    ];
+}
+function requireString(value, what) {
+    if (typeof value !== "string" || value === "")
+        throw new Error(`ACK receipt: ${what} is absent or not a non-empty string`);
+    return value;
+}
+/**
+ * Parse an ISSUED `PaymentReceiptCredential` into its facts. Fail-fast on every departure from what ACK's
+ * own code emits — a receipt this cannot read is one ACK's verification chain could not have produced.
+ *
+ * **The unissued receipt is refused, and it is the mirror of the seller's rule.**
+ * `placement-ack.place` refuses a credential that ALREADY carries a `proof`, because a field added after
+ * issuance either breaks the embedded signature or falls outside the JWT payload ACK treats as
+ * authoritative. This refuses one that does NOT YET carry one, because a credential nobody signed attests
+ * nothing and must not reach a record as evidence of a payment. Between the two rules the reference can
+ * only ever ride a receipt the issuer signed over. The predicate is ACK's own — `isDecodedCredential`
+ * accepts a value iff `"proof" in value && value.proof != null` — mirrored, so a `null` proof is unissued
+ * by the host's rule and is unissued here.
+ */
+export function parseAckReceipt(credential) {
+    const proof = readAtPath(credential, "proof");
+    if (proof === undefined || proof === null)
+        throw new Error("ack/receipt-not-issued: this credential carries no proof — a receipt nobody signed attests nothing, " +
+            "and the reference it carries is outside anything ACK's verification chain would return");
+    const issuerDid = requireString(readAtPath(credential, "issuer.id"), "issuer.id (ACK's own createCredential emits `issuer: { id: issuer }`, never a bare string)");
+    const payerDid = requireString(readAtPath(credential, "credentialSubject.id"), "credentialSubject.id");
+    const [scheme, method] = payerDid.split(":");
+    if (scheme !== "did" ||
+        method === undefined ||
+        !ACK_DID_METHODS.includes(method))
+        throw new Error(`ACK receipt: "${payerDid}" is not a did uri in a did method ACK resolves (${ACK_DID_METHODS.join(", ")})`);
+    const paymentRequestToken = requireString(readAtPath(credential, "credentialSubject.paymentRequestToken"), "credentialSubject.paymentRequestToken");
+    const paymentOptionId = requireString(readAtPath(credential, "credentialSubject.paymentOptionId"), "credentialSubject.paymentOptionId");
+    const extracted = ackPlacement.extract(credential);
+    if (!("ok" in extracted))
+        throw new Error(`ACK receipt carries no readable LCP reference (${extracted.haltClass}/${extracted.code})`);
+    if (extracted.value.type !== "sha256")
+        throw new Error(`ACK legalContext must be a sha256 carrier, got "${extracted.value.type}" — a locator commits to nothing`);
+    const owned = lcpKeys();
+    // `extract` above read the LCP key out of THIS map, so the map is an object and the narrowing cannot
+    // fail. Asserted rather than branched: a defensive `typeof` ternary here would ship an else-arm no input
+    // can reach, and its silent `[]` would under-report ACK's own refs on a receipt that has them.
+    const metadata = readAtPath(credential, "credentialSubject.metadata");
+    const siblingRefKeys = Object.keys(metadata).filter((k) => !owned.includes(k));
+    return {
+        atrHash: extracted.value.value,
+        paymentRequestToken,
+        paymentOptionId,
+        payerDid,
+        payerDidMethod: method,
+        issuerDid,
+        siblingRefKeys,
+    };
+}
+/**
+ * Split an issued receipt into its two rungs. `receiptBytes` are the retained credential exactly as it was
+ * received — the artifact is the bytes, not a re-serialization of the parse, because what the evidence
+ * package must hold is what the issuer signed.
+ */
+export function ackReceiptContribution(credential, receiptBytes) {
+    const facts = parseAckReceipt(credential);
+    return {
+        placement: { extracted: { type: "sha256", value: facts.atrHash } },
+        artifact: { role: "settlement", bytes: receiptBytes },
+        payerDid: facts.payerDid,
+        payerDidMethod: facts.payerDidMethod,
+        issuerDid: facts.issuerDid,
+        paymentRequestToken: facts.paymentRequestToken,
+    };
+}
+//# sourceMappingURL=proposal-ack.js.map

package/dist/proposal-ack.js.map

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

package/dist/proposal-acp.d.ts

@@ -0,0 +1,18 @@
+import type { GateProposal, ProposalContext } from "./proposal.js";
+/**
+ * Parse an ACP checkout session into the SAME typed `GateProposal` the x402 parser produces (the LCP §12.7
+ * boundary — no prose field on the type). Fail-fast (throws) on a malformed session, a reference that is not
+ * a canonical `lcp:sha256:0x…` 32-byte carrier, a non-HTTPS terms URL, a missing `total` row, or a
+ * non-integer minor-unit amount.
+ *
+ * `legal_context_url` is required, and the ACP placement manifest DECLARES it as
+ * `termsUrlField: "metadata.legal_context_url"` — the field this parser demands is a field the placement
+ * names, which is what makes the round-trip compose. It is deliberately NOT read from ACP's native
+ * `links[type=terms_of_use]`: that link is the merchant's standing policy page, while this names the ATR
+ * terms document for this transaction, and falling back to it would substitute one for the other.
+ *
+ * `GateProposal` and `ProposalContext` are IMPORTED, never redefined — one type for every wire is the whole
+ * point of a single typed proposal, and a second copy would let the two drift.
+ */
+export declare function parseProposalFromAcpCheckout(session: unknown, ctx: ProposalContext): GateProposal;
+//# sourceMappingURL=proposal-acp.d.ts.map

package/dist/proposal-acp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-acp.d.ts","sourceRoot":"","sources":["../src/proposal-acp.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAgBnE;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,eAAe,GACnB,YAAY,CAoDd"}

package/dist/proposal-acp.js

@@ -0,0 +1,72 @@
+import { decodeLegalContextString } from "@integraledger/lcp-binding-core";
+import { z } from "zod";
+// Module-internal structural view of the ACP checkout session (NOT the seller's type — buyer ≠ seller).
+// The session object is TOP-LEVEL and `totals` is an ARRAY (stable 2026-04-17); there is no `checkout`
+// wrapper and no `total` string. z.object strips unknown keys, so a real session's many other fields are
+// harmlessly ignored. Kept internal and not z.infer-exported (isolatedDeclarations), exactly as
+// X402ChallengeSchema is in proposal.ts.
+const AcpSessionSchema = z.object({
+    currency: z.string(),
+    totals: z.array(z.object({ type: z.string(), amount: z.number() })),
+    metadata: z.object({
+        legal_context: z.string(),
+        legal_context_url: z.string(),
+    }),
+});
+/**
+ * Parse an ACP checkout session into the SAME typed `GateProposal` the x402 parser produces (the LCP §12.7
+ * boundary — no prose field on the type). Fail-fast (throws) on a malformed session, a reference that is not
+ * a canonical `lcp:sha256:0x…` 32-byte carrier, a non-HTTPS terms URL, a missing `total` row, or a
+ * non-integer minor-unit amount.
+ *
+ * `legal_context_url` is required, and the ACP placement manifest DECLARES it as
+ * `termsUrlField: "metadata.legal_context_url"` — the field this parser demands is a field the placement
+ * names, which is what makes the round-trip compose. It is deliberately NOT read from ACP's native
+ * `links[type=terms_of_use]`: that link is the merchant's standing policy page, while this names the ATR
+ * terms document for this transaction, and falling back to it would substitute one for the other.
+ *
+ * `GateProposal` and `ProposalContext` are IMPORTED, never redefined — one type for every wire is the whole
+ * point of a single typed proposal, and a second copy would let the two drift.
+ */
+export function parseProposalFromAcpCheckout(session, ctx) {
+    const parsed = AcpSessionSchema.parse(session);
+    const { legal_context, legal_context_url } = parsed.metadata;
+    // Decoded through binding-core's codec, never by slicing a prefix. The codec enforces the canonical
+    // sha256 carrier form (0x-prefixed 32-byte hex) — a bare-digits value throws here rather than being
+    // silently re-prefixed into something that looks valid. An earlier draft did `0x${slice(...)}`, which
+    // turned a CONFORMANT 0x-carrying reference into `0x0x…` and accepted the non-canonical form instead.
+    const ref = decodeLegalContextString(legal_context);
+    if (ref === undefined)
+        throw new Error(`ACP legal_context is not a parseable lcp: reference: ${legal_context}`);
+    if (ref.type !== "sha256")
+        throw new Error(`ACP legal_context must be an lcp:sha256: reference, got lcp:${ref.type}:`);
+    // No 0x-32-byte re-check here. `decodeLegalContextString` runs `assertValidValue`, which for `sha256`
+    // IS `kernel.isAtrHash` — the identical `/^0x[0-9a-fA-F]{64}$/`. A second copy of that regex could not
+    // reject anything the decode admitted: it would be a branch no input reaches, permanently unkillable by
+    // any test, and it would tell a reader there is a case here that there is not. The x402 parser carries
+    // its own check because it reads a RAW `extra.atrHash` string that no codec has validated; this one
+    // does not, and that asymmetry is the point rather than an oversight.
+    if (!legal_context_url.startsWith("https://"))
+        throw new Error(`legalContextUrl must be HTTPS: ${legal_context_url}`);
+    // The `total` ROW, never the first row and never a sum. ACP's `totals` carries several typed rows
+    // (`items_base_amount`, `tax`, `fee`, `discount`, …) and only the one typed `total` is the amount the
+    // buyer is being asked to authorize. There is deliberately no fallback: a session with no `total` row is
+    // malformed, and picking another row would gate the buyer against a number nobody quoted.
+    const total = parsed.totals.find((t) => t.type === "total");
+    if (total === undefined)
+        throw new Error("ACP session carries no row typed `total` — nothing to authorize against");
+    if (!Number.isSafeInteger(total.amount) || total.amount < 0)
+        throw new Error(`offer amount must be a non-negative minor-unit integer: ${total.amount}`);
+    return {
+        advertisedAtrHash: ref.value,
+        legalContextUrl: legal_context_url,
+        level: ctx.level,
+        offer: {
+            amount: String(total.amount),
+            // ACP settles in a fiat currency code, not a network:asset pair — the unit string says which.
+            unit: parsed.currency,
+        },
+        sellerAssurance: ctx.sellerAssurance,
+    };
+}
+//# sourceMappingURL=proposal-acp.js.map

package/dist/proposal-acp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-acp.js","sourceRoot":"","sources":["../src/proposal-acp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,wGAAwG;AACxG,uGAAuG;AACvG,yGAAyG;AACzG,gGAAgG;AAChG,yCAAyC;AACzC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACnE,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACjB,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE;QACzB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE;KAC9B,CAAC;CACH,CAAC,CAAC;AAEH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,4BAA4B,CAC1C,OAAgB,EAChB,GAAoB;IAEpB,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC/C,MAAM,EAAE,aAAa,EAAE,iBAAiB,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC;IAE7D,oGAAoG;IACpG,oGAAoG;IACpG,sGAAsG;IACtG,sGAAsG;IACtG,MAAM,GAAG,GAAG,wBAAwB,CAAC,aAAa,CAAC,CAAC;IACpD,IAAI,GAAG,KAAK,SAAS;QACnB,MAAM,IAAI,KAAK,CACb,wDAAwD,aAAa,EAAE,CACxE,CAAC;IACJ,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;QACvB,MAAM,IAAI,KAAK,CACb,+DAA+D,GAAG,CAAC,IAAI,GAAG,CAC3E,CAAC;IACJ,sGAAsG;IACtG,uGAAuG;IACvG,wGAAwG;IACxG,uGAAuG;IACvG,oGAAoG;IACpG,sEAAsE;IAEtE,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,UAAU,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,kCAAkC,iBAAiB,EAAE,CAAC,CAAC;IAEzE,kGAAkG;IAClG,sGAAsG;IACtG,yGAAyG;IACzG,0FAA0F;IAC1F,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC;IAC5D,IAAI,KAAK,KAAK,SAAS;QACrB,MAAM,IAAI,KAAK,CACb,yEAAyE,CAC1E,CAAC;IACJ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;QACzD,MAAM,IAAI,KAAK,CACb,2DAA2D,KAAK,CAAC,MAAM,EAAE,CAC1E,CAAC;IAEJ,OAAO;QACL,iBAAiB,EAAE,GAAG,CAAC,KAAsB;QAC7C,eAAe,EAAE,iBAAiB;QAClC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,KAAK,EAAE;YACL,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;YAC5B,8FAA8F;YAC9F,IAAI,EAAE,MAAM,CAAC,QAAQ;SACtB;QACD,eAAe,EAAE,GAAG,CAAC,eAAe;KACrC,CAAC;AACJ,CAAC"}

package/dist/proposal-ap2.d.ts

@@ -0,0 +1,121 @@
+/**
+ * The AP2 buyer surface: read the LCP reference off the transport envelope that carries an AP2 mandate, and
+ * name the moment "verify before sign" is measured against.
+ *
+ * AP2 is the one wire in this set where the sign moment is genuinely ambiguous. x402 has one (the EIP-3009
+ * authorization), ACP has one (the checkout confirmation). AP2 has FOUR mandates — Checkout and Payment,
+ * each in an Open and a Closed stage — signed by different keys in different modes. A gate that says "verify
+ * before sign" without saying WHICH sign is a gate that cannot be audited, so `AP2_HALT_POINT` names it, and
+ * `parseProposalFromAp2Envelope` refuses to run at or after it.
+ */
+import type { GateProposal, ProposalContext } from "./proposal.js";
+/**
+ * The steps of AP2 v0.2's authorization flow, in the order a Shopping Agent passes through them. CLOSED —
+ * an unknown token is a wire this parser has no halt point for, and inventing one would be the whole defect
+ * this type exists to prevent.
+ *
+ * `agent-key-signing` occurs in Autonomous mode only; `key-binding-presentation` is the `kb+sd-jwt` binding
+ * made when the closed mandate is PRESENTED to the merchant, which is why it is a separate step from the
+ * signature that created the mandate.
+ */
+export type Ap2Step = "checkout-jwt-received" | "mandate-content-built" | "trusted-surface-authorization" | "agent-key-signing" | "key-binding-presentation";
+/** The named sign moment, its defence, and the last step at which gating is still meaningful. */
+export interface Ap2HaltPoint {
+    /** The last step at which no signing key has been invoked — where the gate must have finished. */
+    readonly lastSafeStep: Ap2Step;
+    /** The first step at which a signing key IS invoked. The gate halts strictly before this. */
+    readonly haltBefore: Ap2Step;
+    /** Every step at which some key signs, in flow order. `haltBefore` is the first of them. */
+    readonly signingSteps: readonly Ap2Step[];
+    /** Why this step and not another — the argument, not a restatement of the field. */
+    readonly rationale: string;
+    /** The host protocol's own text this is defended against — AP2 decides its flow, not LCP's appendix. */
+    readonly specRef: string;
+}
+/**
+ * AP2's halt point: **immediately before the Trusted Surface is invoked.**
+ *
+ * The defence, from AP2 v0.2's own specification rather than from LCP's Appendix C:
+ *
+ * - **Human Present (Direct).** "When a Shopping Agent has a Checkout JWT for the closed Checkout from the
+ *   Merchant, they construct the Checkout and Payment Mandate Content and pass it to a Trusted Surface for
+ *   display to the user and signing." The user's key signs at the Trusted Surface. Nothing signs before it.
+ * - **Human Not Present (Autonomous).** "When a Shopping Agent needs to operate autonomously, it will create
+ *   open Checkout and Payment Mandate Content and have these authorized by the Trusted Surface. These MUST
+ *   include the agent's public key as a `cnf` claim." The Trusted Surface is invoked FIRST here too; the
+ *   Shopping Agent's own Agent Key signs the closed mandates only afterwards.
+ *
+ * So both modes place the Trusted Surface first, and that makes it the halt point for both — the gate does
+ * not need to know which mode it is in, which is the property that makes this auditable. `agent-key-signing`
+ * is a later signing step, not an earlier one, and gating there would already be too late.
+ *
+ * **And the window closes hard.** The closed Checkout Mandate carries `checkout_hash`, "a base64url-encoded
+ * hash of the merchant-signed `checkout_jwt`", the Payment Mandate "is bound to a particular Checkout using
+ * the cryptographic hash of the Checkout JWT", and the closed mandate is a `kb+sd-jwt` whose key-binding
+ * signature is constructed over `sd_hash` **at presentation**. Once the Trusted Surface has signed, nothing
+ * inside either mandate is mutable and no later verification can be turned back into a decision.
+ *
+ * **This is a HALT POINT, not a placement constraint.** The reference rides the transport envelope's
+ * metadata, which AP2 never signs and never reads — so the SELLER may place it at any time, under no
+ * ordering precondition at all. Contrast ACK, where placement must happen BEFORE the issuer signs: a field
+ * added after issuance either breaks the embedded signature or falls outside the payload the host treats as
+ * authoritative. What is time-critical here is the BUYER's decision, because after this step the buyer has
+ * no decision left to make.
+ */
+export declare const AP2_HALT_POINT: Ap2HaltPoint;
+/** Does this step invoke a signing key? Membership in `AP2_HALT_POINT.signingSteps`, as a function. */
+export declare function isAp2SigningStep(step: Ap2Step): boolean;
+/**
+ * Throw unless the client is still strictly before the halt point.
+ *
+ * Fail-fast rather than a returned flag: a caller that gates at `agent-key-signing` has already handed the
+ * user's key to the Trusted Surface, and there is no honest outcome to report at that point — the decision
+ * the gate exists to make has already been made by someone else.
+ */
+export declare function assertBeforeAp2HaltPoint(step: Ap2Step): void;
+/**
+ * The context AP2's wire does NOT carry, which the buyer's client establishes — and it is more than the
+ * other parsers need, for two reasons that are both properties of AP2 rather than gaps here.
+ */
+export interface Ap2ProposalContext extends ProposalContext {
+    /**
+     * The terms document's locator.
+     *
+     * AP2's placement is INTEGRITY-ONLY: `AP2_PLACEMENT` declares no `termsUrlField`, because the A2A
+     * `Message.metadata` map holds the reference and AP2 models no terms-URL field anywhere. So unlike ACP
+     * (`metadata.legal_context_url`) and x402 (`extra.legalContextUrl`), the locator cannot come off the wire.
+     * It comes from LCP §2 discovery — the seller's `/.well-known/legal-context.json` — resolved by the
+     * client before it calls this parser. HTTPS is enforced here exactly as it is on every other wire.
+     */
+    readonly legalContextUrl: string;
+    /**
+     * The offer the client is about to authorize.
+     *
+     * AP2 v0.2 carries the price inside the merchant-signed Checkout JWT, referenced from the closed mandate
+     * only by `checkout_hash`. The transport carries mandates as OPAQUE SD-JWT compact strings; this parser
+     * does not decode one, and decoding one would mean trusting an unverified payload to produce the number
+     * the gate compares against a policy cap. The client already holds the checkout it built its Mandate
+     * Content from, so it supplies the amount it is about to commit — the honest source.
+     */
+    readonly offer: {
+        readonly amount: string;
+        readonly unit: string;
+    };
+    /** Where the client is in AP2's flow. At or after the halt point this parser refuses. */
+    readonly step: Ap2Step;
+}
+/**
+ * Parse an AP2 transport envelope into the SAME typed `GateProposal` every other wire produces.
+ *
+ * The reference is read through `@integraledger/lcp-placement-ap2`, never through a hand-rolled path. The
+ * manifest declares both the canonical `metadata.legalContext` and the snake_case alias
+ * `metadata.legal_context`; a second reader here would be a second spelling of the manifest, free to drift
+ * from the one the seller writes through. It also inherits the placement's deliberate blindness to the Tier
+ * B shape — a reference embedded INSIDE the mandate is not read, so a buyer cannot be walked into blessing
+ * a placement no shipped package can emit, because LCP's appendix illustrates and the host protocol binds.
+ *
+ * Fail-fast (throws) on: a step at or after `AP2_HALT_POINT`, an envelope carrying no reference, a carrier
+ * that is not `sha256`, a non-HTTPS terms URL, or a non-base-unit-integer amount.
+ */
+export declare function parseProposalFromAp2Envelope(envelope: unknown, ctx: Ap2ProposalContext): GateProposal;
+//# sourceMappingURL=proposal-ap2.d.ts.map

package/dist/proposal-ap2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-ap2.d.ts","sourceRoot":"","sources":["../src/proposal-ap2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEnE;;;;;;;;GAQG;AACH,MAAM,MAAM,OAAO,GACf,uBAAuB,GACvB,uBAAuB,GACvB,+BAA+B,GAC/B,mBAAmB,GACnB,0BAA0B,CAAC;AAE/B,iGAAiG;AACjG,MAAM,WAAW,YAAY;IAC3B,kGAAkG;IAClG,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,6FAA6F;IAC7F,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,4FAA4F;IAC5F,QAAQ,CAAC,YAAY,EAAE,SAAS,OAAO,EAAE,CAAC;IAC1C,oFAAoF;IACpF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wGAAwG;IACxG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,cAAc,EAAE,YAY5B,CAAC;AAEF,uGAAuG;AACvG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAM5D;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACzD;;;;;;;;OAQG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,OAAO,EACjB,GAAG,EAAE,kBAAkB,GACtB,YAAY,CAoCd"}

package/dist/proposal-ap2.js

@@ -0,0 +1,112 @@
+/**
+ * The AP2 buyer surface: read the LCP reference off the transport envelope that carries an AP2 mandate, and
+ * name the moment "verify before sign" is measured against.
+ *
+ * AP2 is the one wire in this set where the sign moment is genuinely ambiguous. x402 has one (the EIP-3009
+ * authorization), ACP has one (the checkout confirmation). AP2 has FOUR mandates — Checkout and Payment,
+ * each in an Open and a Closed stage — signed by different keys in different modes. A gate that says "verify
+ * before sign" without saying WHICH sign is a gate that cannot be audited, so `AP2_HALT_POINT` names it, and
+ * `parseProposalFromAp2Envelope` refuses to run at or after it.
+ */
+import { ap2Placement } from "@integraledger/lcp-placement-ap2";
+/**
+ * AP2's halt point: **immediately before the Trusted Surface is invoked.**
+ *
+ * The defence, from AP2 v0.2's own specification rather than from LCP's Appendix C:
+ *
+ * - **Human Present (Direct).** "When a Shopping Agent has a Checkout JWT for the closed Checkout from the
+ *   Merchant, they construct the Checkout and Payment Mandate Content and pass it to a Trusted Surface for
+ *   display to the user and signing." The user's key signs at the Trusted Surface. Nothing signs before it.
+ * - **Human Not Present (Autonomous).** "When a Shopping Agent needs to operate autonomously, it will create
+ *   open Checkout and Payment Mandate Content and have these authorized by the Trusted Surface. These MUST
+ *   include the agent's public key as a `cnf` claim." The Trusted Surface is invoked FIRST here too; the
+ *   Shopping Agent's own Agent Key signs the closed mandates only afterwards.
+ *
+ * So both modes place the Trusted Surface first, and that makes it the halt point for both — the gate does
+ * not need to know which mode it is in, which is the property that makes this auditable. `agent-key-signing`
+ * is a later signing step, not an earlier one, and gating there would already be too late.
+ *
+ * **And the window closes hard.** The closed Checkout Mandate carries `checkout_hash`, "a base64url-encoded
+ * hash of the merchant-signed `checkout_jwt`", the Payment Mandate "is bound to a particular Checkout using
+ * the cryptographic hash of the Checkout JWT", and the closed mandate is a `kb+sd-jwt` whose key-binding
+ * signature is constructed over `sd_hash` **at presentation**. Once the Trusted Surface has signed, nothing
+ * inside either mandate is mutable and no later verification can be turned back into a decision.
+ *
+ * **This is a HALT POINT, not a placement constraint.** The reference rides the transport envelope's
+ * metadata, which AP2 never signs and never reads — so the SELLER may place it at any time, under no
+ * ordering precondition at all. Contrast ACK, where placement must happen BEFORE the issuer signs: a field
+ * added after issuance either breaks the embedded signature or falls outside the payload the host treats as
+ * authoritative. What is time-critical here is the BUYER's decision, because after this step the buyer has
+ * no decision left to make.
+ */
+export const AP2_HALT_POINT = {
+    lastSafeStep: "mandate-content-built",
+    haltBefore: "trusted-surface-authorization",
+    signingSteps: [
+        "trusted-surface-authorization",
+        "agent-key-signing",
+        "key-binding-presentation",
+    ],
+    rationale: "Both AP2 modes invoke the Trusted Surface before any other key: in Direct mode the Shopping Agent passes the Mandate Content to it for user signing, and in Autonomous mode it authorizes the OPEN mandates before the Agent Key signs the closed ones. It is therefore the first signing step in either mode, and the closed mandate's checkout_hash plus its presentation-time key binding leave nothing mutable afterwards.",
+    specRef: "AP2 v0.2 (google-agentic-commerce/AP2 @ main, release 0.2.0 dated 2026-04-28) docs/ap2/specification.md §Human Present / §Human Not Present, and docs/ap2/checkout_mandate.md (vct mandate.checkout.1, checkout_hash, kb+sd-jwt over sd_hash at presentation); read 2026-07-30",
+};
+/** Does this step invoke a signing key? Membership in `AP2_HALT_POINT.signingSteps`, as a function. */
+export function isAp2SigningStep(step) {
+    return AP2_HALT_POINT.signingSteps.includes(step);
+}
+/**
+ * Throw unless the client is still strictly before the halt point.
+ *
+ * Fail-fast rather than a returned flag: a caller that gates at `agent-key-signing` has already handed the
+ * user's key to the Trusted Surface, and there is no honest outcome to report at that point — the decision
+ * the gate exists to make has already been made by someone else.
+ */
+export function assertBeforeAp2HaltPoint(step) {
+    if (isAp2SigningStep(step))
+        throw new Error(`AP2 gate refused at "${step}": that is at or after the halt point (${AP2_HALT_POINT.haltBefore}). ` +
+            `Verify before sign means gating no later than "${AP2_HALT_POINT.lastSafeStep}". ${AP2_HALT_POINT.rationale}`);
+}
+const BASE_UNIT_INT = /^[0-9]+$/; // decimal base-unit integer — no sign, no decimal point, non-empty
+/**
+ * Parse an AP2 transport envelope into the SAME typed `GateProposal` every other wire produces.
+ *
+ * The reference is read through `@integraledger/lcp-placement-ap2`, never through a hand-rolled path. The
+ * manifest declares both the canonical `metadata.legalContext` and the snake_case alias
+ * `metadata.legal_context`; a second reader here would be a second spelling of the manifest, free to drift
+ * from the one the seller writes through. It also inherits the placement's deliberate blindness to the Tier
+ * B shape — a reference embedded INSIDE the mandate is not read, so a buyer cannot be walked into blessing
+ * a placement no shipped package can emit, because LCP's appendix illustrates and the host protocol binds.
+ *
+ * Fail-fast (throws) on: a step at or after `AP2_HALT_POINT`, an envelope carrying no reference, a carrier
+ * that is not `sha256`, a non-HTTPS terms URL, or a non-base-unit-integer amount.
+ */
+export function parseProposalFromAp2Envelope(envelope, ctx) {
+    // FIRST, before any reading. A gate that parses and then discovers it was too late has already spent the
+    // buyer's time pretending a decision was available.
+    assertBeforeAp2HaltPoint(ctx.step);
+    const extracted = ap2Placement.extract(envelope);
+    if (!("ok" in extracted))
+        throw new Error(`AP2 envelope carries no readable LCP reference (${extracted.haltClass}/${extracted.code})`);
+    const ref = extracted.value;
+    if (ref.type !== "sha256")
+        throw new Error(`AP2 legalContext must be a sha256 carrier, got "${ref.type}" — the gate compares the advertised ` +
+            "hash against a recomputed one, and a locator commits to nothing");
+    if (!ctx.legalContextUrl.startsWith("https://"))
+        throw new Error(`legalContextUrl must be HTTPS: ${ctx.legalContextUrl}`);
+    if (!BASE_UNIT_INT.test(ctx.offer.amount))
+        throw new Error(`offer amount must be a base-unit integer string: "${ctx.offer.amount}"`);
+    // No 0x-32-byte re-check: `extract` decodes through binding-core's codec, whose `sha256` validity rule IS
+    // `kernel.isAtrHash`. A second copy of that regex could reject nothing the decode admitted — the same
+    // asymmetry `proposal-acp.ts` documents, and for the same reason.
+    return {
+        advertisedAtrHash: ref.value,
+        legalContextUrl: ctx.legalContextUrl,
+        level: ctx.level,
+        offer: {
+            amount: ctx.offer.amount,
+            unit: ctx.offer.unit,
+        },
+        sellerAssurance: ctx.sellerAssurance,
+    };
+}
+//# sourceMappingURL=proposal-ap2.js.map

package/dist/proposal-ap2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-ap2.js","sourceRoot":"","sources":["../src/proposal-ap2.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAiChE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,cAAc,GAAiB;IAC1C,YAAY,EAAE,uBAAuB;IACrC,UAAU,EAAE,+BAA+B;IAC3C,YAAY,EAAE;QACZ,+BAA+B;QAC/B,mBAAmB;QACnB,0BAA0B;KAC3B;IACD,SAAS,EACP,gaAAga;IACla,OAAO,EACL,gRAAgR;CACnR,CAAC;AAEF,uGAAuG;AACvG,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,OAAO,cAAc,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CAAC,IAAa;IACpD,IAAI,gBAAgB,CAAC,IAAI,CAAC;QACxB,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,0CAA0C,cAAc,CAAC,UAAU,KAAK;YAClG,kDAAkD,cAAc,CAAC,YAAY,MAAM,cAAc,CAAC,SAAS,EAAE,CAChH,CAAC;AACN,CAAC;AAkCD,MAAM,aAAa,GAAG,UAAU,CAAC,CAAC,mEAAmE;AAErG;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,4BAA4B,CAC1C,QAAiB,EACjB,GAAuB;IAEvB,yGAAyG;IACzG,oDAAoD;IACpD,wBAAwB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAEnC,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACjD,IAAI,CAAC,CAAC,IAAI,IAAI,SAAS,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,mDAAmD,SAAS,CAAC,SAAS,IAAI,SAAS,CAAC,IAAI,GAAG,CAC5F,CAAC;IACJ,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC;IAC5B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ;QACvB,MAAM,IAAI,KAAK,CACb,mDAAmD,GAAG,CAAC,IAAI,uCAAuC;YAChG,iEAAiE,CACpE,CAAC;IACJ,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,UAAU,CAAC,UAAU,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,kCAAkC,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC;IAC3E,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC;QACvC,MAAM,IAAI,KAAK,CACb,qDAAqD,GAAG,CAAC,KAAK,CAAC,MAAM,GAAG,CACzE,CAAC;IAEJ,0GAA0G;IAC1G,sGAAsG;IACtG,kEAAkE;IAClE,OAAO;QACL,iBAAiB,EAAE,GAAG,CAAC,KAAsB;QAC7C,eAAe,EAAE,GAAG,CAAC,eAAe;QACpC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,KAAK,EAAE;YACL,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM;YACxB,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI;SACrB;QACD,eAAe,EAAE,GAAG,CAAC,eAAe;KACrC,CAAC;AACJ,CAAC"}

package/dist/proposal-mpp.d.ts

@@ -0,0 +1,44 @@
+import type { GateProposal, ProposalContext } from "./proposal.js";
+/**
+ * Parse an MPP `request` body into the SAME typed `GateProposal` the x402 and ACP parsers produce (the
+ * LCP §12.7 boundary — no prose field on the type). Fail-fast (throws) on a malformed body, an absent or
+ * non-0x-32-byte `atrHash`, a non-HTTPS terms URL, or a non-base-unit-integer amount.
+ *
+ * **The document is the `request` body, not the challenge.** MPP's identity lives one layer out, in the
+ * `WWW-Authenticate: Payment` challenge's auth-params; the body this parses is the base64url(JCS(JSON))
+ * payload that challenge's `request` auth-param carries. A caller holding a decoded body is expected to
+ * have decoded it from there.
+ *
+ * **BY NAME, and deliberately not in `PROPOSAL_PARSERS`.** MPP's discriminant is recorded as
+ * `kind: "undiscriminable"`: the body's members are `amount` and `currency` plus optionals, and an
+ * amount/currency pair is the shape of almost every payment document there is. Nothing in the body names
+ * MPP. So a caller must name `mpp` and reach this function directly — the same by-name route
+ * `parseProposalFromAp2Envelope` takes, and for a sibling reason. Adding an `mpp` row to the universal
+ * dispatch map would not make it reachable; it would make the map claim a discrimination it cannot perform.
+ *
+ * **The carrier is `bare-value`, so no codec has validated it.** `placement-mpp` declares
+ * `field: "methodDetails.atrHash"` with `encoding: "bare-value"` and `carrierTypes: ["sha256"]` — the wire
+ * carries the raw hash rather than an `lcp:sha256:0x…` string. That is why this validates the hash itself
+ * through the kernel's `isAtrHash`, as the x402 parser validates its raw `extra.atrHash`, and why it does
+ * NOT call `decodeLegalContextString` as the ACP parser does. Using the kernel's own predicate rather than
+ * restating its regex keeps one definition of what an ATR hash is.
+ *
+ * **`legalContextUrl` is the field the placement names.** `placement-mpp` declares
+ * `termsUrlField: "methodDetails.legalContextUrl"`, so the field this parser demands is the field the
+ * manifest names — which is what makes the seller's write and this buyer's read compose. There is no
+ * fallback to any other member: MPP defines none that means "these terms", and inventing one would gate the
+ * buyer against a document nobody pointed at.
+ *
+ * **What the carrier is worth is weaker than Tier A alone suggests, and the buyer should know it.** MPP
+ * binds the challenge `id` to the challenge parameters, so a client cannot alter the advertised values and
+ * still be accepted — but the binding key is a server secret the specification requires implementations to
+ * keep server-side, so **the buyer cannot verify that MAC.** What this reference gets is tamper-evidence,
+ * not a buyer-verifiable seller commitment. The gate treats it as an advertised value to be recomputed
+ * against fetched bytes, exactly as it treats every other protocol's, and that recomputation is what the
+ * guarantee actually rests on.
+ *
+ * `GateProposal` and `ProposalContext` are IMPORTED, never redefined — one type for every wire is the whole
+ * point of a single typed proposal, and a second copy would let the two drift.
+ */
+export declare function parseProposalFromMppRequest(request: unknown, ctx: ProposalContext): GateProposal;
+//# sourceMappingURL=proposal-mpp.d.ts.map