@openmobilehub/attestomcp-gate 0.1.0

package/dist/ceremony/dc-payment/verify.js

@@ -0,0 +1,208 @@
+// AP2-shaped DC payment mandate + four deterministic gates. TWO verify paths feed
+// ONE set of gates:
+//   • the instant-demo path (buildDcMandate + runDcGates) — disclosed instrument
+//     claims passed in directly; the amount-bound transaction_data is re-derived +
+//     re-checked, so a tampered amount is refused. The tested default (CT6–CT8).
+//   • the REAL OpenID4VP path (verifyDcPresentation, below) — the wallet's
+//     JWE-encrypted response is decrypted (jose ECDH-ES compactDecrypt), the ISO
+//     18013-5 mdoc DeviceResponse is parsed, and the wallet's device-SIGNED
+//     transaction_data_hash (from deviceSigned) is extracted and re-checked against
+//     SHA-256 of the transaction_data we sent — proving the wallet authorized THIS
+//     amount/payee, not merely that a token decrypted.
+//
+// TRUST_LEVEL stays "presence-only-demo" (Principle VII / FR-011): the wire crypto
+// — JWE decryption, the ISO-mdoc CBOR parse, the transaction_data hash binding — is
+// REAL; what is NOT yet verified is the issuer/device COSE SIGNATURE against a real
+// trust anchor (main self-signs its mdoc certs). Faithfully ported from the demo's
+// payment-gate/dc-payment/{mandate,verify}.ts. No gate trusts a `verified` flag —
+// AMOUNT BINDING (Security invariants 2/3) is always re-derived from the
+// catalog-priced lines.
+import { randomUUID } from "node:crypto";
+import * as jose from "jose";
+import { buildBindingFields, DEFAULT_LOYALTY_DISCOUNT_PCT } from "../mandate.js";
+import { buildTransactionData, decodeTransactionData, encodeTransactionData, hashTransactionData } from "./txData.js";
+import { openReaderContext } from "../mdoc/readerContext.js";
+import { decodeVpToken, extractTransactionDataHash, inspectAuthBlocks } from "../mdoc/mdoc.js";
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+function claimText(v) {
+    if (v == null)
+        return null;
+    if (typeof v === "object" && "value" in v)
+        return String(v.value);
+    return String(v);
+}
+const DEFAULT_ISSUER = "did:web:attestomcp.local";
+/**
+ * Build the presence-only DC payment mandate. The transaction_data is derived from
+ * the (catalog-re-priced) order + this RP's origin, so its amount/payee are the
+ * server's truth; `presentedAmount` is what the caller asserts authorizing (Gate 1
+ * re-checks it equals the re-derived payable — a tampered value is refused).
+ */
+export function buildDcMandate(args) {
+    const { order, origin, claims } = args;
+    const now = new Date();
+    const expires = new Date(now.getTime() + 5 * 60_000);
+    const txDataB64 = encodeTransactionData(buildTransactionData(order, origin));
+    const instrument = {
+        issuer: claimText(claims["issuer_name"]),
+        instrumentId: claimText(claims["payment_instrument_id"]),
+        maskedAccount: claimText(claims["masked_account_reference"]),
+        holder: claimText(claims["holder_name"]),
+        expiry: claimText(claims["expiry_date"]),
+    };
+    return {
+        type: "ap2.PaymentMandate",
+        version: "0.1-dc-demo",
+        id: "mandate_pm_" + randomUUID(),
+        issuedAt: now.toISOString(),
+        expiresAt: expires.toISOString(),
+        issuer: args.issuer ?? DEFAULT_ISSUER,
+        subject: { credentialId: instrument.instrumentId },
+        cart: order,
+        payment: { instrument, amount: args.presentedAmount ?? order.total, currency: order.currency },
+        userAuthorization: {
+            type: "openid4vp-dc-api",
+            transactionData: txDataB64,
+            transactionDataHash: hashTransactionData(txDataB64),
+            presented: true,
+        },
+        trust_level: "presence-only-demo",
+    };
+}
+export function runDcGates(mandate, origin, opts = {}) {
+    const pct = opts.loyaltyDiscountPct ?? DEFAULT_LOYALTY_DISCOUNT_PCT;
+    const ua = mandate.userAuthorization;
+    const cart = mandate.cart;
+    const results = [];
+    // Gate 1 — amount binding. Re-sum the (undiscounted) cart lines, re-derive the
+    // payable, and re-check it against (a) the transaction_data we'd send, (b) the
+    // presented payment.amount. A loyalty discount, if present, must be either zero
+    // or EXACTLY the configured percentage of the line sum (this lets a legitimately
+    // discounted order pass and rejects an arbitrary discount). The stored amount is
+    // NOT trusted; everything is re-derived here.
+    const lineSum = round2(cart.lines.reduce((sum, l) => sum + l.lineTotal, 0));
+    const discount = cart.discount ?? 0;
+    const discountOk = discount === 0 || discount === round2(lineSum * (pct / 100));
+    const payable = round2(lineSum - discount);
+    const recomputed = hashTransactionData(ua.transactionData);
+    const hashOk = ua.transactionDataHash === recomputed;
+    const txd = decodeTransactionData(ua.transactionData);
+    const amountOk = discountOk && payable === cart.total && payable === mandate.payment.amount && Number(txd.payload.amount) === payable;
+    const currencyOk = txd.payload.currency === cart.currency;
+    // Payee must be THIS RP — re-derived from the request origin, not the token. An
+    // attacker re-pointing the request to their own origin fails here (invariant 6).
+    const expectedPayee = buildBindingFields(cart, origin).payee.id;
+    const payeeOk = !!txd.payload.payee?.id && txd.payload.payee.id === expectedPayee;
+    results.push({
+        gate: "Amount binding",
+        pass: hashOk && amountOk && currencyOk && payeeOk,
+        detail: `hash ${hashOk ? "✓" : "✗"} · amount ${amountOk ? "✓" : "✗"} (${txd.payload.amount}/${mandate.payment.amount} vs ${payable}) · currency ${currencyOk ? "✓" : "✗"} · payee ${payeeOk ? "✓" : "✗"} (${txd.payload.payee?.id} vs ${expectedPayee})`,
+    });
+    // Gate 2 — authorization present. On the REAL path, the wallet's mdoc carries
+    // structural issuerAuth + deviceAuth blocks (inspected from the parsed
+    // DeviceResponse); on the instant-demo path a disclosed instrument id stands in
+    // for them. Either way this is presence-only — the COSE signatures themselves are
+    // NOT verified against a trust anchor (acknowledged future work).
+    const instrumentId = mandate.payment.instrument.instrumentId;
+    const auth = ua.authBlocks;
+    const authPass = auth ? auth.hasIssuerAuth && auth.hasDeviceAuth : !!instrumentId;
+    results.push({
+        gate: "Authorization present",
+        pass: authPass,
+        detail: auth
+            ? `issuerAuth ${auth.hasIssuerAuth ? "✓" : "✗"} · deviceAuth ${auth.hasDeviceAuth ? "✓" : "✗"} (presence-only — COSE signatures not verified)`
+            : `instrument=${instrumentId ?? "∅"} (presence-only — device/issuer signatures not verified)`,
+    });
+    // Gate 3 — credential not expired (disclosed expiry_date in the future).
+    const expStr = mandate.payment.instrument.expiry;
+    const notExpired = !!expStr && new Date(expStr).getTime() > Date.now();
+    results.push({ gate: "Credential not expired", pass: notExpired, detail: `expiry_date=${expStr}` });
+    // Gate 4 — subject binding: mandate.subject re-checked against the disclosed
+    // instrument id.
+    const subjectOk = !!instrumentId && mandate.subject.credentialId === instrumentId;
+    results.push({ gate: "Subject binding", pass: subjectOk, detail: `subject=${mandate.subject.credentialId} · instrument=${instrumentId}` });
+    return results;
+}
+// ── REAL OpenID4VP path ───────────────────────────────────────────────────────
+// Disclosed mdoc claim values can be {_tag, value} (e.g. tag-1004 dates) or raw.
+function disclosedClaims(vpStr) {
+    const disclosed = decodeVpToken({ dpc: vpStr });
+    return Object.fromEntries((disclosed[0]?.claims ?? []).map((c) => [c.label.split(" / ").pop(), c.value]));
+}
+/**
+ * Build the DC mandate from a REAL wallet DeviceResponse. Unlike the instant-demo
+ * builder, `transactionDataHash` is the value EXTRACTED from the wallet's
+ * device-signed mdoc (deviceSigned/transaction_data_hash) — Gate 1 then re-checks it
+ * equals SHA-256 of the transaction_data WE sealed (transactionDataB64). The vpToken
+ * + parsed issuerAuth/deviceAuth presence drive Gate 2. The instrument fields come
+ * from the issuer-signed namespaces of the SAME DeviceResponse.
+ */
+export function buildDcMandateFromPresentation(args) {
+    const { order, vpStr, transactionDataB64 } = args;
+    const now = new Date();
+    const expires = new Date(now.getTime() + 5 * 60_000);
+    const claims = disclosedClaims(vpStr);
+    const instrument = {
+        issuer: claimText(claims["issuer_name"]),
+        instrumentId: claimText(claims["payment_instrument_id"]),
+        maskedAccount: claimText(claims["masked_account_reference"]),
+        holder: claimText(claims["holder_name"]),
+        expiry: claimText(claims["expiry_date"]),
+    };
+    const blocks = inspectAuthBlocks(vpStr);
+    return {
+        type: "ap2.PaymentMandate",
+        version: "0.1-dc-demo",
+        id: "mandate_pm_" + randomUUID(),
+        issuedAt: now.toISOString(),
+        expiresAt: expires.toISOString(),
+        issuer: args.issuer ?? DEFAULT_ISSUER,
+        subject: { credentialId: instrument.instrumentId },
+        cart: order,
+        payment: { instrument, amount: order.total, currency: order.currency },
+        userAuthorization: {
+            type: "openid4vp-dc-api",
+            transactionData: transactionDataB64,
+            // The wallet's signed hash — re-checked in Gate 1 against our recomputed hash.
+            transactionDataHash: extractTransactionDataHash(vpStr),
+            presented: true,
+            vpToken: vpStr,
+            authBlocks: { hasIssuerAuth: blocks.hasIssuerAuth, hasDeviceAuth: blocks.hasDeviceAuth },
+        },
+        trust_level: "presence-only-demo",
+    };
+}
+/**
+ * Verify the wallet's REAL OpenID4VP presentation: open the sealed reader context,
+ * JWE-decrypt the response (jose ECDH-ES compactDecrypt), pull the mdoc vp_token,
+ * build the amount-bound mandate from the device-signed DeviceResponse, and run the
+ * four gates. Faithfully ported from the demo's payment-gate/dc-payment/verify.ts.
+ * The crypto (decryption + the transaction_data hash binding) is REAL; the issuer
+ * trust anchor is not (trust_level presence-only-demo).
+ */
+export async function verifyDcPresentation(args) {
+    const { order, origin, result, readerContextToken, secret } = args;
+    const ctx = await openReaderContext(readerContextToken, secret);
+    let data = result?.data;
+    if (typeof data === "string") {
+        try {
+            data = JSON.parse(data);
+        }
+        catch { /* leave as string */ }
+    }
+    const jwe = data?.response;
+    if (!jwe)
+        throw new Error("no .response (JWE) in result.data");
+    const encPrivKey = await jose.importJWK(ctx.ecdhPrivateJwk, "ECDH-ES");
+    const { plaintext } = await jose.compactDecrypt(jwe, encPrivKey);
+    const openid4vpResponse = JSON.parse(new TextDecoder().decode(plaintext));
+    const vpToken = openid4vpResponse.vp_token; // { dpc: [ "<DeviceResponse b64url>" ] }
+    const vpStr = Array.isArray(vpToken?.dpc) ? vpToken.dpc[0] : vpToken?.dpc;
+    if (!vpStr)
+        throw new Error("no vp_token.dpc in decrypted response");
+    const mandate = buildDcMandateFromPresentation({ order, vpStr, transactionDataB64: ctx.transactionDataB64 });
+    const gates = runDcGates(mandate, origin);
+    return { mandate, gates };
+}

package/dist/ceremony/mandate.d.ts

@@ -0,0 +1,71 @@
+import type { CeremonyOrder } from "./types.js";
+import type { Origin } from "./origin.js";
+export declare const DEFAULT_LOYALTY_DISCOUNT_PCT = 10;
+export interface BindingFields {
+    amount: number;
+    currency: string;
+    payee: {
+        id: string;
+        name: string;
+    };
+    orderId: string;
+}
+export declare function buildBindingFields(order: CeremonyOrder, origin: Origin, payeeName?: string): BindingFields;
+export interface VerifiedAuthenticator {
+    credentialID: string;
+    userVerified: boolean;
+    credentialDeviceType: "singleDevice" | "multiDevice";
+    credentialBackedUp: boolean;
+}
+export interface PasskeyMandate {
+    type: "ap2.PaymentMandate";
+    version: "0.1-mock";
+    id: string;
+    issuedAt: string;
+    expiresAt: string;
+    issuer: string;
+    subject: {
+        credentialID: string;
+    };
+    cart: CeremonyOrder;
+    payment: {
+        instrument: string;
+        instrumentReference: string;
+        network: string;
+        amount: number;
+        currency: string;
+    };
+    userAuthorization: {
+        type: "webauthn.assertion";
+        credentialID: string;
+        userVerified: boolean;
+        hardwareBacked: boolean;
+        deviceType: string;
+        backedUp: boolean;
+        rpID: string;
+        origin: string;
+        ceremonyTimestamp: string;
+    };
+    payeeId: string;
+    trust_level: "presence-only-demo";
+    signature: {
+        alg: "MOCK-DEV-SIGNER";
+        value: string;
+        note: string;
+    };
+}
+export declare function buildPasskeyMandate(args: {
+    order: CeremonyOrder;
+    authenticator: VerifiedAuthenticator;
+    origin: Origin;
+    issuer?: string;
+    payeeName?: string;
+}): PasskeyMandate;
+export interface GateResult {
+    gate: string;
+    pass: boolean;
+    detail: string;
+}
+export declare function runGates(mandate: PasskeyMandate, opts?: {
+    loyaltyDiscountPct?: number;
+}): GateResult[];

package/dist/ceremony/mandate.js

@@ -0,0 +1,116 @@
+// Binding fields + the AP2-shaped passkey mandate + the four deterministic gates.
+// Extracted from the demo's payment-gate/mandate.ts; the demo's `Order` and the
+// hardcoded `LOYALTY_DISCOUNT_PCT` become an injected `CeremonyOrder` + an opt so
+// the package stays dependency-free. No gate trusts a `verified` boolean — each is
+// re-derived from the mandate's own fields.
+//
+// Trust is PRESENCE-ONLY (Principle VII): the signature is a dev-mock SHA-256
+// digest and the mandate carries `trust_level: "presence-only-demo"`. Real
+// KB-JWT / key-bound signing is deferred (v0.2); this is a flow demo, not a real
+// safety control.
+import { createHash, randomUUID } from "node:crypto";
+function round2(n) {
+    return Math.round(n * 100) / 100;
+}
+// The demo's whole-cart loyalty discount; the host can override via runGates opts.
+export const DEFAULT_LOYALTY_DISCOUNT_PCT = 10;
+const DEFAULT_ISSUER = "did:web:attestomcp.local";
+const DEFAULT_PAYEE_NAME = "AttestoMcp Gate Demo";
+export function buildBindingFields(order, origin, payeeName = DEFAULT_PAYEE_NAME) {
+    return {
+        amount: order.total,
+        currency: order.currency,
+        payee: { id: origin.rpID, name: payeeName },
+        orderId: order.id,
+    };
+}
+export function buildPasskeyMandate(args) {
+    const { order, authenticator, origin } = args;
+    const now = new Date();
+    const expires = new Date(now.getTime() + 5 * 60_000);
+    const binding = buildBindingFields(order, origin, args.payeeName);
+    const body = {
+        type: "ap2.PaymentMandate",
+        version: "0.1-mock",
+        id: "mandate_pm_" + randomUUID(),
+        issuedAt: now.toISOString(),
+        expiresAt: expires.toISOString(),
+        issuer: args.issuer ?? DEFAULT_ISSUER,
+        subject: { credentialID: authenticator.credentialID },
+        cart: order,
+        payment: {
+            instrument: "stripe_test",
+            instrumentReference: "pi_3Mock" + Math.random().toString(36).slice(2, 10).toUpperCase(),
+            network: "card",
+            amount: binding.amount,
+            currency: binding.currency,
+        },
+        userAuthorization: {
+            type: "webauthn.assertion",
+            credentialID: authenticator.credentialID,
+            userVerified: authenticator.userVerified,
+            // A single-device credential is bound to this authenticator's hardware; a
+            // multi-device (syncable) passkey is not strictly hardware-bound.
+            hardwareBacked: authenticator.credentialDeviceType === "singleDevice",
+            deviceType: authenticator.credentialDeviceType,
+            backedUp: authenticator.credentialBackedUp,
+            rpID: origin.rpID,
+            origin: origin.origin,
+            ceremonyTimestamp: now.toISOString(),
+        },
+        payeeId: binding.payee.id,
+        trust_level: "presence-only-demo",
+    };
+    const digest = createHash("sha256").update(JSON.stringify(body)).digest("base64");
+    return {
+        ...body,
+        signature: {
+            alg: "MOCK-DEV-SIGNER",
+            value: "mock-sig:" + digest,
+            note: "Mock dev signer (presence-only-demo). Production replaces with AP2-conformant key-bound signing.",
+        },
+    };
+}
+export function runGates(mandate, opts = {}) {
+    const pct = opts.loyaltyDiscountPct ?? DEFAULT_LOYALTY_DISCOUNT_PCT;
+    const ua = mandate.userAuthorization;
+    const cart = mandate.cart;
+    const lineSum = round2(cart.lines.reduce((sum, l) => sum + l.lineTotal, 0));
+    const results = [];
+    // Gate 1 — amount integrity. Re-sum the (undiscounted) cart lines and re-derive
+    // the payable total; payment.amount is NOT trusted. A loyalty discount, if
+    // present, must be either zero or EXACTLY the configured percentage of the line
+    // sum — this lets a legitimately discounted order pass and rejects a token
+    // tampered with an arbitrary discount. Payable must equal cart.total AND the
+    // authorized payment.amount.
+    const discount = cart.discount ?? 0;
+    const discountOk = discount === 0 || discount === round2(lineSum * (pct / 100));
+    const payable = round2(lineSum - discount);
+    const amountOk = discountOk && payable === cart.total && payable === mandate.payment.amount;
+    results.push({
+        gate: "Amount integrity",
+        pass: amountOk,
+        detail: `lines=${lineSum} · discount=${discount} · payable=${payable} · payment=${mandate.payment.amount} · cart.total=${cart.total}`,
+    });
+    // Gate 2 — authorization present & structurally a webauthn assertion.
+    const authPresent = ua.type === "webauthn.assertion" && !!ua.credentialID;
+    results.push({
+        gate: "Authorization present",
+        pass: authPresent,
+        detail: `type=${ua.type} · credentialID=${ua.credentialID || "∅"}`,
+    });
+    // Gate 3 — user verification asserted by the authenticator.
+    results.push({
+        gate: "User verification",
+        pass: ua.userVerified === true,
+        detail: `userVerified=${ua.userVerified} · hardwareBacked=${ua.hardwareBacked}`,
+    });
+    // Gate 4 — subject binding: re-check subject == authorization credentialID.
+    const subjectOk = !!mandate.subject.credentialID && mandate.subject.credentialID === ua.credentialID;
+    results.push({
+        gate: "Subject binding",
+        pass: subjectOk,
+        detail: `subject=${mandate.subject.credentialID} · auth=${ua.credentialID}`,
+    });
+    return results;
+}

package/dist/ceremony/mdoc/mdoc-iso.d.ts

@@ -0,0 +1,44 @@
+import * as jose from "jose";
+import { type DisclosedEntry } from "./mdoc.js";
+export interface MdocDocSpec {
+    docType: string;
+    namespace: string;
+    elements: string[];
+}
+export declare function coseKeyFromJwk(jwk: {
+    x: string;
+    y: string;
+}): Map<number, unknown>;
+export interface ReaderKey {
+    coseKey: Map<number, unknown>;
+    privateJwk: jose.JWK;
+}
+export declare function generateReaderKey(): Promise<ReaderKey>;
+export declare function buildEncryptionInfo(coseKey: Map<number, unknown>, nonce: Uint8Array): {
+    bytes: Uint8Array;
+    base64: string;
+};
+export declare function buildItemsRequest(spec: MdocDocSpec): Uint8Array;
+export declare function buildDeviceRequest(spec: MdocDocSpec): Uint8Array;
+export declare function buildSessionTranscript(base64EncryptionInfo: string, origin: string): Uint8Array;
+export interface MdocRequestParts {
+    data: {
+        deviceRequest: string;
+        encryptionInfo: string;
+    };
+    readerPrivateJwk: jose.JWK;
+    base64EncryptionInfo: string;
+}
+export declare function buildMdocRequestParts(spec: MdocDocSpec, origin: string, signed?: boolean): Promise<MdocRequestParts>;
+export declare function decryptDeviceResponse(args: {
+    responseB64Url: string;
+    readerPrivateJwk: jose.JWK;
+    sessionTranscript: Uint8Array;
+}): Promise<Uint8Array>;
+export declare function disclosedFromDeviceResponse(deviceResponse: Uint8Array): DisclosedEntry[];
+export interface MdocReaderContext {
+    readerPrivateJwk: jose.JWK;
+    base64EncryptionInfo: string;
+}
+export declare function sealMdocContext(ctx: MdocReaderContext, secret: string, ttlMs?: number): Promise<string>;
+export declare function openMdocContext(token: string, secret: string): Promise<MdocReaderContext>;