mppx 0.15.0 → 0.17.0

package/dist/server/Mppx.js

@@ -1,10 +1,10 @@
 import { isDeepStrictEqual } from 'node:util';
-import * as AttestationServer from '../attestation/Server.js';
 import * as Challenge from '../Challenge.js';
 import * as Constants from '../Constants.js';
 import * as Credential from '../Credential.js';
 import * as Errors from '../Errors.js';
 import * as Expires from '../Expires.js';
+import * as IdentityServer from '../identity/Server.js';
 import * as AcceptPayment from '../internal/AcceptPayment.js';
 import * as Env from '../internal/env.js';
 import { warnOnce } from '../internal/warnOnce.js';
@@ -59,17 +59,19 @@ export const reservedMppxKeys = new Set(reservedMppxKeyValues);
  * ```
  */
 export function create(config) {
-    const { attestation, requiresAuth, realm = Env.get('realm'), selectOffers, secretKey = Env.get('secretKey'), transport = Transport.http({ requiresAuth }), } = config;
+    const { requiresAuth, realm = Env.get('realm'), selectOffers, secretKey = Env.get('secretKey'), transport = Transport.http({ requiresAuth }), } = config;
     const credentialHeader = requiresAuth ? Constants.Headers.paymentAuthorization : undefined;
+    if ('attestation' in config)
+        throw new TypeError('Mppx server `attestation` was replaced by per-route `identity`: pass `identity: [verifier]` to each route.');
+    // Identity is configured per route; a top-level option would otherwise be ignored (fail open).
+    if ('identity' in config)
+        throw new TypeError('Mppx server identity is configured per route: pass `identity: [verifier]` to each route.');
     if (!secretKey) {
         throw new Error('Missing secret key. Set the MPP_SECRET_KEY environment variable or pass `secretKey` to Mppx.create().');
     }
     SecretKey.assert(secretKey);
     const methods = config.methods.flat();
     const serverEvents = createServerEventDispatcher();
-    const verifyAttestation = attestation
-        ? createAttestationGuard(attestation)
-        : undefined;
     const handlers = {};
     const methodHandlers = new Map();
     const intentCount = {};
@@ -87,7 +89,6 @@ export function create(config) {
     assertNoReservedMppxKeys(methods);
     for (const mi of methods) {
         const fn = createMethodFn({
-            ...(verifyAttestation && { attest: verifyAttestation }),
             authorize: mi.authorize,
             credentialHeader,
             defaults: mi.defaults,
@@ -436,8 +437,19 @@ export function create(config) {
 }
 // biome-ignore lint/correctness/noUnusedVariables: _
 function createMethodFn(parameters) {
-    const { attest, authorize, credentialHeader, defaults, events, method, preflight, realm, respond, secretKey, broadcast, stableBinding, transport, validate, verify, } = parameters;
-    return (options) => {
+    const { authorize, credentialHeader, defaults, events, method, preflight, realm, respond, secretKey, broadcast, stableBinding, transport, validate, verify, } = parameters;
+    return (routeOptions) => {
+        const { identity = [], ...options } = routeOptions;
+        const requestVerifiers = identity.filter((verifier) => IdentityServer.stageOf(verifier) === 'request');
+        const paymentVerifiers = identity.filter((verifier) => IdentityServer.stageOf(verifier) === 'payment');
+        // Preflight hooks (e.g. session bootstrap) issue and settle their own challenges, which
+        // payment-stage verifiers cannot see; reject the combination instead of skipping identity.
+        if (paymentVerifiers.length > 0 && preflight)
+            throw new TypeError(`Payment-stage identity is not supported on ${method.name}/${method.intent} routes with a preflight hook.`);
+        // The HTML checkout cannot answer identity challenges, and it pays before resubmitting, so
+        // a browser would pay and then be rejected.
+        if (paymentVerifiers.length > 0 && method.html)
+            throw new TypeError(`Payment-stage identity is not supported on ${method.name}/${method.intent} routes with the HTML checkout.`);
         const { description, meta, scope, ...rest } = options;
         const staticMeta = Scope.merge({ meta, scope });
         const internal = {
@@ -455,20 +467,26 @@ function createMethodFn(parameters) {
                 ]),
             ],
             _canonicalRequest: PaymentRequest.fromMethod(method, { ...defaults, ...rest }),
+            _paymentIdentity: paymentVerifiers.length > 0 ? paymentVerifiers : undefined,
             _stableBinding: stableBinding,
             _transport: transport,
         };
         Object.defineProperty(internal, '_method', { value: method });
         const handler = async (input) => {
-            if (attest && input instanceof globalThis.Request) {
-                const response = await attest(input);
-                if (response)
-                    return {
-                        status: 200,
-                        withReceipt() {
-                            return response;
-                        },
-                    };
+            const identityValues = new Map();
+            if (identity.length > 0) {
+                if (!(input instanceof globalThis.Request))
+                    throw new TypeError('Route identity requires the HTTP transport.');
+                const outcome = await IdentityServer.verify(input, requestVerifiers);
+                if (outcome.status !== 'valid') {
+                    // Returned on the non-200 branch so callers never run paid work: like an early
+                    // rejection, `challenge` holds the identity response (401/403) to send as is.
+                    const rejection = IdentityServer.toResponse(outcome);
+                    identityRejections.add(rejection);
+                    return { challenge: rejection, status: 402 };
+                }
+                for (const [verifier, value] of outcome.values)
+                    identityValues.set(verifier, value);
             }
             if (method.html && isServiceWorkerRequest(input))
                 return {
@@ -482,6 +500,12 @@ function createMethodFn(parameters) {
             const effectiveMeta = scope === undefined && input instanceof globalThis.Request
                 ? Scope.merge({ meta: staticMeta, scope: Scope.get(input) })
                 : staticMeta;
+            // Every offer of one 402 shares the identity nonce (composed routes pass each offer the
+            // same request), so a payment-stage proof is bound to the 402, whichever offer is paid.
+            const identityNonce = paymentVerifiers.length > 0 && input instanceof globalThis.Request
+                ? IdentityServer.nonceFor(input, ChallengeMeta.createNonce)
+                : undefined;
+            const challengeMeta = ChallengeMeta.withIdentity(effectiveMeta, identityNonce);
             // Extract credential once — getCredential may have side effects (e.g. SSE transports).
             let [credential, credentialError] = (() => {
                 try {
@@ -507,6 +531,7 @@ function createMethodFn(parameters) {
                         return { challenge: response, status: 402 };
                     return {
                         status: 200,
+                        identity: IdentityServer.results(identityValues),
                         withReceipt() {
                             return response;
                         },
@@ -514,12 +539,31 @@ function createMethodFn(parameters) {
                 }
             }
             const emitChallenge = async (parameters) => {
-                const response = await transport.respondChallenge({
+                let response = await transport.respondChallenge({
                     challenge: parameters.challenge,
                     input,
                     ...(parameters.error && { error: parameters.error }),
                     ...(parameters.html && { html: parameters.html }),
                 });
+                // Payment-stage verifiers add their own challenge headers to the 402.
+                if (identityNonce !== undefined &&
+                    input instanceof globalThis.Request &&
+                    response instanceof globalThis.Response) {
+                    const identityHeaders = await IdentityServer.challenge(input, paymentVerifiers, identityNonce);
+                    if ([...identityHeaders].length > 0) {
+                        const paymentChallenge = response.headers.get(paymentAuthChallengeHeader);
+                        const headers = new Headers(response.headers);
+                        for (const [name, value] of identityHeaders)
+                            headers.append(name, value);
+                        response = new globalThis.Response(response.body, {
+                            headers,
+                            status: response.status,
+                            statusText: response.statusText,
+                        });
+                        identityChallenges.set(response, identityHeaders);
+                        paymentChallenges.set(response, paymentChallenge);
+                    }
+                }
                 if (isIssuedChallengeResponse(response))
                     await events.emit('challenge.created', createChallengeContext({
                         capturedRequest,
@@ -552,7 +596,7 @@ function createMethodFn(parameters) {
                 description,
                 expires,
                 header: credentialHeader,
-                meta: effectiveMeta,
+                meta: challengeMeta,
                 method,
                 realm,
                 request: parameters.request,
@@ -567,7 +611,7 @@ function createMethodFn(parameters) {
                     description,
                     expires,
                     header: credentialHeader,
-                    meta: effectiveMeta,
+                    meta: challengeMeta,
                     method,
                     realm,
                     routeRequest: rest,
@@ -637,6 +681,7 @@ function createMethodFn(parameters) {
                 const result = {
                     status: 200,
                     challenge,
+                    identity: IdentityServer.results(identityValues),
                     withReceipt(response) {
                         if (managementResponse) {
                             return transport.respondReceipt({
@@ -666,7 +711,17 @@ function createMethodFn(parameters) {
             };
             // No credential provided—issue challenge
             if (!credential) {
-                if (authorize && input instanceof globalThis.Request) {
+                // Authorization without a payment credential still requires payment-stage identity;
+                // a verifier that needs the credential reports missing, so the route issues its 402.
+                const authorizeIdentity = authorize && input instanceof globalThis.Request && paymentVerifiers.length > 0
+                    ? await IdentityServer.verify(input, paymentVerifiers, { challenge })
+                    : undefined;
+                if (authorize &&
+                    input instanceof globalThis.Request &&
+                    (!authorizeIdentity || authorizeIdentity.status === 'valid')) {
+                    if (authorizeIdentity?.status === 'valid')
+                        for (const [verifier, value] of authorizeIdentity.values)
+                            identityValues.set(verifier, value);
                     try {
                         const authorized = await authorize({
                             challenge,
@@ -839,6 +894,34 @@ function createMethodFn(parameters) {
                 credential: parsedCredential,
                 request: parsedRequest,
             });
+            // Payment-stage identity is checked against the answered challenge before settlement.
+            if (paymentVerifiers.length > 0) {
+                const outcome = await IdentityServer.verify(input, paymentVerifiers, {
+                    challenge: credential.challenge,
+                    credential: parsedCredential,
+                    nonce: ChallengeMeta.identity(credential.challenge.meta),
+                });
+                if (outcome.status !== 'valid') {
+                    const error = new Errors.VerificationFailedError({ reason: outcome.reason });
+                    await emitPaymentFailed({
+                        challenge,
+                        credential: parsedCredential,
+                        error,
+                        request: parsedRequest,
+                        retryChallenge: challenge,
+                        submittedChallenge: credential.challenge,
+                    });
+                    // The client may already have pushed this payment, so a fresh 402 would invite
+                    // it to pay again. Reject without a challenge, like a replayed credential.
+                    // Returned on the non-200 branch so callers never run paid work: like an early
+                    // rejection, `challenge` holds the identity response (401/403) to send as is.
+                    const rejection = IdentityServer.toResponse(outcome);
+                    identityRejections.add(rejection);
+                    return { challenge: rejection, status: 402 };
+                }
+                for (const [verifier, value] of outcome.values)
+                    identityValues.set(verifier, value);
+            }
             // User-provided verification (e.g., check signature, submit tx, verify payment).
             // If verification fails, re-issue the challenge so the client can retry.
             let receiptData;
@@ -922,7 +1005,7 @@ function createMethodFn(parameters) {
 function createChallengeFn(parameters) {
     const { credentialHeader, defaults, method, realm, secretKey } = parameters;
     return async (options) => {
-        const { description, meta, scope, ...rest } = options;
+        const { description, identity: _, meta, scope, ...rest } = options;
         const effectiveMeta = Scope.merge({ meta, scope });
         const expires = 'expires' in options
             ? normalizeExpires(options.expires)
@@ -941,33 +1024,6 @@ function createChallengeFn(parameters) {
         }).then((resolved) => resolved.challenge);
     };
 }
-function createAttestationGuard(verifiers) {
-    const entries = Object.entries(verifiers);
-    if (entries.length === 0)
-        throw new TypeError('Mppx server attestation must configure at least one verifier.');
-    const cache = new WeakMap();
-    return (request) => {
-        const cached = cache.get(request);
-        if (cached)
-            return cached;
-        const verification = AttestationServer.verify(request, verifiers).then((outcomes) => {
-            for (const [name, outcome] of Object.entries(outcomes))
-                if (outcome.status === 'invalid')
-                    return new globalThis.Response(`Request attestation "${name}" is invalid: ${outcome.reason}`, { status: 401 });
-            for (const [name, outcome] of Object.entries(outcomes)) {
-                if (outcome.status === 'verified')
-                    continue;
-                const reason = outcome.status === 'unverified'
-                    ? `Request attestation "${name}" could not be verified: ${outcome.reason}`
-                    : `Request attestation "${name}" is required.`;
-                return new globalThis.Response(reason, { status: 403 });
-            }
-            return undefined;
-        });
-        cache.set(request, verification);
-        return verification;
-    };
-}
 /** Dispatches instance events and scopes success hooks to the supplied configured method. */
 function createServerEventDispatcher() {
     const handlers = {
@@ -1295,6 +1351,7 @@ async function resolveRouteChallenge(parameters) {
             ? (await parameters.request({
                 capturedRequest: parameters.capturedRequest,
                 credential: parameters.credential,
+                expires: parameters.credential?.challenge.expires ?? parameters.expires,
                 request: merged,
             }))
             : merged;
@@ -1531,11 +1588,34 @@ function withParsedCredentialPayload(credential, payload) {
     };
 }
 const paymentAuthChallengeHeader = Constants.Headers.wwwAuthenticate;
+/** Payment-stage identity headers added to issued 402 responses, keyed by response. @internal */
+const identityChallenges = new WeakMap();
+/** Identity rejections (401/403) returned on a route's non-success branch. @internal */
+const identityRejections = new WeakSet();
+/**
+ * A 402's Payment `WWW-Authenticate` value without its identity challenge, keyed by response.
+ * Composers merge these and append the shared identity challenge once. @internal
+ */
+const paymentChallenges = new WeakMap();
+/** Records a merged 402's identity challenge so an outer composer can forward it. @internal */
+function withIdentityChallenge(response, headers, paymentChallenge) {
+    if (headers) {
+        identityChallenges.set(response, headers);
+        paymentChallenges.set(response, paymentChallenge);
+    }
+    return response;
+}
 const challengeHeaderMerges = [
     {
         name: paymentAuthChallengeHeader,
         values: (context) => context.challengeEntries
-            .map((entry) => entry.result.challenge.headers.get(paymentAuthChallengeHeader))
+            .map((entry) => {
+            const response = entry.result.challenge;
+            // Identity challenges are appended once by the composer, not once per offer.
+            return paymentChallenges.has(response)
+                ? paymentChallenges.get(response)
+                : response.headers.get(paymentAuthChallengeHeader);
+        })
             .filter((value) => value !== null),
         merge: (values) => values,
     },
@@ -1576,6 +1656,13 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
     });
     if (handlers.length === 0)
         throw new Error('compose() requires at least one handler');
+    // A 402 carries one identity challenge, shared by its offers through the identity nonce, so
+    // every offer that requires payment-stage identity must require the same verifiers.
+    const identityOffers = handlers
+        .flatMap(getConfiguredOffers)
+        .flatMap((offer) => (offer._paymentIdentity ? [offer._paymentIdentity] : []));
+    if (identityOffers.some((verifiers) => !sameVerifiers(verifiers, identityOffers[0])))
+        throw new TypeError('Offers in a composed route must require the same payment-stage identity verifiers.');
     const offerSelector = selectOffers;
     const offerEntries = handlers.map((handler) => {
         const internal = handler._internal;
@@ -1684,21 +1771,30 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
             return transportCredentialHandler(input);
         // No credential — evaluate handlers sequentially so authorize()/renewal hooks
         // can safely claim the request without racing each other.
+        // An identity rejection from one offer does not hide the others: it is returned only
+        // when no offer issued a payment challenge.
         const results = [];
         for (const handler of selectedHandlers) {
             const result = transportResults.get(handler) ?? (await handler(input));
             if (result.status === 200)
                 return result;
-            if (result.challenge.status !== 402)
+            const rejected = identityRejections.has(result.challenge);
+            if (result.challenge.status !== 402 && !rejected)
                 return result;
             results.push(result);
         }
+        const offers = results.filter((result) => result.status === 402 && !identityRejections.has(result.challenge));
+        if (offers.length === 0 && results[0])
+            return results[0];
         const challengeEntries = (() => {
             const entries = [];
             for (let i = 0; i < selectedHandlers.length; i++) {
                 const result = results[i];
                 if (result?.status !== 402)
                     continue;
+                // Identity rejections may carry non-Payment challenges (e.g. Bearer); they are not offers.
+                if (identityRejections.has(result.challenge))
+                    continue;
                 const response = result.challenge;
                 const wwwAuth = response.headers.get(paymentAuthChallengeHeader);
                 if (!wwwAuth)
@@ -1723,7 +1819,7 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
                 return entries;
             }
         })();
-        const challengeResponses = results.flatMap((result) => result.status === 402 ? [result.challenge] : []);
+        const challengeResponses = offers.map((result) => result.challenge);
         const unnegotiatedX402Responses = input.headers.has(Constants.Headers.acceptPayment) || challengeEntries.length === 0
             ? []
             : challengeResponses.filter((response) => response.headers.has(x402_Types.paymentRequiredHeader) &&
@@ -1734,6 +1830,11 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
                 ...unnegotiatedX402Responses,
             ]
             : challengeResponses;
+        // Offers share one identity challenge (enforced when composing); forward it only if an
+        // offer that carries it is still advertised after negotiation.
+        const identityHeaders = negotiatedChallengeResponses
+            .map((response) => identityChallenges.get(response))
+            .find((headers) => headers !== undefined);
         // Merge challenge headers from the negotiated 402 responses.
         const mergedHeaders = new Headers();
         mergedHeaders.set('Cache-Control', 'no-store');
@@ -1746,6 +1847,11 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
                 mergedHeaders.append(header.name, value);
             }
         }
+        // The merged offer values above exclude identity challenges; append the shared one once.
+        const paymentChallenge = mergedHeaders.get(paymentAuthChallengeHeader);
+        if (identityHeaders)
+            for (const [name, value] of identityHeaders)
+                mergedHeaders.append(name, value);
         // Collect html-enabled handlers and their challenges
         const htmlEntries = challengeEntries.filter((entry) => entry.handler._internal?.html);
         const wantsHtml = input.headers.get('Accept')?.includes('text/html');
@@ -1782,7 +1888,7 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
             });
             return {
                 status: 402,
-                challenge: new Response(body, { status: 402, headers: mergedHeaders }),
+                challenge: withIdentityChallenge(new Response(body, { status: 402, headers: mergedHeaders }), identityHeaders, paymentChallenge),
             };
         }
         // Non-HTML fallback: prefer the first Payment-auth body, otherwise use
@@ -1802,7 +1908,7 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
         }
         return {
             status: 402,
-            challenge: new Response(body, { status: 402, headers: mergedHeaders }),
+            challenge: withIdentityChallenge(new Response(body, { status: 402, headers: mergedHeaders }), identityHeaders, paymentChallenge),
         };
     };
     const offers = handlers.flatMap(getConfiguredOffers);
@@ -1811,6 +1917,10 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
     return composed;
 }
 /** Returns the flattened configured offers accepted by a handler. */
+/** Whether two verifier lists hold the same verifiers in the same order. */
+function sameVerifiers(a, b) {
+    return a.length === b.length && a.every((verifier, i) => verifier === b[i]);
+}
 function getConfiguredOffers(handler) {
     const internal = handler._internal;
     if (!internal)

package/dist/server/internal/challengeMeta.d.ts

@@ -1,5 +1,11 @@
 /** Adds fresh issuance randomness while preserving application and route metadata. */
 export declare function withNonce(meta: Record<string, string> | undefined): Record<string, string>;
+/** Returns fresh randomness for an identity nonce. */
+export declare function createNonce(): string;
+/** Adds an identity nonce to challenge metadata. */
+export declare function withIdentity(meta: Record<string, string> | undefined, nonce: string | undefined): Record<string, string> | undefined;
+/** Reads the identity nonce from challenge metadata. */
+export declare function identity(meta: Record<string, string> | undefined): string | undefined;
 /** Removes issuance-only metadata when comparing stable route requirements. */
 export declare function routeMeta(meta: Record<string, string> | undefined): Record<string, string> | undefined;
 //# sourceMappingURL=challengeMeta.d.ts.map

package/dist/server/internal/challengeMeta.js

@@ -6,9 +6,25 @@ export function withNonce(meta) {
     // Ox uses runtime-specific secure randomness, including Node without global Web Crypto.
     return { ...meta, [nonceKey]: Secp256k1.randomPrivateKey() };
 }
+/** Reserved metadata key for the HMAC-bound identity nonce shared by every offer in one 402. */
+const identityKey = '_mppx_identity';
+/** Returns fresh randomness for an identity nonce. */
+export function createNonce() {
+    return Secp256k1.randomPrivateKey();
+}
+/** Adds an identity nonce to challenge metadata. */
+export function withIdentity(meta, nonce) {
+    if (nonce === undefined)
+        return meta;
+    return { ...meta, [identityKey]: nonce };
+}
+/** Reads the identity nonce from challenge metadata. */
+export function identity(meta) {
+    return meta?.[identityKey];
+}
 /** Removes issuance-only metadata when comparing stable route requirements. */
 export function routeMeta(meta) {
-    const { [nonceKey]: _, ...rest } = meta ?? {};
+    const { [nonceKey]: _, [identityKey]: __, ...rest } = meta ?? {};
     return Object.keys(rest).length ? rest : undefined;
 }
 //# sourceMappingURL=challengeMeta.js.map