@integraledger/agent-guard 0.9.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-mpp.d.ts","sourceRoot":"","sources":["../src/proposal-mpp.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAgCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAChB,GAAG,EAAE,eAAe,GACnB,YAAY,CA8Cd"}

package/dist/proposal-mpp.js

@@ -0,0 +1,106 @@
+import { isAtrHash } from "@integraledger/lcp-kernel";
+import { z } from "zod";
+// Module-internal structural view of the MPP `request` body (NOT the seller's type — buyer ≠ seller).
+// `z.object` strips unknown keys, so the optional members this parser has no use for — `description`,
+// `expires`, `externalId`, `recipient` — are harmlessly ignored. Kept internal and not `z.infer`-exported
+// (isolatedDeclarations), exactly as `X402ChallengeSchema` and `AcpSessionSchema` are.
+//
+// `methodDetails` is OPTIONAL in the charge intent (draft-payment-intent-charge-00 §5.1.2, Table 3), which
+// is why it is optional here and its absence is a refusal below rather than a schema error: a request body
+// with no `methodDetails` is a perfectly conformant MPP document that simply advertises no LCP reference,
+// and saying so is more useful than a Zod path error.
+const MppRequestSchema = z.object({
+    amount: z.string(),
+    currency: z.string(),
+    methodDetails: z
+        .object({
+        atrHash: z.string().optional(),
+        legalContextUrl: z.string().optional(),
+    })
+        .optional(),
+});
+// Decimal base-unit integer — no sign, no decimal point, non-empty. Identical in shape to the x402 parser's
+// check and required for the same reason: `policy.ts` compares the offer with `BigInt(offer.amount)`, and
+// `BigInt("10.50")` THROWS rather than returning, which would escape `evaluate`'s contract to RETURN a
+// `GateDecision`. The grammar is the host's, not ours: draft-payment-intent-charge-00 Table 2 defines
+// `amount` as "Payment amount in base units (smallest denomination)", and §3 defines base units as "the
+// smallest denomination of a currency or asset. For USD, this is cents (1/100)." Every example in the
+// specification agrees — "5000"/usd, "1000000"/token, "100000"/sat — so a decimal amount is malformed MPP
+// and is refused here rather than thrown from inside the gate.
+const BASE_UNIT_INT = /^[0-9]+$/;
+/**
+ * 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 function parseProposalFromMppRequest(request, ctx) {
+    const parsed = MppRequestSchema.parse(request);
+    // Absence is a refusal, not a permission. A conformant MPP body may omit `methodDetails` entirely, and
+    // may carry one that names no LCP reference; neither is a document this gate can bind terms from, and
+    // both are named rather than collapsed into one message so a seller reading the error knows which it is.
+    const details = parsed.methodDetails;
+    if (details === undefined)
+        throw new Error("MPP request body carries no `methodDetails` — nothing advertises an LCP reference");
+    const { atrHash, legalContextUrl } = details;
+    if (atrHash === undefined)
+        throw new Error("MPP request body advertises no `methodDetails.atrHash` — the placement's declared carrier is absent");
+    if (legalContextUrl === undefined)
+        throw new Error("MPP request body advertises no `methodDetails.legalContextUrl` — the placement's declared terms-URL field is absent");
+    if (!isAtrHash(atrHash))
+        throw new Error(`advertised atrHash is not a 0x-prefixed 32-byte hex: ${atrHash}`);
+    if (!legalContextUrl.startsWith("https://"))
+        throw new Error(`legalContextUrl must be HTTPS: ${legalContextUrl}`);
+    if (!BASE_UNIT_INT.test(parsed.amount))
+        throw new Error(`offer amount must be a base-unit integer string: "${parsed.amount}"`);
+    return {
+        advertisedAtrHash: atrHash,
+        legalContextUrl,
+        level: ctx.level,
+        offer: {
+            amount: parsed.amount,
+            // MPP's `currency` is a "Currency or asset identifier" (Table 2) and spans the whole family — an ISO
+            // 4217 code for `card`/`stripe`, a token address for `evm`, `sat` for `lightning`. It is carried
+            // verbatim as the unit string, exactly as ACP's fiat code and x402's `network:asset` pair are: the
+            // gate compares units for equality against the buyer's cap and never interprets them.
+            unit: parsed.currency,
+        },
+        sellerAssurance: ctx.sellerAssurance,
+    };
+}
+//# sourceMappingURL=proposal-mpp.js.map

package/dist/proposal-mpp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proposal-mpp.js","sourceRoot":"","sources":["../src/proposal-mpp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AACtD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,sGAAsG;AACtG,sGAAsG;AACtG,0GAA0G;AAC1G,uFAAuF;AACvF,EAAE;AACF,2GAA2G;AAC3G,2GAA2G;AAC3G,0GAA0G;AAC1G,sDAAsD;AACtD,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,aAAa,EAAE,CAAC;SACb,MAAM,CAAC;QACN,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC9B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;KACvC,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC;AAEH,4GAA4G;AAC5G,0GAA0G;AAC1G,uGAAuG;AACvG,sGAAsG;AACtG,wGAAwG;AACxG,sGAAsG;AACtG,0GAA0G;AAC1G,+DAA+D;AAC/D,MAAM,aAAa,GAAG,UAAU,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAgB,EAChB,GAAoB;IAEpB,MAAM,MAAM,GAAG,gBAAgB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAE/C,uGAAuG;IACvG,sGAAsG;IACtG,yGAAyG;IACzG,MAAM,OAAO,GAAG,MAAM,CAAC,aAAa,CAAC;IACrC,IAAI,OAAO,KAAK,SAAS;QACvB,MAAM,IAAI,KAAK,CACb,mFAAmF,CACpF,CAAC;IACJ,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC;IAC7C,IAAI,OAAO,KAAK,SAAS;QACvB,MAAM,IAAI,KAAK,CACb,qGAAqG,CACtG,CAAC;IACJ,IAAI,eAAe,KAAK,SAAS;QAC/B,MAAM,IAAI,KAAK,CACb,qHAAqH,CACtH,CAAC;IAEJ,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,wDAAwD,OAAO,EAAE,CAClE,CAAC;IACJ,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,UAAU,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,kCAAkC,eAAe,EAAE,CAAC,CAAC;IACvE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC;QACpC,MAAM,IAAI,KAAK,CACb,qDAAqD,MAAM,CAAC,MAAM,GAAG,CACtE,CAAC;IAEJ,OAAO;QACL,iBAAiB,EAAE,OAAO;QAC1B,eAAe;QACf,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,KAAK,EAAE;YACL,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,qGAAqG;YACrG,iGAAiG;YACjG,mGAAmG;YACnG,sFAAsF;YACtF,IAAI,EAAE,MAAM,CAAC,QAAQ;SACtB;QACD,eAAe,EAAE,GAAG,CAAC,eAAe;KACrC,CAAC;AACJ,CAAC"}

package/dist/proposal-universal.d.ts

@@ -0,0 +1,239 @@
+import { type ProtocolId } from "@integraledger/lcp-binding-core";
+import { type PlacementDeployment } from "@integraledger/lcp-placements";
+import { type GateProposal, type ProposalContext } from "./proposal.js";
+/**
+ * ACP's `CheckoutSession.status` — the closed eleven-value enum, and the discriminant that separates an ACP
+ * session from every other checkout-shaped document in the set.
+ *
+ * DERIVED, NOT AUTHORED — from the live ACP schema, which `placement-acp` enumerated protocol-side in a
+ * write condition it no longer declares (checked 2026-07-30).
+ *
+ * ⚠️ THIS COPY NO LONGER HAS A DRIFT GUARD. It was pinned equal to the manifest's write condition through
+ * the registry, but the protocol line declares no `writeCondition` on any ACP manifest — its `readAlso` aliases
+ * carry `{path, encoding}` only — so the enum is not published anywhere to pin against. The pin test was
+ * deleted rather than loosened (an assertion over an absent field guards nothing). Re-derive this list
+ * against the live ACP schema when touching it; the discriminant tests only prove it matches our fixtures.
+ */
+export declare const ACP_SESSION_STATUS: readonly string[];
+/**
+ * The two Verifiable Intent Autonomous-mode credential types, derived from Mastercard's own open-mandate
+ * definitions. Formerly pinned against `placement-mastercard-vi`'s write condition; that placement is now
+ * declaration-only (LCP v1.38 §C.7 — an unregistered constraint type gets the WHOLE mandate rejected by a
+ * stock verifier), so it declares no write condition and there is nothing to pin against. Same standing as
+ * {@link ACP_SESSION_STATUS}: hand-kept, re-derive against the host when touching it.
+ */
+export declare const VI_OPEN_MANDATE_VCT: readonly string[];
+/**
+ * How ONE protocol's document is recognized — or the recorded fact that it cannot be.
+ *
+ * A keyed union rather than an optional `matches`, because "no rule" and "a rule that never fires" are
+ * different claims and only one of them is honest about a protocol whose document carries nothing to
+ * recognize. An `undiscriminable` row is a finding with a citation, not a hole: it says the live specification
+ * was read and no identifying member exists, which is the answer a future unit needs in order not to redo the
+ * reading, and it keeps the table TOTAL over the placement registry so a newly registered protocol cannot slip
+ * in unnoticed.
+ *
+ * `cite` is data rather than a comment because a claim about somebody else's protocol is exactly the kind that
+ * gets stale, and an audit trail that only a reader of the source can see is not one a deployment can act on.
+ */
+export type ProtocolDiscriminant = {
+    readonly protocol: ProtocolId;
+    readonly kind: "structural";
+    /** Does this document belong to `protocol`? TOTAL — never throws, on any shape a wire can present. */
+    readonly matches: (doc: unknown) => boolean;
+    /** The host protocol's own source the rule was read from, and when. */
+    readonly cite: string;
+} | {
+    readonly protocol: ProtocolId;
+    readonly kind: "undiscriminable";
+    /** Why no rule exists, and where the protocol's identity actually lives instead. */
+    readonly reason: string;
+    readonly cite: string;
+};
+/**
+ * Every supported protocol's document discriminant, one row each.
+ *
+ * DETECTION IS BY DISCRIMINANT, NEVER BY "does the field I want happen to be present": a document is x402
+ * because it carries `x402Version`, not because it has an atrHash somewhere. Detecting on the LCP field would
+ * make every protocol look alike the moment it carried a reference — which is exactly the situation this table
+ * exists to disambiguate.
+ *
+ * EVERY RULE IS POSITIVE. No row says "and not the other protocol's marker". Documents CAN satisfy two rows,
+ * and where they do the answer is AMBIGUITY, which {@link parseProposalUniversal} refuses. A negative term
+ * would convert that refusal into a silent choice, and a wrong negative term (one protocol adding a field
+ * another already had) converts it into a silent WRONG choice. Refusing is never the wrong answer; guessing
+ * sometimes is.
+ *
+ * THE TWO OVERLAPS ARE NOT THE SAME STRENGTH, and the difference is load-bearing:
+ *
+ *  - ACP/UCP is CONTINGENT. A UCP checkout response that also carries `currency`, `totals` and `line_items`
+ *    satisfies both rows; one that does not carries only `ucp`, `id`, `status` and `links` and is
+ *    unambiguously UCP. Either protocol's documents remain individually reachable.
+ *  - AP2/A2A is TOTAL. `ap2` matches `carriesAp2Mandate(doc) && isA2aMessage(doc)`, and `a2a` matches
+ *    `isA2aTask(doc) || isA2aMessage(doc)`, so the `ap2` predicate is a strict logical SUBSET of the `a2a`
+ *    one: every document the AP2 row fires on fires the A2A row too, without exception and by construction.
+ *    So NO AP2 document is reachable through {@link parseProposalUniversal} — the ambiguity refusal always
+ *    triggers first, and registering an `ap2` entry in {@link PROPOSAL_PARSERS} would not make one parseable.
+ *    A caller holding an AP2 envelope names `ap2` and calls its parser directly. That is a consequence of AP2
+ *    defining no transport of its own (v0.2 rides A2A), not a defect to engineer away: a negative term on the
+ *    A2A row would be this package asserting that a valid A2A message is not one, which is A2A's call to
+ *    make rather than ours — the host protocol defines its own documents.
+ *
+ * ORDERED as `KNOWN_PROTOCOL_IDS` orders the closed set, so `matchProtocols` reports in a stable order rather
+ * than in the order units happened to land.
+ */
+export declare const PROTOCOL_DISCRIMINANTS: readonly ProtocolDiscriminant[];
+/**
+ * Every protocol whose discriminant this document satisfies, in the table's order.
+ *
+ * ALL matches, never the first. A first-match detector cannot tell a document that belongs to one protocol
+ * from a document that belongs to two, and the second case is the one that costs a buyer money: an AP2
+ * envelope IS an A2A message, so both rows fire on it, and answering "a2a" because it came first would be a
+ * guess wearing an answer's clothes.
+ */
+export declare function matchProtocols(wire: unknown): readonly ProtocolId[];
+/**
+ * Identify which commerce protocol a wire document belongs to, structurally.
+ *
+ * Returns `undefined` unless EXACTLY ONE discriminant fires — so both "nothing matched" and "several matched"
+ * answer `undefined`, because a single-valued return cannot honestly distinguish them and inventing a
+ * preference is the failure this function exists to prevent. A caller that needs to tell the two apart calls
+ * {@link matchProtocols} and reads the length; {@link parseProposalUniversal} does exactly that, and refuses
+ * each case with its own message.
+ *
+ * This function never guesses and never throws.
+ */
+export declare function detectProtocol(wire: unknown): ProtocolId | undefined;
+/**
+ * The terms URL a document advertises at the path its manifest declares — or the reason there is no answer,
+ * stated rather than folded into an `undefined`.
+ *
+ * A UNION, because `string | undefined` conflated three facts and only two of them are absences. The third is
+ * x402 today: `PlacementManifest.termsUrlField` is SINGULAR, and x402's names a path INSIDE the
+ * `extensions.legalContext.info` carrier — while the challenge LCP v1.38 §C.4 illustrates carries both the
+ * reference and the URL in `accepts[].extra` instead, which the manifest declares as a `readAlso` alias. Read
+ * such a challenge and the hash answers from the alias while the declared terms path holds nothing. That is
+ * not "this seller advertised no terms"; it is "the manifest says nothing about where a terms URL rides on the
+ * carrier that answered". Returning `undefined` there would assert the seller's silence — and
+ * `parseProposalFromChallenge`, reading the same bytes in the same package, would contradict it.
+ *
+ * The gap is owed back to the manifest: a per-alias terms-URL declaration is the fix and it is a protocol-repo
+ * change. Until it lands this type REPORTS the gap, because a reader that cannot tell two facts apart must say
+ * which one it cannot tell.
+ */
+export type AdvertisedTermsUrl = 
+/** Read from the field the manifest declares. */
+{
+    readonly kind: "read";
+    readonly url: string;
+}
+/** The manifest declares no terms-URL field at all: the protocol has no room for one. */
+ | {
+    readonly kind: "no-field-declared";
+}
+/** The manifest declares one, its declaration reaches the answering carrier, and the document leaves it empty. */
+ | {
+    readonly kind: "declared-field-empty";
+    readonly field: string;
+}
+/**
+ * The manifest's terms-URL path lies INSIDE the canonical carrier's own object, and the reference answered
+ * from a declared alias instead — so the declaration never reached the carrier this document used. Whether
+ * the document advertises a terms URL is UNKNOWN to this reader, not answered.
+ */
+ | {
+    readonly kind: "undeclared-at-answering-carrier";
+    readonly field: string;
+    readonly answeredAt: string;
+};
+/** What a protocol document advertises about the terms governing it. */
+export type AdvertisedTerms = {
+    /** The protocol whose manifest the carriers were read through. */
+    readonly protocol: ProtocolId;
+    /** The advertised ATR hash, reconciled across every integrity-bearing carrier the manifest declares. */
+    readonly advertisedAtrHash: `0x${string}`;
+    /** What the document says about where its terms live — read, absent, or not answerable from here. */
+    readonly legalContextUrl: AdvertisedTermsUrl;
+};
+/**
+ * Read what ANY supported protocol document advertises: its ATR hash, and its terms URL where the protocol
+ * has room for one.
+ *
+ * UNIVERSAL BY CONSTRUCTION. The carriers are not listed here — they are read out of the protocol's own
+ * `PlacementManifest` through `@integraledger/lcp-placements`, so a protocol this function supports is precisely
+ * one the build can also place a reference INTO, and adding a protocol product-side is nothing at all. There
+ * is no second place protocols are listed and no path by which a reader and a writer can drift.
+ *
+ * THE PROTOCOL IS AN ARGUMENT, NOT A DETECTION. Detection is the only part of this seam that can be wrong, so
+ * a caller that knows its protocol — which is the ordinary case, since a buyer agent knows which counterparty
+ * it dialled — never pays for it. {@link detectProtocol} is available for the caller that genuinely does not.
+ *
+ * FAIL-FAST, four ways, all loud:
+ *
+ *  - a protocol with no registered placement (`mcp` is the only one, and LCP v1.38 §C.9 makes that terminal:
+ *    it describes an LCP-aware MCP *server*, which has no document field for a reference to ride in);
+ *  - a document advertising nothing at any declared carrier;
+ *  - DISAGREEMENT between two declared carriers. This is the generalization of the x402 two-carrier rule to
+ *    every protocol in the set, and it is deliberately stricter than the placement adapter's own `extract`,
+ *    which answers with the canonical field and says nothing (`readDeclaredPaths` returns the first hit, not
+ *    the set). A placement is structural and does not adjudicate a host's document; a BUYER must, because two
+ *    different values on one document would let a seller advertise different terms to different readers of it
+ *    and then disown whichever one it lost by. Preference is not an answer here — refusal is;
+ *  - a reference that is not a `sha256` carrier. `carrierTypes` permits `url` on several manifests and that is
+ *    correct for a placement, but the gate compares the advertised value against a RECOMPUTED record hash, and
+ *    nothing but a hash can be compared to a hash.
+ *
+ * `deployment` is required only for a protocol whose placement is namespaced — Mastercard VI, whose constraint
+ * type is minted under the deployment's own reverse-domain namespace and has no default. Omitting it there
+ * throws from the registry rather than answering about some invented namespace.
+ */
+export declare function readAdvertisedTerms(protocol: ProtocolId, wire: unknown, deployment?: PlacementDeployment): AdvertisedTerms;
+/** A parser from one protocol's wire document to the one `GateProposal` every parser produces. */
+export type ProposalParser = (wire: unknown, ctx: ProposalContext) => GateProposal;
+/**
+ * Every protocol this build can turn into a complete `GateProposal`, keyed by `ProtocolId`.
+ *
+ * SMALLER THAN THE PLACEMENT REGISTRY, and the difference is a fact about the protocols rather than a gap in
+ * this package. A `GateProposal` carries an OFFER — an amount and a unit — and an offer is protocol-native
+ * economics that no `PlacementManifest` declares and LCP does not standardize: x402 quotes it in
+ * `accepts[].amount` with a `network:asset` unit, ACP in the row of `totals` typed `total` with an ISO 4217
+ * currency, and the remaining seven each differently again. Inventing an offer-locator axis product-side would
+ * put protocol knowledge in a second place and put it there UNGATED, which is the one thing the placement seam
+ * was built to stop. {@link readAdvertisedTerms} is universal because the reference is; this is not, because
+ * the offer is not.
+ *
+ * ONE PROTOCOL COULD NOT BE DISPATCHED HERE EVEN IF ITS OFFER WERE READABLE. `ap2`'s discriminant is a strict
+ * subset of `a2a`'s, so an AP2 envelope always matches two rows and {@link parseProposalUniversal} refuses it
+ * as ambiguous before any lookup in this map. An `ap2` entry added here would be unreachable through the
+ * universal door; the parser a future unit writes must be exported and called by name.
+ *
+ * `Object.freeze` for the same reason `PLACEMENTS` is frozen: a published package is consumed as JavaScript,
+ * where the type alone does not stop a consumer swapping the parser that decides what a buyer is agreeing to.
+ */
+export declare const PROPOSAL_PARSERS: Readonly<Partial<Record<ProtocolId, ProposalParser>>>;
+/** Every protocol this build can parse a complete proposal from, in registration order. */
+export declare function parseableProtocols(): readonly ProtocolId[];
+/**
+ * Parse ANY supported wire into the one `GateProposal` every parser produces.
+ *
+ * The universal entry point: a buyer no longer has to know which protocol it is on to gate a
+ * transaction. Every named parser stays exported — a caller that DOES know its protocol should keep calling
+ * the specific one, because a known protocol needs no detection and detection is the only part that can be
+ * wrong.
+ *
+ * Fail-fast on four conditions, all loud: an unidentifiable wire, an AMBIGUOUS wire matching more than one
+ * protocol's discriminant, a protocol whose offer this build cannot read, and any refusal from the protocol
+ * parser it routes to. There is no "try them all and take the first that works" path — that is a fallback
+ * chain, and it would let a malformed document of one protocol be silently reinterpreted as a valid document
+ * of another.
+ *
+ * The named parsers are DELEGATED to rather than reimplemented over the placement manifests, and one of them
+ * proves why that is not merely convenient: x402's wire carries `legalContextUrl` in BOTH `accepts[].extra`
+ * and `extensions.legalContext.info` — LCP v1.38 §C.4's own illustration uses the first — while
+ * `PlacementManifest.termsUrlField` is singular and declares only the second. Routing x402 through the
+ * manifest would drop the terms URL from a spec-legal challenge. The reference reconcile generalizes; the
+ * terms-URL locator does not yet, so this entry point delegates and {@link readAdvertisedTerms} REPORTS the
+ * shortfall as `undeclared-at-answering-carrier` rather than answering an absence it cannot vouch for.
+ */
+export declare function parseProposalUniversal(wire: unknown, ctx: ProposalContext): GateProposal;
+//# sourceMappingURL=proposal-universal.d.ts.map

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

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