Identity.from

Creates a verifier from your identity lookup. It runs before issuing a payment Challenge or accepting a payment Credential, so identity failures stop payment processing.

Return an authenticated value to continue; undefined or null rejects the request with 401. The optional challenge headers accompany identity rejections, not the payment 402.

Usage

import * as Identity from 'mppx/identity'
import { Mppx, tempo } from 'mppx/server'
 
declare const customers: ReadonlyMap<string, { customerId: string }>
 
const customer = Identity.from({
  challenge: { 'WWW-Authenticate': 'ApiKey' },
  verify(request) {
    const key = request.headers.get('X-Api-Key')
    if (!key) return undefined
    const identity = customers.get(key)
    if (!identity) throw new Identity.Rejection('Unknown API key.', { code: 403 })
    return identity
  },
})
const mppx = Mppx.create({ methods: [tempo.charge()] })
 
export async function handler(request: Request) {
  const result = await mppx.charge({ amount: '0.05', identity: [customer] })(request)
  if (result.status === 402) return result.challenge
  return result.withReceipt(Response.json(result.identity?.get(customer)))
}

The verifier runs before the server issues a payment Challenge or settles a Credential. It doesn't authenticate a returned value for you—validate the API key, session, or provider response inside verify.

Return type

Identity.Verifier<value> with stage: 'request'. Read the returned identity with result.identity?.get(verifier) after a successful payment result.

Other values, including false and 0, count as identities. Return undefined or null to signal no identity.

Parameters

challenge (optional)

• Type: HeadersInit

Headers sent for missing and rejected identities. No headers by default. This is a static header set, not a payment-stage challenge hook.

verify

• Type: (request: Request) => value | null | undefined | Promise<value | null | undefined>

Look up and authenticate the caller. Throw Identity.Rejection for a known rejection; let operational errors propagate.

Accept alternative identities

Use identity: [Identity.anyOf(email, customer)] to accept either an email verifier or your lookup. Every member runs; the first valid member in list order wins. If none succeeds, a presented but invalid identity takes precedence over a missing identity. The results lookup includes the winning member, so result.identity?.get(customer) works when it wins. A plain list such as identity: [email, customer] requires both.