mppx 0.4.11 → 0.5.0

package/src/server/Mppx.ts

@@ -153,7 +153,7 @@ export function create<
   const transport extends Transport.AnyTransport = Transport.Http,
 >(config: create.Config<methods, transport>): Mppx<methods, transport> {
   const {
-    realm = Env.get('realm') ?? 'MPP Payment',
+    realm = Env.get('realm'),
     secretKey = Env.get('secretKey'),
     transport = Transport.http() as transport,
   } = config
@@ -222,7 +222,7 @@ export function create<
   return {
     methods,
     compose: composeFn,
-    realm: realm as string,
+    realm: realm as string | undefined,
     transport,
     ...handlers,
   } as never
@@ -235,7 +235,7 @@ export declare namespace create {
   > = {
     /** Array of configured methods. @example [tempo()] */
     methods: methods
-    /** Server realm (e.g., hostname). Auto-detected from environment variables (`MPP_REALM`, `VERCEL_URL`, `RAILWAY_PUBLIC_DOMAIN`, `RENDER_EXTERNAL_HOSTNAME`, `HOST`, `HOSTNAME`), falling back to `"localhost"`. */
+    /** Server realm (e.g., hostname). Resolution order: explicit value > env vars (`MPP_REALM`, `FLY_APP_NAME`, `VERCEL_URL`, etc.) > request URL hostname > `"MPP Payment"`. */
     realm?: string | undefined
     /** Secret key for HMAC-bound challenge IDs for stateless verification. Auto-detected from `MPP_SECRET_KEY` environment variable. Throws if neither provided nor set. */
     secretKey?: string | undefined
@@ -283,6 +283,9 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
             : merged
         ) as never
 
+        // Resolve realm: explicit > env var > request Host header.
+        const effectiveRealm = realm ?? resolveRealmFromRequest(input)
+
         // Recompute challenge from options. The HMAC-bound ID means we don't need to
         // store challenges server-side—if the client echoes back a credential with
         // a matching ID, we know it was issued by us with these exact parameters.
@@ -290,7 +293,7 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
           description,
           expires,
           meta,
-          realm,
+          realm: effectiveRealm,
           request,
           secretKey,
         })
@@ -389,17 +392,40 @@ function createMethodFn(parameters: createMethodFn.Parameters): createMethodFn.R
                 return { challenge: response, status: 402 }
               }
             }
+
+            // Compare payment-relevant methodDetails fields (memo, splits).
+            // These are excluded from the top-level field check above but
+            // affect verification semantics — a credential issued for a
+            // no-splits route must not be accepted on a splits route.
+            for (const field of ['memo', 'splits'] as const) {
+              const routeVal = routeDetails[field]
+              const echoedVal = echoedDetails[field]
+              if (
+                routeVal !== undefined &&
+                JSON.stringify(routeVal) !== JSON.stringify(echoedVal)
+              ) {
+                const response = await transport.respondChallenge({
+                  challenge,
+                  input,
+                  error: new Errors.InvalidChallengeError({
+                    id: credential.challenge.id,
+                    reason: `credential ${field} does not match this route's requirements`,
+                  }),
+                })
+                return { challenge: response, status: 402 }
+              }
+            }
           }
         }
 
-        // Reject expired credentials
-        if (credential.challenge.expires && new Date(credential.challenge.expires) < new Date()) {
+        // Reject credentials without expires (fail-closed) or with expired timestamp
+        try {
+          Expires.assert(credential.challenge.expires, credential.challenge.id)
+        } catch (error) {
           const response = await transport.respondChallenge({
             challenge,
             input,
-            error: new Errors.PaymentExpiredError({
-              expires: credential.challenge.expires,
-            }),
+            error: error as Errors.PaymentError,
           })
           return { challenge: response, status: 402 }
         }
@@ -483,7 +509,7 @@ declare namespace createMethodFn {
   > = {
     defaults?: defaults
     method: method
-    realm: string
+    realm: string | undefined
     request?: Method.RequestFn<method>
     respond?: Method.RespondFn<method>
     secretKey: string
@@ -498,6 +524,34 @@ declare namespace createMethodFn {
   > = MethodFn<method, transport, defaults>
 }
 
+const defaultRealm = 'MPP Payment'
+const Warnings = {
+  realmFallback: 'realm-fallback',
+} as const
+
+const _warned = new Set<string>()
+function warnOnce(key: string, message: string) {
+  if (_warned.has(key)) return
+  _warned.add(key)
+  console.warn(`[mppx] ${message}`)
+}
+
+/** Extracts hostname from the request URL, falling back to a default. */
+function resolveRealmFromRequest(input: unknown): string {
+  try {
+    const url = typeof (input as any)?.url === 'string' ? (input as any).url : undefined
+    if (url) {
+      const { protocol, hostname } = new URL(url)
+      if (/^https?:$/.test(protocol) && hostname) return hostname
+    }
+  } catch {}
+  warnOnce(
+    Warnings.realmFallback,
+    `Could not auto-detect realm from request. Falling back to "${defaultRealm}". Set \`realm\` in Mppx.create() or the MPP_REALM env var.`,
+  )
+  return defaultRealm
+}
+
 export type MethodFn<
   method extends Method.Method,
   transport extends Transport.AnyTransport,

package/src/stripe/server/Charge.ts

@@ -1,9 +1,6 @@
 import type * as Credential from '../../Credential.js'
-import {
-  PaymentActionRequiredError,
-  PaymentExpiredError,
-  VerificationFailedError,
-} from '../../Errors.js'
+import { PaymentActionRequiredError, VerificationFailedError } from '../../Errors.js'
+import * as Expires from '../../Expires.js'
 import type { LooseOmit, OneOf } from '../../internal/types.js'
 import * as Method from '../../Method.js'
 import type { StripeClient } from '../internal/types.js'
@@ -66,8 +63,7 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
       const { challenge } = credential
       const { request } = challenge
 
-      if (challenge.expires && new Date(challenge.expires) < new Date())
-        throw new PaymentExpiredError({ expires: challenge.expires })
+      Expires.assert(challenge.expires, challenge.id)
 
       const parsed = Methods.charge.schema.credential.payload.safeParse(credential.payload)
       if (!parsed.success) throw new Error('Invalid credential payload: missing or malformed spt')

package/src/tempo/Methods.test.ts

@@ -51,6 +51,111 @@ describe('charge', () => {
     expect(result.success).toBe(true)
   })
 
+  test('schema: validates request with splits', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      splits: [
+        {
+          amount: '0.25',
+          recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        },
+        {
+          amount: '0.1',
+          memo: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+          recipient: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+        },
+      ],
+    })
+    expect(result.success).toBe(true)
+    if (!result.success) return
+
+    expect(result.data.methodDetails?.splits).toEqual([
+      {
+        amount: '250000',
+        recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+      },
+      {
+        amount: '100000',
+        memo: '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
+        recipient: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+      },
+    ])
+  })
+
+  test('schema: rejects empty splits', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      splits: [],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  test('schema: rejects more than 10 splits', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '11',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      splits: Array.from({ length: 11 }, (_, index) => ({
+        amount: '0.1',
+        recipient: `0x${(index + 1).toString(16).padStart(40, '0')}`,
+      })),
+    })
+    expect(result.success).toBe(false)
+  })
+
+  test('schema: rejects split totals greater than or equal to amount', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '1',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      splits: [
+        {
+          amount: '0.5',
+          recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        },
+        {
+          amount: '0.5',
+          recipient: '0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb',
+        },
+      ],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  test('schema: rejects zero-amount with splits', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '0',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      splits: [
+        {
+          amount: '0.1',
+          recipient: '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd',
+        },
+      ],
+    })
+    expect(result.success).toBe(false)
+  })
+
+  test('schema: accepts zero-amount without splits', () => {
+    const result = Methods.charge.schema.request.safeParse({
+      amount: '0',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+    })
+    expect(result.success).toBe(true)
+  })
+
   test('schema: rejects invalid request', () => {
     const result = Methods.charge.schema.request.safeParse({
       amount: '1',

package/src/tempo/Methods.ts

@@ -1,9 +1,18 @@
-import type { Account } from 'viem'
+import type { Account, Address } from 'viem'
 import { parseUnits } from 'viem'
 
 import * as Method from '../Method.js'
 import * as z from '../zod.js'
 
+const split = z.object({
+  amount: z.amount(),
+  memo: z.optional(z.hash()),
+  recipient: z.pipe(
+    z.string(),
+    z.transform((v) => v as Address),
+  ),
+})
+
 /**
  * Tempo charge intent for one-time TIP-20 token transfers.
  *
@@ -17,34 +26,62 @@ export const charge = Method.from({
       payload: z.discriminatedUnion('type', [
         z.object({ hash: z.hash(), type: z.literal('hash') }),
         z.object({ signature: z.signature(), type: z.literal('transaction') }),
+        z.object({ signature: z.signature(), type: z.literal('proof') }),
       ]),
     },
     request: z.pipe(
-      z.object({
-        amount: z.amount(),
-        chainId: z.optional(z.number()),
-        currency: z.string(),
-        decimals: z.number(),
-        description: z.optional(z.string()),
-        externalId: z.optional(z.string()),
-        feePayer: z.optional(
-          z.pipe(
-            z.union([z.boolean(), z.custom<Account>()]),
-            z.transform((v): boolean => (typeof v === 'object' ? true : v)),
+      z
+        .object({
+          amount: z.amount(),
+          chainId: z.optional(z.number()),
+          currency: z.string(),
+          decimals: z.number(),
+          description: z.optional(z.string()),
+          externalId: z.optional(z.string()),
+          feePayer: z.optional(
+            z.pipe(
+              z.union([z.boolean(), z.custom<Account>()]),
+              z.transform((v): boolean => (typeof v === 'object' ? true : v)),
+            ),
           ),
+          memo: z.optional(z.hash()),
+          recipient: z.optional(z.string()),
+          splits: z.optional(z.array(split).check(z.minLength(1), z.maxLength(10))),
+        })
+        .check(
+          z.refine(({ amount, decimals, splits }) => {
+            if (!splits) return true
+
+            const totalAmount = parseUnits(amount, decimals)
+            const splitTotal = splits.reduce(
+              (sum, split) => sum + parseUnits(split.amount, decimals),
+              0n,
+            )
+
+            return (
+              splits.every((split) => parseUnits(split.amount, decimals) > 0n) &&
+              splitTotal < totalAmount
+            )
+          }, 'Invalid splits'),
         ),
-        memo: z.optional(z.hash()),
-        recipient: z.optional(z.string()),
-      }),
-      z.transform(({ amount, chainId, decimals, feePayer, memo, ...rest }) => ({
+      z.transform(({ amount, chainId, decimals, feePayer, memo, splits, ...rest }) => ({
         ...rest,
         amount: parseUnits(amount, decimals).toString(),
-        ...(chainId !== undefined || feePayer !== undefined || memo !== undefined
+        ...(chainId !== undefined ||
+        feePayer !== undefined ||
+        memo !== undefined ||
+        splits !== undefined
           ? {
               methodDetails: {
                 ...(chainId !== undefined && { chainId }),
                 ...(feePayer !== undefined && { feePayer }),
                 ...(memo !== undefined && { memo }),
+                ...(splits !== undefined && {
+                  splits: splits.map((split) => ({
+                    ...split,
+                    amount: parseUnits(split.amount, decimals).toString(),
+                  })),
+                }),
               },
             }
           : {}),

package/src/tempo/client/Charge.ts

@@ -1,6 +1,11 @@
 import type * as Hex from 'ox/Hex'
 import type { Address } from 'viem'
-import { prepareTransactionRequest, sendCallsSync, signTransaction } from 'viem/actions'
+import {
+  prepareTransactionRequest,
+  sendCallsSync,
+  signTypedData,
+  signTransaction,
+} from 'viem/actions'
 import { tempo as tempo_chain } from 'viem/chains'
 import { Actions } from 'viem/tempo'
 
@@ -11,7 +16,9 @@ import * as Client from '../../viem/Client.js'
 import * as z from '../../zod.js'
 import * as Attribution from '../Attribution.js'
 import * as AutoSwap from '../internal/auto-swap.js'
+import * as Charge_internal from '../internal/charge.js'
 import * as defaults from '../internal/defaults.js'
+import * as Proof from '../internal/proof.js'
 import * as Methods from '../Methods.js'
 
 /**
@@ -48,24 +55,60 @@ export function charge(parameters: charge.Parameters = {}) {
       const client = await getClient({ chainId })
       const account = getAccount(client, context)
 
+      const { request } = challenge
+      const { amount, methodDetails } = request
+
+      // Zero-amount: sign EIP-712 typed data instead of creating a transaction.
+      if (BigInt(amount) === 0n) {
+        const signature = await signTypedData(client, {
+          account,
+          domain: Proof.domain(chainId!),
+          types: Proof.types,
+          primaryType: 'Proof',
+          message: Proof.message(challenge.id),
+        })
+        return Credential.serialize({
+          challenge,
+          payload: { signature, type: 'proof' },
+          source: Proof.proofSource({ address: account.address, chainId: chainId! }),
+        })
+      }
+
       const mode =
         context?.mode ?? parameters.mode ?? (account.type === 'json-rpc' ? 'push' : 'pull')
 
-      const { request } = challenge
-      const { amount, methodDetails } = request
       const currency = request.currency as Address
-      const recipient = request.recipient as Address
+
+      if (parameters.expectedRecipients) {
+        const allowed = new Set(parameters.expectedRecipients.map((a) => a.toLowerCase()))
+        const splits = methodDetails?.splits as readonly { recipient: string }[] | undefined
+        if (splits) {
+          for (const split of splits) {
+            if (!allowed.has(split.recipient.toLowerCase()))
+              throw new Error(`Unexpected split recipient: ${split.recipient}`)
+          }
+        }
+      }
 
       const memo = methodDetails?.memo
         ? (methodDetails.memo as Hex.Hex)
         : Attribution.encode({ serverId: challenge.realm, clientId })
-
-      const transferCall = Actions.token.transfer.call({
-        amount: BigInt(amount),
-        memo,
-        to: recipient,
-        token: currency,
+      const transfers = Charge_internal.getTransfers({
+        amount,
+        methodDetails: {
+          ...methodDetails,
+          memo,
+        },
+        recipient: request.recipient as Address,
       })
+      const transferCalls = transfers.map((transfer) =>
+        Actions.token.transfer.call({
+          amount: BigInt(transfer.amount),
+          ...(transfer.memo && { memo: transfer.memo as Hex.Hex }),
+          to: transfer.recipient as Address,
+          token: currency,
+        }),
+      )
 
       const autoSwap = AutoSwap.resolve(
         context?.autoSwap ?? parameters.autoSwap,
@@ -82,7 +125,14 @@ export function charge(parameters: charge.Parameters = {}) {
           })
         : undefined
 
-      const calls = [...(swapCalls ?? []), transferCall]
+      const calls = [...(swapCalls ?? []), ...transferCalls]
+
+      const validBefore = (() => {
+        const defaultExpiry = Math.floor(Date.now() / 1000) + 25
+        if (!challenge.expires) return defaultExpiry
+        const challengeExpiry = Math.floor(new Date(challenge.expires).getTime() / 1000)
+        return Math.min(defaultExpiry, challengeExpiry)
+      })()
 
       if (mode === 'push') {
         const { receipts } = await sendCallsSync(client, {
@@ -104,6 +154,7 @@ export function charge(parameters: charge.Parameters = {}) {
         calls,
         ...(methodDetails?.feePayer && { feePayer: true }),
         nonceKey: 'expiring',
+        validBefore,
       } as never)
       // FIXME: figure out gas estimation issue for fee payer tx
       prepared.gas = prepared.gas! + 5_000n
@@ -131,6 +182,11 @@ export declare namespace charge {
     autoSwap?: AutoSwap | undefined
     /** Client identifier used to derive the client fingerprint in attribution memos. */
     clientId?: string | undefined
+    /**
+     * Allowlist of expected split recipient addresses. When set, the client
+     * rejects any challenge whose split recipients are not in this list.
+     */
+    expectedRecipients?: readonly Address[] | undefined
     /**
      * Controls how the charge transaction is submitted.
      *

package/src/tempo/internal/account.ts

@@ -33,18 +33,11 @@ export function resolve(parameters: resolve.Parameters) {
 }
 
 export declare namespace resolve {
-  type Parameters = { recipient?: Address | undefined } & (
-    | {
-        /** Account that performs payment operations. */
-        account?: Account | undefined
-        /** When true, the account also sponsors (pays) transaction fees. */
-        feePayer?: true | undefined
-      }
-    | {
-        /** Address that receives payment. */
-        account?: Address | undefined
-        /** Optional fee payer account or fee payer URL for covering transaction fees. */
-        feePayer?: Account | string | undefined
-      }
-  )
+  type Parameters = {
+    recipient?: Address | undefined
+    /** Account or address that performs payment operations / receives payment. */
+    account?: Account | Address | undefined
+    /** When `true`, the account also sponsors fees. An `Account` object or URL string can also be provided as a dedicated fee payer. */
+    feePayer?: Account | string | true | undefined
+  }
 }

package/src/tempo/internal/charge.test.ts

@@ -0,0 +1,66 @@
+import type { Address } from 'viem'
+import { describe, expect, test } from 'vp/test'
+
+import { getTransfers } from './charge.js'
+
+const recipient = '0x1234567890abcdef1234567890abcdef12345678' as Address
+
+describe('getTransfers', () => {
+  test('returns single transfer when no splits', () => {
+    const transfers = getTransfers({ amount: '100', recipient })
+    expect(transfers).toEqual([{ amount: '100', memo: undefined, recipient }])
+  })
+
+  test('splits amount between primary and split recipients', () => {
+    const splitRecipient = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' as Address
+    const transfers = getTransfers({
+      amount: '100',
+      methodDetails: { splits: [{ amount: '30', recipient: splitRecipient }] },
+      recipient,
+    })
+    expect(transfers).toHaveLength(2)
+    expect(transfers[0]!.amount).toBe('70')
+    expect(transfers[0]!.recipient).toBe(recipient)
+    expect(transfers[1]!.amount).toBe('30')
+    expect(transfers[1]!.recipient).toBe(splitRecipient)
+  })
+
+  test('throws when amount is zero with no splits', () => {
+    expect(() => getTransfers({ amount: '0', recipient })).toThrow(
+      'split total must be less than total amount',
+    )
+  })
+
+  test('throws when amount is zero with splits', () => {
+    const splitRecipient = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' as Address
+    expect(() =>
+      getTransfers({
+        amount: '0',
+        methodDetails: { splits: [{ amount: '0', recipient: splitRecipient }] },
+        recipient,
+      }),
+    ).toThrow()
+  })
+
+  test('throws when split total equals amount', () => {
+    const splitRecipient = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' as Address
+    expect(() =>
+      getTransfers({
+        amount: '100',
+        methodDetails: { splits: [{ amount: '100', recipient: splitRecipient }] },
+        recipient,
+      }),
+    ).toThrow('split total must be less than total amount')
+  })
+
+  test('throws when split total exceeds amount', () => {
+    const splitRecipient = '0xabcdefabcdefabcdefabcdefabcdefabcdefabcd' as Address
+    expect(() =>
+      getTransfers({
+        amount: '100',
+        methodDetails: { splits: [{ amount: '200', recipient: splitRecipient }] },
+        recipient,
+      }),
+    ).toThrow('split total must be less than total amount')
+  })
+})

package/src/tempo/internal/charge.ts

@@ -0,0 +1,43 @@
+import type { Address } from 'viem'
+
+export type Split = {
+  amount: string
+  memo?: string | undefined
+  recipient: Address
+}
+
+export type Transfer = {
+  amount: string
+  memo?: string | undefined
+  recipient: Address
+}
+
+export function getTransfers(request: {
+  amount: string
+  methodDetails?: { memo?: string | undefined; splits?: readonly Split[] | undefined }
+  recipient: Address
+}): Transfer[] {
+  const totalAmount = BigInt(request.amount)
+  const splits = request.methodDetails?.splits ?? []
+
+  const splitTotal = splits.reduce((sum, split) => sum + BigInt(split.amount), 0n)
+  if (splitTotal >= totalAmount)
+    throw new Error('Invalid charge request: split total must be less than total amount.')
+
+  const primaryAmount = totalAmount - splitTotal
+  if (primaryAmount <= 0n)
+    throw new Error('Invalid charge request: primary transfer amount must be positive.')
+
+  return [
+    {
+      amount: primaryAmount.toString(),
+      memo: request.methodDetails?.memo,
+      recipient: request.recipient,
+    },
+    ...splits.map((split) => ({
+      amount: split.amount,
+      memo: split.memo,
+      recipient: split.recipient,
+    })),
+  ]
+}