mppx 0.8.12 → 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/cli/account.ts

@@ -5,6 +5,8 @@ import * as path from 'node:path'
 
 import { Errors } from 'incur'
 
+import { isTempoAccount } from './utils.js'
+
 const SERVICE_NAME = 'mppx'
 const defaultCommandTimeoutMs = 10_000
 
@@ -203,6 +205,48 @@ export function createKeychain(account = 'main') {
   }
 }
 
+/** Resolves a local CLI signer together with its durable account reference. */
+export async function resolveLocalAccount(name?: string) {
+  const { privateKeyToAccount } = await import('viem/accounts')
+
+  const envKey = process.env.MPPX_PRIVATE_KEY?.trim()
+  if (envKey)
+    return {
+      account: privateKeyToAccount(envKey as `0x${string}`),
+      source: 'environment' as const,
+    }
+
+  const accountName = resolveAccountName(name)
+  const key = await createKeychain(accountName).get()
+  if (key)
+    return {
+      account: privateKeyToAccount(key as `0x${string}`),
+      accountName,
+      source: 'keychain' as const,
+    }
+
+  throw new Error(`Account "${accountName}" not found.`)
+}
+
+/** Resolves an account supported by persistent CLI sessions. */
+export async function resolvePersistentAccount(name?: string) {
+  const accountName = resolveAccountName(name)
+  if (!process.env.MPPX_PRIVATE_KEY?.trim() && isTempoAccount(accountName))
+    throw new Errors.IncurError({
+      code: 'UNSUPPORTED_ACCOUNT',
+      message: 'Persistent sessions require an mppx account or MPPX_PRIVATE_KEY.',
+      exitCode: 2,
+    })
+  return resolveLocalAccount(name).catch((cause: unknown) => {
+    throw new Errors.IncurError({
+      code: 'ACCOUNT_NOT_FOUND',
+      message: cause instanceof Error ? cause.message : 'No account found.',
+      exitCode: 69,
+      ...(cause instanceof Error && { cause }),
+    })
+  })
+}
+
 /**
  * Resolve a CLI account to a viem `LocalAccount`.
  *
@@ -221,14 +265,5 @@ export function createKeychain(account = 'main') {
  * ```
  */
 export async function resolveAccount(name?: string) {
-  const { privateKeyToAccount } = await import('viem/accounts')
-
-  const envKey = process.env.MPPX_PRIVATE_KEY?.trim()
-  if (envKey) return privateKeyToAccount(envKey as `0x${string}`)
-
-  const accountName = resolveAccountName(name)
-  const key = await createKeychain(accountName).get()
-  if (key) return privateKeyToAccount(key as `0x${string}`)
-
-  throw new Error(`Account "${accountName}" not found.`)
+  return (await resolveLocalAccount(name)).account
 }