mppx 0.8.13 → 0.8.14

package/src/Method.ts

@@ -1,5 +1,8 @@
 import type * as Challenge from './Challenge.js'
-import type * as Credential from './Credential.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 type { ExactPartial, LooseOmit, MaybePromise } from './internal/types.js'
 import type * as Receipt from './Receipt.js'
 import type * as Html from './server/internal/html/config.js'
@@ -117,12 +120,72 @@ export type VerifyContext<method extends Method> = {
   request: z.input<method['schema']['request']>
 }
 
+/** Validation hook parameters for a single method. */
+export type ValidateContext<method extends Method> = VerifyContext<method>
+
 /** Response hook parameters for a single method. */
 export type RespondContext<method extends Method> = VerifyContext<method> & {
   input: globalThis.Request
   receipt: Receipt.Receipt
 }
 
+/**
+ * Non-mutating method-specific validation result.
+ *
+ * Returned by {@link ValidateFn} and exposed from `mppx.validateCredential()`.
+ * This confirms that a credential is currently acceptable to the payment
+ * method; it does not settle, reserve, or otherwise consume the payment.
+ */
+export type Validation<method extends Method = Method, details = unknown> = Readonly<{
+  /**
+   * The challenge echoed by the credential and accepted by the method.
+   *
+   * Callers using `Mppx.validateCredential()` receive a challenge whose HMAC,
+   * expiry, route binding, and method identity have already been checked.
+   * Lower-level `Method.validateCredential()` callers must verify challenge
+   * issuance and route binding themselves.
+   */
+  challenge: Challenge.Challenge<
+    z.output<method['schema']['request']>,
+    method['intent'],
+    method['name']
+  >
+  /**
+   * The submitted credential with its method-specific payload parsed by the
+   * selected method schema. This is the exact credential validation examined.
+   */
+  credential: Credential.Credential<
+    z.output<method['schema']['credential']['payload']>,
+    Challenge.Challenge<z.output<method['schema']['request']>, method['intent'], method['name']>
+  >
+  /**
+   * Method-defined, non-mutating validation data.
+   *
+   * Its shape is intentionally method-specific—for example, a recovered payer
+   * address or a simulation result. Consumers must not assume a particular
+   * shape or use it as a settlement receipt.
+   */
+  details: details
+  /** The validated payment intent, repeated for convenient dispatch. */
+  intent: method['intent']
+  /** The validated payment method, repeated for convenient dispatch. */
+  method: method['name']
+  /**
+   * The validated method request after the method's schema transforms.
+   *
+   * For `Mppx.validateCredential()` with route options, this is the
+   * authoritative route request after defaults and request-hook transforms.
+   */
+  request: z.output<method['schema']['request']>
+  /**
+   * Optional payer identity declared by the credential.
+   *
+   * This is an asserted identity, not independent proof of control; methods
+   * that rely on it must validate the relationship to the credential payload.
+   */
+  source?: string | undefined
+}>
+
 /**
  * A server-side configured method with verification logic.
  */
@@ -141,8 +204,15 @@ export type Server<
   preflight?: PreflightFn<method> | undefined
   request?: RequestFn<method> | undefined
   respond?: RespondFn<method> | undefined
+  broadcast?: BroadcastFn<method> | undefined
   stableBinding?: StableBindingFn<method> | undefined
   transport?: transportOverride | undefined
+  validate?: ValidateFn<method> | undefined
+  /**
+   * @deprecated Use `validate` for the non-mutating pre-check and `broadcast`
+   * for settlement. `verify` combines both operations and may consume payment
+   * state, so it cannot support a safe pre-check endpoint.
+   */
   verify: VerifyFn<method>
 }
 export type AnyServer = Server<any, any, any, any, any>
@@ -221,11 +291,148 @@ export type StableBindingFn<method extends Method> = (
   request: z.output<method['schema']['request']>,
 ) => Record<string, unknown>
 
-/** Verification function for a single method. */
+/**
+ * Legacy combined validation and settlement function for a single method.
+ *
+ * @deprecated Implement `validate` and `broadcast` instead. `validate` must
+ * be non-mutating; `broadcast` performs the terminal payment operation. This
+ * hook remains only for existing methods that cannot yet split those phases.
+ */
 export type VerifyFn<method extends Method> = (
   parameters: VerifyContext<method>,
 ) => Promise<Receipt.Receipt>
 
+/**
+ * Non-mutating validation function for a single method.
+ *
+ * @returns A {@link Validation} record describing the credential that was
+ * accepted. It must not settle, reserve, or otherwise consume payment state.
+ */
+export type ValidateFn<method extends Method> = (
+  parameters: ValidateContext<method>,
+) => Promise<Validation<method>>
+
+/** Terminal payment function for a single method. */
+export type BroadcastFn<method extends Method> = (
+  parameters: VerifyContext<method>,
+) => Promise<Receipt.Receipt>
+
+/**
+ * Validates a credential against one of the configured methods.
+ *
+ * This checks credential structure, challenge expiry, and method-specific
+ * validation. It does not prove that the challenge was issued by a particular
+ * server; hosts that issue challenges must verify that binding separately.
+ */
+export async function validateCredential<const methods extends readonly AnyServer[]>(
+  methods: methods,
+  input: string | Credential.Credential,
+): Promise<Validation<methods[number]>> {
+  const prepared = prepareCredential(methods, input)
+  if (!prepared.method.validate)
+    throw new Errors.VerificationFailedError({
+      details: { intent: prepared.method.intent, method: prepared.method.name },
+      reason: `${prepared.method.name}/${prepared.method.intent} does not support non-mutating credential validation`,
+    })
+  return prepared.method.validate({
+    credential: prepared.credential,
+    request: prepared.request,
+  } as never) as Promise<Validation<methods[number]>>
+}
+
+/**
+ * Re-validates and performs the terminal payment operation for a credential.
+ *
+ * This does not prove that the challenge was issued by a particular server;
+ * hosts that issue challenges must verify that binding separately.
+ */
+export async function broadcastCredential<const methods extends readonly AnyServer[]>(
+  methods: methods,
+  input: string | Credential.Credential,
+): Promise<Receipt.Receipt> {
+  const prepared = prepareCredential(methods, input)
+  const { method } = prepared
+
+  if (method.broadcast && method.validate)
+    await method.validate({ credential: prepared.credential, request: prepared.request } as never)
+
+  const broadcast = method.broadcast ?? method.verify
+  return broadcast({ credential: prepared.credential, request: prepared.request } as never)
+}
+
+/**
+ * Parses a submitted credential into the inputs required for method execution.
+ *
+ * Dispatch is based on the challenge method and intent. When more than one
+ * server method handles the same wire identity, session protocol details select
+ * the appropriate implementation. The helper then asserts challenge expiry and
+ * parses the method-specific credential payload before returning the selected
+ * method and the unmodified challenge request.
+ *
+ * This intentionally does not verify that the challenge was issued by a
+ * particular host, authorize the caller or requested resource, validate the
+ * method request, or invoke method lifecycle hooks. Hosts that issue challenges
+ * must verify their challenge binding before accepting the credential.
+ */
+function prepareCredential(
+  methods: readonly AnyServer[],
+  input: string | Credential.Credential,
+): {
+  credential: Credential.Credential
+  method: AnyServer
+  request: Record<string, unknown>
+} {
+  const credential = typeof input === 'string' ? Credential.deserialize(input) : input
+  const candidates = methods.filter(
+    (method) =>
+      method.name === credential.challenge.method && method.intent === credential.challenge.intent,
+  )
+  const method = selectServerMethod(candidates, credential.challenge)
+  if (!method)
+    throw new Errors.InvalidChallengeError({
+      id: credential.challenge.id,
+      reason: `no registered method for ${credential.challenge.method}/${credential.challenge.intent}`,
+    })
+
+  Expires.assert(credential.challenge.expires, credential.challenge.id)
+
+  let payload: unknown
+  try {
+    payload = method.schema.credential.payload.parse(credential.payload)
+  } catch (error) {
+    throw new Errors.InvalidPayloadError(error instanceof Error ? { reason: error.message } : {})
+  }
+
+  return {
+    credential: { ...credential, payload },
+    method,
+    request: credential.challenge.request,
+  }
+}
+
+/** @internal */
+export function selectServerMethod(
+  methods: readonly AnyServer[],
+  challenge: Challenge.Challenge,
+): AnyServer | undefined {
+  if (methods.length <= 1) return methods[0]
+  if (
+    challenge.method !== Constants.Methods.tempo ||
+    challenge.intent !== Constants.Intents.session
+  )
+    return methods[0]
+
+  const sessionProtocol = Constants.getMethodDetail(
+    challenge.request.methodDetails,
+    Constants.MethodDetailKeys.sessionProtocol,
+  )
+  if (sessionProtocol === undefined || sessionProtocol === Constants.SessionProtocols.v1)
+    return methods.find((method) => method.alias === 'sessionLegacy') ?? methods[0]
+  if (sessionProtocol === Constants.SessionProtocols.v2)
+    return methods.find((method) => method.alias === undefined) ?? methods[0]
+  return undefined
+}
+
 /**
  * Optional respond function for a server-side method.
  *
@@ -336,10 +543,22 @@ export function toServer<
     preflight,
     request,
     respond,
+    broadcast,
     stableBinding,
     transport,
+    validate,
     verify,
   } = options
+  const effectiveVerify =
+    verify ??
+    (async (parameters: VerifyContext<method>) => {
+      if (validate) await validate(parameters)
+      if (!broadcast)
+        throw new Errors.VerificationFailedError({
+          reason: `${method.name}/${method.intent} does not support credential broadcast`,
+        })
+      return broadcast(parameters)
+    })
   return {
     ...method,
     alias,
@@ -350,9 +569,11 @@ export function toServer<
     preflight,
     request,
     respond,
+    broadcast,
     stableBinding,
     transport,
-    verify,
+    validate,
+    verify: effectiveVerify,
   } as Server<method, defaults, transportOverride, extensions, toServer.Alias<options>>
 }
 
@@ -376,6 +597,21 @@ export declare namespace toServer {
     respond?: RespondFn<method> | undefined
     stableBinding?: StableBindingFn<method> | undefined
     transport?: transportOverride | Transport.AnyTransport | undefined
-    verify: VerifyFn<method>
-  }
+  } & (
+    | {
+        broadcast: BroadcastFn<method>
+        validate?: ValidateFn<method> | undefined
+        verify?: undefined
+      }
+    | {
+        broadcast?: undefined
+        validate?: undefined
+        /**
+         * @deprecated Use `validate` and `broadcast` for new methods. This
+         * combined hook may mutate payment state and cannot power a safe
+         * validation-only endpoint.
+         */
+        verify: VerifyFn<method>
+      }
+  )
 }

package/src/client/Mppx.test-d.ts

@@ -262,9 +262,9 @@ describe('fetch context', () => {
     type FetchInit = NonNullable<Parameters<typeof _mppx.fetch>[1]>
     type Context = NonNullable<FetchInit['context']>
 
-    // Context is a union of charge and session contexts.
-    // `account` exists on both; `autoSwap` only on charge.
+    // Context is a union of charge and session contexts; both support auto-swap.
     expectTypeOf<Context>().toHaveProperty('account')
-    expectTypeOf<Extract<Context, { autoSwap?: unknown }>>().toHaveProperty('autoSwap')
+    expectTypeOf<Context>().toHaveProperty('autoSwap')
+    expectTypeOf<Context['autoSwap']>().toEqualTypeOf<AutoSwap.resolve.Value | undefined>()
   })
 })

package/src/client/internal/Fetch.ts

@@ -6,6 +6,7 @@ import type { MaybePromise } from '../../internal/types.js'
 import type * as Method from '../../Method.js'
 import type * as z from '../../zod.js'
 import * as Transport from '../Transport.js'
+import * as MethodChallenge from './MethodChallenge.js'
 import * as MethodResponse from './MethodResponse.js'
 
 // We tag wrappers with a global symbol so we can recognize wrappers created by mppx,
@@ -241,9 +242,22 @@ export function from<const methods extends readonly Method.AnyClient[]>(
         mi = selected.method
         if (challenge.expires) Expires.assert(challenge.expires, challenge.id)
 
+        const paymentInput = resolvePaymentRetryInput(
+          response,
+          initialRequest.input,
+          initialRequest.input,
+        )
         const createCredential = memoizeCreateCredential(
-          (overrideContext?: AnyContextFor<methods>) =>
-            resolveCredential(selectedChallenge, selected.method, overrideContext ?? context),
+          async (overrideContext?: AnyContextFor<methods>) => {
+            const credentialContext = overrideContext ?? context
+            await MethodChallenge.handle(selected.method, {
+              challenge: selectedChallenge,
+              context: credentialContext,
+              fetch: baseFetch,
+              input: paymentInput,
+            })
+            return resolveCredential(selectedChallenge, selected.method, credentialContext)
+          },
         )
         const eventCredential = await events.emit(
           'challenge.received',
@@ -278,11 +292,6 @@ export function from<const methods extends readonly Method.AnyClient[]>(
           }),
         )
 
-        const paymentInput = resolvePaymentRetryInput(
-          response,
-          initialRequest.input,
-          initialRequest.input,
-        )
         response = await baseFetch(
           paymentInput,
           transport.setCredential(

package/src/client/internal/MethodChallenge.ts

@@ -0,0 +1,30 @@
+import type * as Challenge from '../../Challenge.js'
+import type { MaybePromise } from '../../internal/types.js'
+import type * as Method from '../../Method.js'
+
+const handlers = new WeakMap<Method.AnyClient, Handler>()
+
+/** Inputs available before a client method creates a challenge credential. */
+export type HandlerParameters = {
+  challenge: Challenge.Challenge
+  context?: unknown
+  fetch: typeof globalThis.fetch
+  input: RequestInfo | URL
+}
+
+/** Internal client-method challenge hook. */
+export type Handler = (parameters: HandlerParameters) => MaybePromise<void>
+
+/** Registers an internal challenge hook without changing the public method shape. */
+export function register<const method extends Method.AnyClient>(
+  method: method,
+  handler: Handler,
+): method {
+  handlers.set(method, handler)
+  return method
+}
+
+/** Runs method-specific work before creating a challenge credential. */
+export function handle(method: Method.AnyClient, parameters: HandlerParameters): Promise<void> {
+  return Promise.resolve(handlers.get(method)?.(parameters))
+}

package/src/server/Mppx.test-d.ts

@@ -223,6 +223,8 @@ describe('Mppx type tests', () => {
     const mppx = Mppx.create({ methods: [alphaMethod], realm, secretKey })
 
     expectTypeOf(mppx.verifyCredential).toBeFunction()
+    expectTypeOf(mppx.broadcastCredential).toBeFunction()
+    expectTypeOf(mppx.validateCredential).toBeFunction()
   })
 
   test('server events receive typed method context', () => {

package/src/server/Mppx.test.ts

@@ -4872,6 +4872,211 @@ describe('verifyCredential', () => {
     expect(verifyArgs).toBeDefined()
   })
 
+  test('validateCredential uses pure method validation without broadcast', async () => {
+    const calls: string[] = []
+    const splitServer = Method.toServer(mockCharge, {
+      async validate({ credential, request }) {
+        calls.push('validate')
+        return {
+          challenge: credential.challenge,
+          credential,
+          details: { token: credential.payload.token },
+          intent: 'charge',
+          method: 'alpha',
+          request,
+          source: credential.source,
+        }
+      },
+      async broadcast() {
+        calls.push('broadcast')
+        return mockReceipt('broadcast')
+      },
+    })
+    const mppx = Mppx.create({ methods: [splitServer], realm, secretKey })
+    const challenge = await mppx.challenge.alpha.charge(challengeOpts)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const validation = await mppx.validateCredential(credential)
+
+    expect(validation.details).toEqual({ token: 'valid' })
+    expect(calls).toEqual(['validate'])
+  })
+
+  test('broadcastCredential revalidates and uses method broadcast', async () => {
+    const calls: string[] = []
+    const splitServer = Method.toServer(mockCharge, {
+      async validate({ credential, request }) {
+        calls.push('validate')
+        return {
+          challenge: credential.challenge,
+          credential,
+          details: {},
+          intent: 'charge',
+          method: 'alpha',
+          request,
+          source: credential.source,
+        }
+      },
+      async broadcast() {
+        calls.push('broadcast')
+        return mockReceipt('broadcast')
+      },
+    })
+    const mppx = Mppx.create({ methods: [splitServer], realm, secretKey })
+    const challenge = await mppx.challenge.alpha.charge(challengeOpts)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const receipt = await mppx.broadcastCredential(credential)
+
+    expect(receipt.method).toBe('broadcast')
+    expect(calls).toEqual(['validate', 'broadcast'])
+  })
+
+  test('verifyCredential remains a legacy alias for broadcast', async () => {
+    const calls: string[] = []
+    const splitServer = Method.toServer(mockCharge, {
+      async validate({ credential, request }) {
+        calls.push('validate')
+        return {
+          challenge: credential.challenge,
+          credential,
+          details: {},
+          intent: 'charge',
+          method: 'alpha',
+          request,
+          source: credential.source,
+        }
+      },
+      async broadcast() {
+        calls.push('broadcast')
+        return mockReceipt('broadcast')
+      },
+    })
+    const mppx = Mppx.create({ methods: [splitServer], realm, secretKey })
+    const challenge = await mppx.challenge.alpha.charge(challengeOpts)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const receipt = await mppx.verifyCredential(credential)
+
+    expect(receipt.method).toBe('broadcast')
+    expect(calls).toEqual(['validate', 'broadcast'])
+  })
+
+  test('validateCredential rejects legacy-only methods without emitting payment failure', async () => {
+    const events: string[] = []
+    const mppx = Mppx.create({ methods: [alphaChargeServer], realm, secretKey })
+    mppx.onPaymentFailed((context) => {
+      events.push(context.error.name)
+    })
+    const challenge = await mppx.challenge.alpha.charge(challengeOpts)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    await expect(mppx.validateCredential(credential)).rejects.toThrow(
+      'does not support non-mutating credential validation',
+    )
+
+    expect(events).toEqual([])
+  })
+
+  test('validateCredential enforces supplied route requirements', async () => {
+    const splitServer = Method.toServer(mockCharge, {
+      async validate({ credential, request }) {
+        return {
+          challenge: credential.challenge,
+          credential,
+          details: { amount: request.amount },
+          intent: 'charge',
+          method: 'alpha',
+          request,
+          source: credential.source,
+        }
+      },
+      async broadcast() {
+        return mockReceipt('broadcast')
+      },
+    })
+    const mppx = Mppx.create({ methods: [splitServer], realm, secretKey })
+    const challenge = await mppx.challenge.alpha.charge(challengeOpts)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const validation = await mppx.validateCredential(credential, { request: challengeOpts })
+    expect(validation.details).toEqual({ amount: '1000' })
+
+    await expect(
+      mppx.validateCredential(credential, {
+        request: {
+          ...challengeOpts,
+          amount: '2000',
+        },
+      }),
+    ).rejects.toThrow('credential amount does not match this route')
+  })
+
+  test('broadcastCredential emits payment failure when split validation fails', async () => {
+    const calls: string[] = []
+    const events: string[] = []
+    const splitServer = Method.toServer(mockCharge, {
+      async validate() {
+        calls.push('validate')
+        throw new Errors.VerificationFailedError({ reason: 'risk denied' })
+      },
+      async broadcast() {
+        calls.push('broadcast')
+        return mockReceipt('broadcast')
+      },
+    })
+    const mppx = Mppx.create({ methods: [splitServer], realm, secretKey })
+    mppx.onPaymentFailed((context) => {
+      events.push(context.error.name)
+    })
+    const challenge = await mppx.challenge.alpha.charge(challengeOpts)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    await expect(mppx.broadcastCredential(credential)).rejects.toThrow('risk denied')
+
+    expect(calls).toEqual(['validate'])
+    expect(events).toEqual(['VerificationFailedError'])
+  })
+
+  test('route handlers revalidate before broadcast for split methods', async () => {
+    const calls: string[] = []
+    const splitServer = Method.toServer(mockCharge, {
+      async validate({ credential, request }) {
+        calls.push('validate')
+        return {
+          challenge: credential.challenge,
+          credential,
+          details: {},
+          intent: 'charge',
+          method: 'alpha',
+          request,
+          source: credential.source,
+        }
+      },
+      async broadcast() {
+        calls.push('broadcast')
+        return mockReceipt('broadcast')
+      },
+    })
+    const mppx = Mppx.create({ methods: [splitServer], realm, secretKey })
+    const firstResult = await mppx.charge(challengeOpts)(
+      new Request('https://api.example.com/resource'),
+    )
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+    const result = await mppx.charge(challengeOpts)(
+      new Request('https://api.example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(200)
+    expect(calls).toEqual(['validate', 'broadcast'])
+  })
+
   test('verifies a parsed Credential object (charge)', async () => {
     verifyArgs = undefined
     const mppx = Mppx.create({