@openmobilehub/attestomcp-gate 0.1.0

package/dist/ceremony/mdoc/mdoc-iso.js

@@ -0,0 +1,260 @@
+// ISO 18013-7 Annex C "org-iso-mdoc" over the W3C Digital Credentials API — the
+// protocol iOS Safari/WebKit supports (Android Chrome uses OpenID4VP instead).
+// Extracted FAITHFULLY from the demo's payment-gate/credential-gate/mdoc-iso.ts
+// (which reverse-engineered the wire format from verifier.multipaz.org). The only
+// adaptation: the doctype/namespace/elements arrive as a `MdocDocSpec` argument
+// (rail-agnostic) instead of a hardcoded credential-kind table, so both rails reuse
+// this one module.
+//
+// What is REAL here: the full ISO/IEC 18013-5 wire format — deterministic
+// (canonical) CBOR, COSE_Sign1 ReaderAuthAll (ES256 over the SessionTranscript),
+// the @peculiar/x509 reader-cert chain (CA + leaf with mDL reader-auth EKUs),
+// EncryptionInfo / DeviceRequest / SessionTranscript, and HPKE (P-256 / HKDF-SHA256
+// / AES-128-GCM) decryption of the wallet's DeviceResponse bound to the web origin.
+// What is NOT yet real: the issuer TRUST ANCHOR — the reader cert is self-signed
+// (no real CA), so origin/reader binding is enforced but cross-issuer trust is not.
+import { Encoder, decode as cborDecode, Tag } from "cbor-x";
+// ISO/IEC 18013-5 §9.1.1 mandates *deterministic* (canonical) CBOR. cbor-x's
+// default `encode` writes maps with a fixed 2-byte length header (0xb9 …) for
+// speed, which is non-minimal — Apple re-encodes deviceRequestInfo canonically
+// when it reconstructs ReaderAuthenticationAll, so a non-minimal header makes the
+// reader-auth signature fail to validate (idcsInvalidReaderAuthSignature).
+// `useRecords:false` + `variableMapSize:true` emits minimal map headers (0xa2 …)
+// matching verifier.multipaz.org's output exactly. `useTag259ForMaps:false` is
+// CRITICAL: by default cbor-x wraps every JS Map in its non-standard tag 259
+// (0xd90103), so the COSE protected header `{1:-7}` becomes `d90103 a10126`
+// instead of `a10126`. The protected header is part of the signed Sig_structure,
+// so the tag makes Apple's COSE parser reject the reader-auth signature
+// (idcsInvalidReaderAuthSignature). It also corrupts the x5chain (unprotected
+// header) and the recipientPublicKey COSE_Key.
+const canonicalEncoder = new Encoder({
+    useRecords: false,
+    variableMapSize: true,
+    useTag259ForMaps: false,
+});
+function cborEncode(value) {
+    return canonicalEncoder.encode(value);
+}
+import { createHash, webcrypto, randomBytes } from "node:crypto";
+import { CipherSuite, DhkemP256HkdfSha256, HkdfSha256, Aes128Gcm } from "@hpke/core";
+import * as jose from "jose";
+import * as x509 from "@peculiar/x509";
+import { decodeVpToken } from "./mdoc.js";
+x509.cryptoProvider.set(globalThis.crypto);
+const READER_SIGN_ALG = { name: "ECDSA", namedCurve: "P-256", hash: "SHA-256" };
+// Reader-authentication certificate chain following the ISO/IEC 18013-5 reader
+// profile. Apple validates the *whole chain* on a signed request, so a single
+// self-signed cert is rejected (idcsInvalidReaderAuthSignature). We mint the
+// exact structure verifier.multipaz.org uses: a self-signed Reader CA root
+// (basicConstraints CA:true) and a leaf signed by it carrying the reader-auth
+// EKUs and a DNS SAN matching the request origin. The reader auth is signed with
+// the leaf key; x5chain = [leaf, ca].
+async function makeMdocReaderCert(origin, host) {
+    const now = Date.now();
+    // ── Reader CA (self-signed root) ──
+    const caKeys = await webcrypto.subtle.generateKey(READER_SIGN_ALG, true, ["sign", "verify"]);
+    const ca = await x509.X509CertificateGenerator.createSelfSigned({
+        serialNumber: "01",
+        name: `CN=${host} Reader CA`,
+        notBefore: new Date(now - 60_000),
+        notAfter: new Date(now + 5 * 365 * 86_400_000),
+        signingAlgorithm: READER_SIGN_ALG,
+        keys: caKeys,
+        extensions: [
+            new x509.BasicConstraintsExtension(true, undefined, true), // CA:true, critical
+            new x509.KeyUsagesExtension(x509.KeyUsageFlags.keyCertSign | x509.KeyUsageFlags.cRLSign, true),
+            await x509.SubjectKeyIdentifierExtension.create(caKeys.publicKey),
+        ],
+    });
+    // ── Leaf (signed by the Reader CA) ──
+    const leafKeys = await webcrypto.subtle.generateKey(READER_SIGN_ALG, true, ["sign", "verify"]);
+    const leaf = await x509.X509CertificateGenerator.create({
+        serialNumber: "02",
+        subject: `CN=Verifier at ${origin}`,
+        issuer: ca.subject,
+        notBefore: new Date(now - 60_000),
+        notAfter: new Date(now + 365 * 86_400_000),
+        signingAlgorithm: READER_SIGN_ALG,
+        publicKey: leafKeys.publicKey,
+        signingKey: caKeys.privateKey,
+        extensions: [
+            new x509.KeyUsagesExtension(x509.KeyUsageFlags.digitalSignature, true),
+            // id-mdlReaderAuth + ISO 23220-4 reader-auth — both, as multipaz does.
+            new x509.ExtendedKeyUsageExtension(["1.0.18013.5.1.6", "1.0.23220.4.1.6"], true),
+            new x509.SubjectAlternativeNameExtension([{ type: "dns", value: host }]),
+            await x509.AuthorityKeyIdentifierExtension.create(ca),
+            await x509.SubjectKeyIdentifierExtension.create(leafKeys.publicKey),
+        ],
+    });
+    return {
+        chainDer: [new Uint8Array(leaf.rawData), new Uint8Array(ca.rawData)],
+        leafKey: leafKeys.privateKey,
+    };
+}
+function suite() {
+    return new CipherSuite({ kem: new DhkemP256HkdfSha256(), kdf: new HkdfSha256(), aead: new Aes128Gcm() });
+}
+function b64urlToBytes(s) {
+    return Buffer.from(s, "base64url");
+}
+function bytesToB64url(b) {
+    return Buffer.from(b).toString("base64url");
+}
+// @hpke/core wants ArrayBuffer for enc/info/ciphertext.
+function toAB(b) {
+    return b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+}
+// ── COSE_Key (EC2 / P-256), CBOR map with integer keys ────────────────────────
+export function coseKeyFromJwk(jwk) {
+    return new Map([
+        [1, 2], // kty: EC2
+        [-1, 1], // crv: P-256
+        [-2, b64urlToBytes(jwk.x)], // x
+        [-3, b64urlToBytes(jwk.y)], // y
+    ]);
+}
+export async function generateReaderKey() {
+    const kp = await webcrypto.subtle.generateKey({ name: "ECDH", namedCurve: "P-256" }, true, ["deriveBits"]);
+    const pubJwk = (await webcrypto.subtle.exportKey("jwk", kp.publicKey));
+    const privateJwk = (await webcrypto.subtle.exportKey("jwk", kp.privateKey));
+    return { coseKey: coseKeyFromJwk(pubJwk), privateJwk };
+}
+// ── EncryptionInfo = ["dcapi", { nonce, recipientPublicKey: COSE_Key }] ────────
+export function buildEncryptionInfo(coseKey, nonce) {
+    const info = ["dcapi", { nonce: Buffer.from(nonce), recipientPublicKey: coseKey }];
+    const bytes = cborEncode(info);
+    return { bytes, base64: bytesToB64url(bytes) };
+}
+// CBOR canonical map-key order (RFC 8949 §4.2.1 / ISO 18013-5): shorter key
+// first, then bytewise. The reader-auth signature is over the canonically-encoded
+// ItemsRequest, so its element-map keys MUST be in this order or Apple's
+// reconstruction won't match (idcsInvalidReaderAuthSignature).
+function canonicalKeyOrder(a, b) {
+    const ab = Buffer.from(a), bb = Buffer.from(b);
+    return ab.length !== bb.length ? ab.length - bb.length : Buffer.compare(ab, bb);
+}
+export function buildItemsRequest(spec) {
+    const { docType, namespace, elements } = spec;
+    const sorted = [...elements].sort(canonicalKeyOrder);
+    return cborEncode({ docType, nameSpaces: { [namespace]: Object.fromEntries(sorted.map((e) => [e, false])) } });
+}
+// Unsigned DeviceRequest (used by the structure tests). The real request sent to
+// iOS is reader-authenticated — see buildSignedDeviceRequest.
+export function buildDeviceRequest(spec) {
+    return cborEncode({
+        version: "1.0",
+        docRequests: [{ itemsRequest: new Tag(Buffer.from(buildItemsRequest(spec)), 24) }],
+    });
+}
+// ISO 18013-5 (mdoc v1.1) ReaderAuthAll — a single COSE_Sign1 (detached) at the
+// DeviceRequest level covering ALL doc requests, signed over:
+//   #6.24(bstr .cbor ["ReaderAuthenticationAll", SessionTranscript,
+//                      [ #6.24(bstr ItemsRequest), … ], deviceRequestInfo|null])
+// This is exactly what verifier.multipaz.org sends and what Apple's WebKit
+// validator authenticates ("ReaderAuthAll"). The reader cert rides in x5chain
+// (label 33). NOTE: the DeviceRequest version MUST be "1.1" or readerAuthAll is
+// ignored by conformant parsers.
+// DeviceRequestInfo (mdoc v1.1): one mandatory use case covering our single doc
+// request (documentSets indices). Matches what verifier.multipaz.org sends; it is
+// part of the ReaderAuthAll signed payload, so it must be present AND identical.
+function buildDeviceRequestInfo() {
+    return cborEncode({ useCases: [{ mandatory: true, documentSets: [[0]] }] });
+}
+async function buildReaderAuthAll(args) {
+    const transcriptItem = cborDecode(args.sessionTranscript);
+    // [ "ReaderAuthenticationAll", SessionTranscript, [ItemsRequestBytes…], deviceRequestInfoBytes ]
+    const readerAuthenticationAll = ["ReaderAuthenticationAll", transcriptItem, args.itemsRequestTags, args.deviceRequestInfoTag];
+    const raaBytes = cborEncode(new Tag(Buffer.from(cborEncode(readerAuthenticationAll)), 24));
+    const protectedHeader = cborEncode(new Map([[1, -7]])); // {alg: ES256}
+    const sigStructure = cborEncode(["Signature1", Buffer.from(protectedHeader), Buffer.alloc(0), Buffer.from(raaBytes)]);
+    const signature = new Uint8Array(await webcrypto.subtle.sign({ name: "ECDSA", hash: "SHA-256" }, args.signingKey, sigStructure));
+    // x5chain (label 33): array of DER certs, leaf first — [leaf, ca].
+    const unprotected = new Map([[33, args.chainDer.map((d) => Buffer.from(d))]]);
+    // COSE_Sign1 = [protected, unprotected, payload(null = detached), signature]
+    return [Buffer.from(protectedHeader), unprotected, null, Buffer.from(signature)];
+}
+async function buildSignedDeviceRequest(spec, sessionTranscript, signingKey, chainDer) {
+    const itemsRequestTag = new Tag(Buffer.from(buildItemsRequest(spec)), 24);
+    const deviceRequestInfoTag = new Tag(Buffer.from(buildDeviceRequestInfo()), 24);
+    const readerAuthAll = await buildReaderAuthAll({ sessionTranscript, itemsRequestTags: [itemsRequestTag], deviceRequestInfoTag, signingKey, chainDer });
+    // Key order matches verifier.multipaz.org: version, docRequests, deviceRequestInfo, readerAuthAll.
+    // readerAuthAll is an *array* of COSE_Sign1s (one per signing key); we always send exactly one,
+    // so the value is [[protectedHdr, unprotected, null, sig]] — the outer array is not a mistake.
+    return cborEncode({ version: "1.1", docRequests: [{ itemsRequest: itemsRequestTag }], deviceRequestInfo: deviceRequestInfoTag, readerAuthAll: [readerAuthAll] });
+}
+// ── SessionTranscript = [null, null, ["dcapi", SHA256(CBOR([b64EncInfo, origin]))]] ──
+export function buildSessionTranscript(base64EncryptionInfo, origin) {
+    const dcapiInfo = [base64EncryptionInfo, origin];
+    const digest = createHash("sha256").update(cborEncode(dcapiInfo)).digest();
+    const transcript = [null, null, ["dcapi", digest]];
+    return cborEncode(transcript);
+}
+export async function buildMdocRequestParts(spec, origin, signed = true) {
+    const { coseKey, privateJwk } = await generateReaderKey();
+    const nonce = randomBytes(16);
+    const { base64: base64EncryptionInfo } = buildEncryptionInfo(coseKey, nonce);
+    let deviceRequest;
+    if (signed) {
+        // The reader auth signs over the session transcript, which binds the request
+        // to this exact origin — so the device request must be built with it.
+        const sessionTranscript = buildSessionTranscript(base64EncryptionInfo, origin);
+        const host = new URL(origin).host.split(":")[0];
+        const { chainDer, leafKey } = await makeMdocReaderCert(origin, host);
+        deviceRequest = await buildSignedDeviceRequest(spec, sessionTranscript, leafKey, chainDer);
+    }
+    else {
+        deviceRequest = buildDeviceRequest(spec); // unsigned (diagnostic A/B)
+    }
+    return {
+        data: { deviceRequest: bytesToB64url(deviceRequest), encryptionInfo: base64EncryptionInfo },
+        readerPrivateJwk: privateJwk,
+        base64EncryptionInfo,
+    };
+}
+// ── HPKE-decrypt the wallet's response → DeviceResponse CBOR bytes ─────────────
+function field(map, key) {
+    if (map instanceof Map)
+        return map.get(key);
+    if (map && typeof map === "object")
+        return map[key];
+    return undefined;
+}
+export async function decryptDeviceResponse(args) {
+    const { responseB64Url, readerPrivateJwk, sessionTranscript } = args;
+    const decoded = cborDecode(b64urlToBytes(responseB64Url));
+    // Accept either ["dcapi", {enc, cipherText}] or a bare {enc, cipherText} map.
+    const params = Array.isArray(decoded) && decoded[0] === "dcapi" ? decoded[1] : decoded;
+    const enc = field(params, "enc");
+    const cipherText = field(params, "cipherText");
+    if (!enc || !cipherText)
+        throw new Error("missing enc/cipherText in response");
+    const s = suite();
+    const recipientKey = await s.kem.importKey("jwk", readerPrivateJwk, false);
+    const recipient = await s.createRecipientContext({
+        recipientKey,
+        enc: toAB(enc),
+        info: toAB(sessionTranscript),
+    });
+    const pt = await recipient.open(toAB(cipherText));
+    return new Uint8Array(pt);
+}
+// ── Decrypted DeviceResponse → disclosed claims (reuses ./mdoc.ts) ────────────
+export function disclosedFromDeviceResponse(deviceResponse) {
+    return decodeVpToken({ mdoc: bytesToB64url(deviceResponse) });
+}
+function keyFromSecret(secret) {
+    return new Uint8Array(createHash("sha256").update(secret).digest());
+}
+export async function sealMdocContext(ctx, secret, ttlMs = 180_000) {
+    const payload = { ...ctx, exp: Date.now() + ttlMs };
+    return await new jose.CompactEncrypt(new TextEncoder().encode(JSON.stringify(payload)))
+        .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
+        .encrypt(keyFromSecret(secret));
+}
+export async function openMdocContext(token, secret) {
+    const { plaintext } = await jose.compactDecrypt(token, keyFromSecret(secret));
+    const payload = JSON.parse(new TextDecoder().decode(plaintext));
+    if (Date.now() > payload.exp)
+        throw new Error("mdoc reader context expired");
+    return { readerPrivateJwk: payload.readerPrivateJwk, base64EncryptionInfo: payload.base64EncryptionInfo };
+}

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

@@ -0,0 +1,17 @@
+export interface DisclosedEntry {
+    id: string;
+    format: string;
+    type?: string;
+    claims: {
+        label: string;
+        value: any;
+    }[];
+}
+export declare function decodeVpToken(vpToken: unknown): DisclosedEntry[];
+export declare function extractTransactionDataHash(vpStr: string | string[], namespace?: string, element?: string): string | null;
+export interface AuthBlocks {
+    hasIssuerAuth: boolean;
+    hasDeviceAuth: boolean;
+    docType: string | null;
+}
+export declare function inspectAuthBlocks(vpStr: string | string[]): AuthBlocks;

package/dist/ceremony/mdoc/mdoc.js

@@ -0,0 +1,94 @@
+// Structural-only decode of a presented mdoc DeviceResponse (ISO 18013-5 CBOR).
+// Extracted FAITHFULLY from the demo's payment-gate/dc-payment/mdoc.ts — the
+// SAME real wire parser both rails (credential-gate + dc-payment) feed their
+// decrypted DeviceResponse into.
+//
+// What is REAL here: the ISO 18013-5 CBOR wire format is fully parsed — the
+// DeviceResponse → documents → issuerSigned.nameSpaces → IssuerSignedItemBytes
+// (#6.24 tagged) → elementIdentifier / elementValue, and the deviceSigned
+// transaction_data_hash. What is NOT verified here: the issuer/device COSE
+// SIGNATURES and the value digests — that issuer-trust check is the acknowledged
+// future work (main self-signs its mdoc certs, so there is no real trust anchor
+// yet). The crypto that IS real — JWE/HPKE decryption + nonce binding — runs in
+// verify before this parser ever sees the bytes.
+import { decode, Tag } from "cbor-x";
+function b64urlToBytes(s) {
+    return new Uint8Array(Buffer.from(String(s), "base64url"));
+}
+// IssuerSignedItemBytes = #6.24(bstr .cbor IssuerSignedItem). Depending on the
+// cbor-x build, tag 24 arrives as a Tag wrapping bytes or already as bytes.
+function decodeTagged(item) {
+    if (item instanceof Tag)
+        return decode(item.value);
+    if (item instanceof Uint8Array)
+        return decode(item);
+    return item;
+}
+function sanitize(v) {
+    if (v instanceof Uint8Array)
+        return { _bytes_b64url: Buffer.from(v).toString("base64url") };
+    if (v instanceof Tag)
+        return { _tag: v.tag, value: sanitize(v.value) };
+    if (v instanceof Date)
+        return v.toISOString();
+    if (typeof v === "bigint")
+        return v.toString();
+    if (Array.isArray(v))
+        return v.map(sanitize);
+    if (v && typeof v === "object") {
+        const o = {};
+        for (const [k, val] of Object.entries(v))
+            o[k] = sanitize(val);
+        return o;
+    }
+    return v;
+}
+// vp_token from OpenID4VP DC API: { "<dcql-id>": "<base64url DeviceResponse>" }
+// (older shape: an array, or a wrapping array per id). Returns a flattened shape.
+export function decodeVpToken(vpToken) {
+    const entries = Array.isArray(vpToken)
+        ? vpToken.map((v, i) => [String(i), v])
+        : Object.entries(vpToken ?? {});
+    return entries.map(([id, token]) => {
+        const str = Array.isArray(token) ? token[0] : token;
+        const dr = decode(b64urlToBytes(str));
+        const flat = [];
+        let type;
+        for (const doc of dr.documents ?? []) {
+            type = doc.docType;
+            const nameSpaces = doc.issuerSigned?.nameSpaces ?? {};
+            for (const [ns, items] of Object.entries(nameSpaces)) {
+                for (const raw of items) {
+                    const isi = decodeTagged(raw);
+                    flat.push({ label: `${ns} / ${isi.elementIdentifier}`, value: sanitize(isi.elementValue) });
+                }
+            }
+        }
+        return { id, format: "mso_mdoc", type, claims: flat };
+    });
+}
+// The payment binding lives in deviceSigned, not issuerSigned. Returns the
+// transaction_data_hash bytes as base64url, or null.
+export function extractTransactionDataHash(vpStr, namespace = "urn:eudi:sca:payment:1", element = "transaction_data_hash") {
+    const str = Array.isArray(vpStr) ? vpStr[0] : vpStr;
+    const dr = decode(b64urlToBytes(str));
+    for (const doc of dr.documents ?? []) {
+        const ns = decodeTagged(doc.deviceSigned?.nameSpaces);
+        const val = ns?.[namespace]?.[element];
+        if (val instanceof Uint8Array)
+            return Buffer.from(val).toString("base64url");
+    }
+    return null;
+}
+export function inspectAuthBlocks(vpStr) {
+    const str = Array.isArray(vpStr) ? vpStr[0] : vpStr;
+    const dr = decode(b64urlToBytes(str));
+    const doc = (dr.documents ?? [])[0] ?? {};
+    const issuerAuth = doc.issuerSigned?.issuerAuth;
+    const deviceAuth = doc.deviceSigned?.deviceAuth;
+    return {
+        hasIssuerAuth: Array.isArray(issuerAuth) && issuerAuth.length > 0,
+        hasDeviceAuth: !!(deviceAuth && (deviceAuth.deviceSignature || deviceAuth.deviceMac)),
+        docType: doc.docType ?? null,
+    };
+}

package/dist/ceremony/mdoc/reader.d.ts

@@ -0,0 +1,10 @@
+import * as jose from "jose";
+import type { webcrypto as NodeWebCrypto } from "node:crypto";
+export declare function makeReaderCert(rpID: string): Promise<{
+    x5c: string;
+    privateKey: NodeWebCrypto.CryptoKey;
+}>;
+export declare function makeEncryptionKey(): Promise<{
+    encJwk: jose.JWK;
+    ecdhPrivateJwk: jose.JWK;
+}>;

package/dist/ceremony/mdoc/reader.js

@@ -0,0 +1,43 @@
+// Reader-side key + cert material for the Android-Chrome OpenID4VP path, shared by
+// both rails' REAL signed-request builders. Extracted FAITHFULLY from the demo's
+// payment-gate/dc-payment/request.ts (makeReaderCert + makeEncryptionKey).
+//
+// REAL crypto: a P-256 reader certificate is minted with @peculiar/x509 (SAN-DNS =
+// RP-ID, SubjectKeyIdentifier required or the wallet's TrustManagerUtil NPEs) and
+// an ephemeral P-256 ECDH key the wallet encrypts its response to. The request is
+// then ES256-signed (jose.SignJWT) over the verifier-bound request object. The one
+// thing NOT yet real is the issuer TRUST ANCHOR — the reader cert is self-signed
+// here (as the demo's is), so origin/RP binding is enforced but cross-issuer trust
+// is not.
+import * as jose from "jose";
+import * as x509 from "@peculiar/x509";
+const webcrypto = globalThis.crypto;
+x509.cryptoProvider.set(webcrypto);
+const SIGN_ALG = { name: "ECDSA", namedCurve: "P-256", hash: "SHA-256" };
+export async function makeReaderCert(rpID) {
+    const keys = await webcrypto.subtle.generateKey(SIGN_ALG, true, ["sign", "verify"]);
+    const cert = await x509.X509CertificateGenerator.createSelfSigned({
+        serialNumber: "01",
+        name: `CN=${rpID}`,
+        notBefore: new Date(Date.now() - 60_000),
+        notAfter: new Date(Date.now() + 86_400_000),
+        signingAlgorithm: SIGN_ALG,
+        keys,
+        extensions: [
+            new x509.SubjectAlternativeNameExtension([{ type: "dns", value: rpID }]),
+            // The Subject Key Identifier extension is REQUIRED — without it the wallet's
+            // TrustManagerUtil does subjectKeyIdentifier!! → NPE.
+            await x509.SubjectKeyIdentifierExtension.create(keys.publicKey),
+        ],
+    });
+    return { x5c: cert.toString("base64"), privateKey: keys.privateKey };
+}
+// Ephemeral P-256 key the wallet encrypts its response to. Shared by the payment
+// and credential gates so both build the response-encryption JWK identically.
+export async function makeEncryptionKey() {
+    const encKP = await webcrypto.subtle.generateKey({ name: "ECDH", namedCurve: "P-256" }, true, ["deriveBits"]);
+    const encPubJwk = await webcrypto.subtle.exportKey("jwk", encKP.publicKey);
+    const ecdhPrivateJwk = (await webcrypto.subtle.exportKey("jwk", encKP.privateKey));
+    const encJwk = { kty: "EC", crv: "P-256", x: encPubJwk.x, y: encPubJwk.y, use: "enc", alg: "ECDH-ES", kid: "response-encryption-key" };
+    return { encJwk, ecdhPrivateJwk };
+}

package/dist/ceremony/mdoc/readerContext.d.ts

@@ -0,0 +1,8 @@
+import * as jose from "jose";
+export interface ReaderContext {
+    ecdhPrivateJwk: jose.JWK;
+    transactionDataB64: string;
+    nonce?: string;
+}
+export declare function sealReaderContext(ctx: ReaderContext, secret: string, ttlMs?: number): Promise<string>;
+export declare function openReaderContext(token: string, secret: string): Promise<ReaderContext>;

package/dist/ceremony/mdoc/readerContext.js

@@ -0,0 +1,29 @@
+// Stateless carrier for the reader's ephemeral ECDH private key + the bound
+// transaction_data (and the request nonce) between /request and /verify. Extracted
+// FAITHFULLY from the demo's payment-gate/dc-payment/readerContext.ts.
+//
+// REAL crypto: sealed as a JWE (dir / A256GCM) under a key derived from the host's
+// signingKey, with a short expiry. Confidentiality matters (it wraps a PRIVATE
+// key), so we encrypt rather than just HMAC — `jose.CompactEncrypt` /
+// `jose.compactDecrypt`. The nonce sealed here is what /verify requires the
+// wallet's response to be bound to (apu/apv echo) — not merely "a token decrypted".
+import { createHash } from "node:crypto";
+import * as jose from "jose";
+const DEFAULT_TTL_MS = 180_000;
+function keyFromSecret(secret) {
+    return new Uint8Array(createHash("sha256").update(secret).digest());
+}
+export async function sealReaderContext(ctx, secret, ttlMs = DEFAULT_TTL_MS) {
+    const payload = { ...ctx, exp: Date.now() + ttlMs };
+    const plaintext = new TextEncoder().encode(JSON.stringify(payload));
+    return await new jose.CompactEncrypt(plaintext)
+        .setProtectedHeader({ alg: "dir", enc: "A256GCM" })
+        .encrypt(keyFromSecret(secret));
+}
+export async function openReaderContext(token, secret) {
+    const { plaintext } = await jose.compactDecrypt(token, keyFromSecret(secret));
+    const payload = JSON.parse(new TextDecoder().decode(plaintext));
+    if (Date.now() > payload.exp)
+        throw new Error("reader context expired");
+    return { ecdhPrivateJwk: payload.ecdhPrivateJwk, transactionDataB64: payload.transactionDataB64, nonce: payload.nonce };
+}

package/dist/ceremony/mount.d.ts

@@ -0,0 +1,57 @@
+import type { VerificationStore } from "../types.js";
+import { type Origin, type RequestLike } from "./origin.js";
+import type { CeremonyCatalog, CeremonyOrder, CeremonyOrderStore, CompletionSeam, SettlementSeam } from "./types.js";
+/** Minimal Express-app shape mount() needs (no `express` dependency). */
+export interface CeremonyApp {
+    locals: Record<string, unknown>;
+    get?(path: string, ...handlers: unknown[]): unknown;
+    post?(path: string, ...handlers: unknown[]): unknown;
+    use?(path: string, ...handlers: unknown[]): unknown;
+}
+/** What the host injects. Required seams throw if missing (CT2); `origin`,
+ *  `settlement`, and the signing-key escape hatch have safe behaviors. */
+export interface CeremonySeams {
+    /** Per-order verification state (never process-global — invariant 4). */
+    verificationStore: VerificationStore;
+    /** Resolve a created order by id (totals are re-priced from `catalog`). */
+    orderStore: CeremonyOrderStore;
+    /** Server-side re-pricing — the amount source of truth (invariant 2). */
+    catalog: CeremonyCatalog;
+    /** Host-bound completion (idempotent record + cart/verification clear). */
+    completion: CompletionSeam;
+    /** Stable HMAC key for the challenge nonce. Required so options→verify survive
+     *  an instance split (D6) UNLESS `allowEphemeralKey` is explicitly set. */
+    signingKey?: string;
+    /** RP-id / origin derivation; defaults to the built-in `deriveOrigin`. */
+    origin?: (req: RequestLike) => Origin;
+    /** Optional demo-mode settlement seam (absent ⇒ mock-complete). */
+    settlement?: SettlementSeam;
+    /** Dev-only: allow an ephemeral per-process signing key. NEVER inferred —
+     *  mount() does not guess "serverless". */
+    allowEphemeralKey?: boolean;
+}
+/** The resolved context each rail receives (every required seam present). */
+export interface CeremonyContext {
+    verificationStore: VerificationStore;
+    orderStore: CeremonyOrderStore;
+    catalog: CeremonyCatalog;
+    completion: CompletionSeam;
+    signingKey: string;
+    origin: (req: RequestLike) => Origin;
+    settlement?: SettlementSeam;
+}
+/** A rail attaches its routes to the host app given the resolved context. */
+export type RailRegistrar = (app: CeremonyApp, ctx: CeremonyContext) => void;
+/**
+ * Read + validate the injected seams, build the CeremonyContext, and register
+ * every rail's routes. Throws on a missing required seam (CT2). Seams may arrive
+ * via `options` OR `app.locals.attestomcp` — options win.
+ */
+export declare function mountCeremony(app: CeremonyApp, options?: Partial<CeremonySeams>): CeremonyContext;
+/**
+ * Shared order resolution + re-pricing (T003a). Resolve a created order by id
+ * from the injected store, then RE-PRICE it from the catalog — the displayed and
+ * bound amounts come from the catalog, never the id/token (CT3, invariants 2/3).
+ * A tampered or unknown id resolves to `null` (the rail refuses).
+ */
+export declare function resolveOrder(ctx: CeremonyContext, orderId: string | undefined | null): Promise<CeremonyOrder | null>;

package/dist/ceremony/mount.js

@@ -0,0 +1,96 @@
+// The injected-seam contract for the ceremony (Context 2). `mountCeremony(app)`
+// reads the seams the host provides (options + `app.locals.attestomcp`), FAILS FAST
+// when a load-bearing one is missing (CT2 — never silently degrade), resolves a
+// CeremonyContext, and registers each rail's routes onto the host app. With no
+// rails extracted yet (Phase 2 — Foundational), it validates the seams + builds
+// the context only; the passkey / dc-payment / credential-gate rails push their
+// registrars here as they land (US1–US3).
+//
+// The package stays dependency-free: `CeremonyApp` is a minimal structural type
+// (no `express` import) carrying just `locals` + the route methods a rail needs.
+import { randomBytes } from "node:crypto";
+import { deriveOrigin } from "./origin.js";
+import { registerCredentialGate } from "./credential-gate/routes.js";
+import { registerPasskeyGate } from "./passkey/routes.js";
+import { registerDcPaymentGate } from "./dc-payment/routes.js";
+// Per-rail registration scaffold. Each rail (passkey / dc-payment /
+// credential-gate) pushes its registrar here once extracted (US1–US3). US1 lands
+// the credential gate (age + membership); passkey / dc-payment follow (US2/US3).
+// Each registrar no-ops on a route-less app shape, so mount()'s fail-fast tests
+// (which pass a `{ locals }`-only app) are unaffected.
+const RAILS = [registerCredentialGate, registerPasskeyGate, registerDcPaymentGate];
+/**
+ * Read + validate the injected seams, build the CeremonyContext, and register
+ * every rail's routes. Throws on a missing required seam (CT2). Seams may arrive
+ * via `options` OR `app.locals.attestomcp` — options win.
+ */
+export function mountCeremony(app, options = {}) {
+    const locals = (app.locals.attestomcp ?? {});
+    const verificationStore = options.verificationStore ?? locals.verificationStore ?? locals.store;
+    const orderStore = options.orderStore ?? locals.orderStore;
+    const catalog = options.catalog ?? locals.catalog;
+    const completion = options.completion ?? locals.completion;
+    const settlement = options.settlement ?? locals.settlement;
+    const origin = options.origin ?? locals.origin ?? deriveOrigin;
+    const allowEphemeralKey = options.allowEphemeralKey ?? locals.allowEphemeralKey ?? false;
+    let signingKey = options.signingKey ?? locals.signingKey;
+    // Fail fast (CT2) — a load-bearing seam must never silently default. (`origin`
+    // has a safe built-in default; `settlement` is genuinely optional.)
+    const missing = [];
+    if (!verificationStore)
+        missing.push("verificationStore");
+    if (!orderStore)
+        missing.push("orderStore");
+    if (!catalog)
+        missing.push("catalog");
+    if (!completion)
+        missing.push("completion");
+    if (missing.length > 0) {
+        throw new Error(`[attestomcp] mount(): missing required ceremony seam(s): ${missing.join(", ")}. ` +
+            `Provide them via attestomcp.mount(app, { ... }) or app.locals.attestomcp.`);
+    }
+    // The challenge HMAC must survive an instance split (options→verify may hit
+    // different serverless instances — D6). We do NOT infer "serverless"; an
+    // ephemeral per-process key is allowed ONLY when the host opts in explicitly.
+    if (!signingKey) {
+        if (!allowEphemeralKey) {
+            throw new Error(`[attestomcp] mount(): a stable 'signingKey' is required so the challenge HMAC survives an instance split. ` +
+                `Pass { signingKey } (e.g. process.env.GATE_SECRET), or { allowEphemeralKey: true } for a single-process dev server.`);
+        }
+        signingKey = randomBytes(32).toString("hex");
+    }
+    const ctx = {
+        verificationStore: verificationStore,
+        orderStore: orderStore,
+        catalog: catalog,
+        completion: completion,
+        signingKey,
+        origin,
+        ...(settlement ? { settlement } : {}),
+    };
+    // Re-expose the resolved seams on app.locals so the storefront's gate routes
+    // resolve verification THROUGH AttestoMcp (and a re-mount is idempotent).
+    app.locals.attestomcp = { ...app.locals.attestomcp, store: ctx.verificationStore, ...ctx };
+    for (const register of RAILS)
+        register(app, ctx);
+    return ctx;
+}
+/**
+ * Shared order resolution + re-pricing (T003a). Resolve a created order by id
+ * from the injected store, then RE-PRICE it from the catalog — the displayed and
+ * bound amounts come from the catalog, never the id/token (CT3, invariants 2/3).
+ * A tampered or unknown id resolves to `null` (the rail refuses).
+ */
+export async function resolveOrder(ctx, orderId) {
+    if (!orderId)
+        return null;
+    const stored = await ctx.orderStore.read(orderId);
+    if (!stored || stored.id !== orderId || !Array.isArray(stored.lines))
+        return null;
+    // A loyalty discount is applied only when THIS order's verification opts in
+    // (invariant 3); the line items come from the store, every price from the
+    // catalog.
+    const verification = await ctx.verificationStore.read(orderId);
+    const loyaltyApplied = !!verification?.loyalty?.applied;
+    return ctx.catalog.createOrder(stored.lines.map((l) => ({ productId: l.id, quantity: l.quantity })), orderId, { loyaltyApplied });
+}

package/dist/ceremony/origin.d.ts

@@ -0,0 +1,10 @@
+export interface RequestLike {
+    headers: Record<string, string | string[] | undefined>;
+    host: string;
+    protocol: string;
+}
+export interface Origin {
+    rpID: string;
+    origin: string;
+}
+export declare function deriveOrigin(req: RequestLike): Origin;

package/dist/ceremony/origin.js

@@ -0,0 +1,9 @@
+function first(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+export function deriveOrigin(req) {
+    const host = first(req.headers["x-forwarded-host"]) ?? req.host;
+    const proto = first(req.headers["x-forwarded-proto"]) ?? req.protocol;
+    const rpID = host.split(":")[0];
+    return { rpID, origin: `${proto}://${host}` };
+}

package/dist/ceremony/passkey/page.d.ts

@@ -0,0 +1,6 @@
+import type { CeremonyOrder } from "../types.js";
+export declare function renderPasskeyPage(args: {
+    order: CeremonyOrder;
+    crossDevice?: boolean;
+    returnUrl?: string;
+}): string;