mppx 0.15.0 → 0.16.0

package/dist/server/Mppx.d.ts

@@ -1,8 +1,8 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import type * as Attestation from '../attestation/Types.js';
 import * as Challenge from '../Challenge.js';
 import * as Credential from '../Credential.js';
 import * as Errors from '../Errors.js';
+import type * as Identity from '../identity/Types.js';
 import type { DeepReadonly, MaybePromise } from '../internal/types.js';
 import * as Method from '../Method.js';
 import type * as Receipt from '../Receipt.js';
@@ -277,8 +277,25 @@ type IntentHandlers<methods extends readonly Method.AnyServer[], transport exten
         intent: intent;
     }>, transport>;
 };
+/**
+ * Route identity option. HTTP routes accept identity verifiers, all of which must be valid;
+ * use `Identity.anyOf` to accept one of several protocols. Other transports reject it.
+ */
+type RouteIdentity<transport extends Transport.AnyTransport> = Transport.InputOf<transport> extends Request ? Transport.ChallengeOutputOf<transport> extends Response ? {
+    identity?: readonly Identity.Verifier[] | undefined;
+} : {
+    identity?: never;
+} : {
+    identity?: never;
+};
 /** Handler for an intent with multiple methods - takes the intersection of all methods' options. */
-type MultiMethodFn<methods extends Method.AnyServer, transport extends Transport.AnyTransport> = (options: UnionToIntersection<MultiMethodFnDistribute<methods>>) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>;
+type MultiMethodFn<methods extends Method.AnyServer, transport extends Transport.AnyTransport> = (options: MultiMethodOptions<methods> & RouteIdentity<transport>) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>;
+/**
+ * Intersected options of every method for an intent. When a method's options can't be inferred,
+ * the intersection is `unknown`; fall back to any object (interfaces included) so `RouteIdentity`
+ * doesn't turn it into an object that rejects every option but `identity`.
+ */
+type MultiMethodOptions<methods extends Method.AnyServer> = UnionToIntersection<MultiMethodFnDistribute<methods>> extends infer options ? unknown extends options ? Record<string, any> : options : never;
 type MultiMethodFnDistribute<M> = M extends Method.Server<infer method, infer defaults, any, any, any> ? MethodFn.Options<method, NonNullable<defaults>> : never;
 type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 /** Nested handlers: `mppx.tempo.charge(...)`, grouped by method name then intent. */
@@ -334,8 +351,6 @@ type ChallengeFn<method extends Method.Method, defaults extends Record<string, u
 export declare function create<const methods extends Methods, const transport extends Transport.AnyTransport = Transport.Http>(config: create.Config<methods, transport>): Mppx<methods, transport>;
 export declare namespace create {
     type Config<methods extends Methods = Methods, transport extends Transport.AnyTransport = Transport.Http> = {
-        /** Request-attestation verifiers required before handling an HTTP payment request. */
-        attestation?: transport extends Transport.Http ? Attestation.VerifierMap | undefined : never;
         /** Array of configured methods. @example [tempo()] */
         methods: methods;
         /** Uses `Payment-Authorization` for Payment credentials so `Authorization` remains available for application authentication. */
@@ -357,7 +372,7 @@ export declare class MissingReceiptResponseError extends Error {
 }
 /** Returns true when an error is the typed `withReceipt()` no-response sentinel. */
 export declare function isMissingReceiptResponseError(error: unknown): error is MissingReceiptResponseError;
-export type MethodFn<method extends Method.Method, transport extends Transport.AnyTransport, defaults extends Record<string, unknown>> = (options: MethodFn.Options<method, defaults>) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>;
+export type MethodFn<method extends Method.Method, transport extends Transport.AnyTransport, defaults extends Record<string, unknown>> = (options: MethodFn.Options<method, defaults> & RouteIdentity<transport>) => (input: Transport.InputOf<transport>) => Promise<MethodFn.Response<transport>>;
 /** @internal */
 export type AnyMethodFn = (options: any) => (input: any) => Promise<any>;
 /** @internal */
@@ -379,6 +394,8 @@ declare namespace MethodFn {
         status: 200;
         /** Canonical challenge resolved from the selected route's terms, when available. */
         challenge?: Challenge.Challenge | undefined;
+        /** Verified identity values for the route's verifiers. */
+        identity?: Identity.Results | undefined;
         withReceipt: Transport.WithReceipt<transport>;
     };
 }
@@ -395,6 +412,8 @@ type ConfiguredHandler<transport extends Transport.AnyTransport = Transport.Http
         scope?: string | undefined;
         _canonicalRequest: Record<string, unknown>;
         _stableBinding?: Method.StableBindingFn<Method.Method> | undefined;
+        /** Whether the offer requires payment-stage identity. */
+        _paymentIdentity?: boolean | undefined;
         _transport: Transport.AnyTransport;
     };
 };
@@ -409,19 +428,19 @@ type ComposedHandler<transport extends Transport.AnyTransport = Transport.Http>
 type ComposeEntry<methods extends readonly Method.AnyServer[]> = {
     [i in keyof methods]: readonly [
         methods[i],
-        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>>
+        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>> & RouteIdentity<Transport.Http>
     ];
 }[number] | {
     [i in keyof methods]: readonly [
         `${methods[i]['name']}/${methods[i]['intent']}`,
-        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>>
+        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>> & RouteIdentity<Transport.Http>
     ];
 }[number] | {
     [i in keyof methods]: readonly [
         MethodFn<methods[i], any, any> & {
             _method: methods[i];
         },
-        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>>
+        MethodFn.Options<methods[i], NonNullable<methods[i]['defaults']>> & RouteIdentity<Transport.Http>
     ];
 }[number];
 export declare function compose(...args: readonly unknown[]): ComposedHandler;

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,
             _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 {
@@ -507,6 +525,7 @@ function createMethodFn(parameters) {
                         return { challenge: response, status: 402 };
                     return {
                         status: 200,
+                        identity: IdentityServer.results(identityValues),
                         withReceipt() {
                             return response;
                         },
@@ -514,12 +533,35 @@ 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 (paymentVerifiers.length > 0 &&
+                    input instanceof globalThis.Request &&
+                    response instanceof globalThis.Response) {
+                    const outcome = await IdentityServer.verify(input, paymentVerifiers, {
+                        challenge: parameters.challenge,
+                    });
+                    const identityHeaders = new Headers();
+                    if (outcome.status !== 'valid')
+                        for (const [name, value] of outcome.headers)
+                            identityHeaders.append(name, value);
+                    if ([...identityHeaders].length > 0) {
+                        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);
+                    }
+                }
                 if (isIssuedChallengeResponse(response))
                     await events.emit('challenge.created', createChallengeContext({
                         capturedRequest,
@@ -637,6 +679,7 @@ function createMethodFn(parameters) {
                 const result = {
                     status: 200,
                     challenge,
+                    identity: IdentityServer.results(identityValues),
                     withReceipt(response) {
                         if (managementResponse) {
                             return transport.respondReceipt({
@@ -666,7 +709,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 +892,33 @@ 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,
+                });
+                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 +1002,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 +1021,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 = {
@@ -1531,6 +1584,16 @@ 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();
+/** Records a merged 402's identity challenge so an outer composer can forward it. @internal */
+function withIdentityChallenge(response, headers) {
+    if (headers)
+        identityChallenges.set(response, headers);
+    return response;
+}
 const challengeHeaderMerges = [
     {
         name: paymentAuthChallengeHeader,
@@ -1576,6 +1639,9 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
     });
     if (handlers.length === 0)
         throw new Error('compose() requires at least one handler');
+    // A 402 carries one identity challenge, bound to one payment challenge.
+    if (handlers.flatMap(getConfiguredOffers).filter((offer) => offer._paymentIdentity).length > 1)
+        throw new TypeError('A composed route can include at most one offer with payment-stage identity.');
     const offerSelector = selectOffers;
     const offerEntries = handlers.map((handler) => {
         const internal = handler._internal;
@@ -1684,21 +1750,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 +1798,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 +1809,11 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
                 ...unnegotiatedX402Responses,
             ]
             : challengeResponses;
+        // At most one offer carries an identity challenge (enforced when composing); forward it
+        // only if its payment challenge 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 +1826,11 @@ function composeHandlers(handlers, composeOptions, selectOffers) {
                 mergedHeaders.append(header.name, value);
             }
         }
+        // Identity WWW-Authenticate values already arrive in the merged offer value above.
+        if (identityHeaders)
+            for (const [name, value] of identityHeaders)
+                if (name !== paymentAuthChallengeHeader.toLowerCase())
+                    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 +1867,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),
             };
         }
         // Non-HTML fallback: prefer the first Payment-auth body, otherwise use
@@ -1802,7 +1887,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),
         };
     };
     const offers = handlers.flatMap(getConfiguredOffers);