mppx 0.4.10 → 0.4.12

package/src/server/Mppx.test.ts

@@ -1567,6 +1567,77 @@ describe('cross-route credential replay via scope binding flaw', () => {
     // The result should be 200 (matched to cheap), not routed to expensive.
     expect(result.status).toBe(200)
   })
+
+  test('rejects no-splits credential replayed at splits route', async () => {
+    // Method whose schema transform moves splits into methodDetails.
+    const splitsMethod = Method.from({
+      name: 'mock',
+      intent: 'charge',
+      schema: {
+        credential: { payload: z.object({ token: z.string() }) },
+        request: z.pipe(
+          z.object({
+            amount: z.string(),
+            currency: z.string(),
+            decimals: z.number(),
+            recipient: z.string(),
+            splits: z.optional(z.array(z.object({ amount: z.string(), recipient: z.string() }))),
+          }),
+          z.transform(({ amount, currency, decimals, recipient, splits }) => ({
+            methodDetails: {
+              amount: String(Number(amount) * 10 ** decimals),
+              currency,
+              recipient,
+              ...(splits && { splits }),
+            },
+          })),
+        ),
+      },
+    })
+
+    const splitsServerMethod = Method.toServer(splitsMethod, {
+      async verify() {
+        return mockReceipt()
+      },
+    })
+
+    const handler = Mppx.create({ methods: [splitsServerMethod], realm, secretKey })
+
+    // Get a challenge from a route with no splits
+    const noSplitsHandle = handler.charge({
+      amount: '1',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+    const noSplitsResult = await noSplitsHandle(new Request('https://example.com/no-splits'))
+    expect(noSplitsResult.status).toBe(402)
+    if (noSplitsResult.status !== 402) throw new Error()
+
+    const noSplitsChallenge = Challenge.fromResponse(noSplitsResult.challenge)
+    const credential = Credential.from({
+      challenge: noSplitsChallenge,
+      payload: { token: 'valid' },
+    })
+
+    // Present at a route that requires splits
+    const splitsHandle = handler.charge({
+      amount: '1',
+      currency: '0x0000000000000000000000000000000000000001',
+      decimals: 6,
+      expires: new Date(Date.now() + 60_000).toISOString(),
+      recipient: '0x0000000000000000000000000000000000000002',
+      splits: [{ amount: '0.2', recipient: '0x0000000000000000000000000000000000000003' }],
+    })
+    const result = await splitsHandle(
+      new Request('https://example.com/with-splits', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(result.status).toBe(402)
+  })
 })
 
 describe('withReceipt', () => {
@@ -1741,3 +1812,219 @@ describe('withReceipt', () => {
     server.close()
   })
 })
+
+describe('realm auto-detection', () => {
+  beforeEach(() => {
+    // Clear all env vars that Env.get('realm') probes so realm falls through to request detection
+    for (const name of [
+      'MPP_REALM',
+      'FLY_APP_NAME',
+      'HEROKU_APP_NAME',
+      'RAILWAY_PUBLIC_DOMAIN',
+      'RENDER_EXTERNAL_HOSTNAME',
+      'VERCEL_URL',
+      'WEBSITE_HOSTNAME',
+    ])
+      vi.stubEnv(name, '')
+  })
+
+  afterEach(() => {
+    vi.unstubAllEnvs()
+  })
+
+  const mockMethod = Method.toServer(
+    Method.from({
+      name: 'mock',
+      intent: 'charge',
+      schema: {
+        credential: { payload: z.object({ token: z.string() }) },
+        request: z.object({ amount: z.string(), currency: z.string(), recipient: z.string() }),
+      },
+    }),
+    {
+      async verify() {
+        return {
+          method: 'mock',
+          reference: 'ref',
+          status: 'success' as const,
+          timestamp: new Date().toISOString(),
+        }
+      },
+    },
+  )
+
+  test.each([
+    { url: 'https://mpp.dev/resource', expected: 'mpp.dev' },
+    { url: 'https://api.example.com/v1/resource', expected: 'api.example.com' },
+    { url: 'https://localhost:8787/resource', expected: 'localhost' },
+    { url: 'https://MPP.DEV/resource', expected: 'mpp.dev' },
+    { url: 'http://staging.mpp.dev:3000/api', expected: 'staging.mpp.dev' },
+  ])('derives realm "$expected" from $url', async ({ url, expected }) => {
+    const handler = Mppx.create({ methods: [mockMethod], secretKey })
+
+    const result = await handler.charge({
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    })(new Request(url))
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    expect(challenge.realm).toBe(expected)
+  })
+
+  test('credential verifies across different casing of same host', async () => {
+    const handler = Mppx.create({ methods: [mockMethod], secretKey })
+
+    const chargeOpts = {
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    }
+
+    // Get challenge with uppercase host
+    const result = await handler.charge(chargeOpts)(new Request('https://MPP.DEV/resource'))
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    // Verify with lowercase host — should match since both normalize
+    const verifyResult = await handler.charge(chargeOpts)(
+      new Request('https://mpp.dev/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(verifyResult.status).toBe(200)
+  })
+
+  test('explicit realm takes precedence over request url', async () => {
+    const handler = Mppx.create({ methods: [mockMethod], realm: 'explicit.example.com', secretKey })
+
+    const request = new Request('https://other.example.com/resource')
+    const result = await handler.charge({
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    })(request)
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    expect(challenge.realm).toBe('explicit.example.com')
+  })
+
+  test('challenge and verification use same auto-detected realm', async () => {
+    const handler = Mppx.create({ methods: [mockMethod], secretKey })
+
+    const url = 'https://mpp.dev/resource'
+
+    // Get challenge
+    const result = await handler.charge({
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    })(new Request(url))
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    // Replay with credential from same host — should verify
+    const verifyResult = await handler.charge({
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    })(new Request(url, { headers: { Authorization: Credential.serialize(credential) } }))
+
+    expect(verifyResult.status).toBe(200)
+  })
+
+  test('credential from one host rejected at different host', async () => {
+    const handler = Mppx.create({ methods: [mockMethod], secretKey })
+
+    // Get challenge from host A
+    const result = await handler.charge({
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    })(new Request('https://host-a.example.com/resource'))
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    // Present at host B — realm mismatch should reject
+    const verifyResult = await handler.charge({
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    })(
+      new Request('https://host-b.example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(verifyResult.status).toBe(402)
+  })
+
+  test('realm undefined on handler when not explicitly set', () => {
+    const handler = Mppx.create({ methods: [mockMethod], secretKey })
+    expect(handler.realm).toBeUndefined()
+  })
+
+  test('falls back to default realm when input has no url', async () => {
+    const handler = Mppx.create({ methods: [mockMethod], secretKey })
+    const handle = handler.charge({
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    })
+
+    // Simulate a non-HTTP input with no .url — should warn and use fallback
+    const result = await handle({} as any)
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+    const challenge = Challenge.fromResponse(result.challenge)
+    expect(challenge.realm).toBe('MPP Payment')
+  })
+
+  test('cross-host rejection reports realm mismatch', async () => {
+    const handler = Mppx.create({ methods: [mockMethod], secretKey })
+
+    const result = await handler.charge({
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    })(new Request('https://host-a.example.com/resource'))
+
+    expect(result.status).toBe(402)
+    if (result.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(result.challenge)
+    const credential = Credential.from({ challenge, payload: { token: 'valid' } })
+
+    const verifyResult = await handler.charge({
+      amount: '100',
+      currency: '0x0000000000000000000000000000000000000001',
+      recipient: '0x0000000000000000000000000000000000000002',
+    })(
+      new Request('https://host-b.example.com/resource', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+
+    expect(verifyResult.status).toBe(402)
+    if (verifyResult.status !== 402) throw new Error()
+    const body = (await verifyResult.challenge.json()) as { detail: string }
+    expect(body.detail).toContain('realm')
+  })
+})

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,6 +392,29 @@ 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 }
+              }
+            }
           }
         }
 
@@ -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/internal/types.ts

@@ -6,7 +6,11 @@
  */
 export type StripeClient = {
   paymentIntents: {
-    create(...args: any[]): Promise<{ id: string; status: string }>
+    create(...args: any[]): Promise<{
+      id: string
+      status: string
+      lastResponse?: { headers?: Record<string, string> }
+    }>
   }
 }
 

package/src/stripe/server/Charge.test.ts

@@ -16,9 +16,15 @@ function createMockStripeClient(
   overrides?: Partial<{ status: string; id: string; throws: boolean }>,
 ): { client: StripeClient; create: ReturnType<typeof vi.fn> } {
   const { status = 'succeeded', id = 'pi_mock_123', throws = false } = overrides ?? {}
+  let callCount = 0
   const create = vi.fn(async () => {
     if (throws) throw new Error('Stripe API error')
-    return { id, status }
+    callCount++
+    return {
+      id,
+      status,
+      ...(callCount > 1 ? { lastResponse: { headers: { 'idempotent-replayed': 'true' } } } : {}),
+    }
   })
   return {
     client: { paymentIntents: { create } },
@@ -196,6 +202,51 @@ describe('stripe.charge with client', () => {
     expect(body.detail).toContain('requires action')
   })
 
+  test('behavior: rejects replayed credential', async () => {
+    const { client } = createMockStripeClient()
+
+    const server = Mppx.create({
+      methods: [
+        stripe.charge({
+          client,
+          networkId: 'internal',
+          paymentMethodTypes: ['card'],
+        }),
+      ],
+      realm,
+      secretKey,
+    })
+
+    const handle = server.charge({ amount: '1', currency: 'usd', decimals: 2 })
+
+    // First request: get challenge
+    const firstResult = await handle(new Request('https://example.com'))
+    expect(firstResult.status).toBe(402)
+    if (firstResult.status !== 402) throw new Error()
+
+    const challenge = Challenge.fromResponse(firstResult.challenge)
+    const credential = Credential.from({
+      challenge,
+      payload: { spt: 'spt_test_token' },
+    })
+
+    // First payment: should succeed
+    const result1 = await handle(
+      new Request('https://example.com', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(result1.status).toBe(200)
+
+    // Replay same credential: should be rejected
+    const result2 = await handle(
+      new Request('https://example.com', {
+        headers: { Authorization: Credential.serialize(credential) },
+      }),
+    )
+    expect(result2.status).toBe(402)
+  })
+
   test('behavior: receipt contains mock reference', async () => {
     const { client } = createMockStripeClient({ id: 'pi_custom_ref' })
 

package/src/stripe/server/Charge.ts

@@ -89,6 +89,9 @@ export function charge<const parameters extends charge.Parameters>(parameters: p
             metadata: resolvedMetadata,
           })
 
+      if (pi.replayed)
+        throw new VerificationFailedError({ reason: 'Payment has already been processed.' })
+
       if (pi.status === 'requires_action') {
         throw new PaymentActionRequiredError({ reason: 'Stripe PaymentIntent requires action' })
       }
@@ -136,7 +139,7 @@ async function createWithClient(parameters: {
   metadata: Record<string, string>
   request: { amount: unknown; currency: unknown }
   spt: string
-}): Promise<{ id: string; status: string }> {
+}): Promise<{ id: string; status: string; replayed: boolean }> {
   const { client, challenge, metadata, request, spt } = parameters
   try {
     const result = await client.paymentIntents.create(
@@ -151,7 +154,9 @@ async function createWithClient(parameters: {
       } as any,
       { idempotencyKey: `mppx_${challenge.id}_${spt}` },
     )
-    return { id: result.id, status: result.status }
+    // https://docs.stripe.com/error-low-level#idempotency
+    const replayed = result.lastResponse?.headers?.['idempotent-replayed'] === 'true'
+    return { id: result.id, status: result.status, replayed }
   } catch {
     throw new VerificationFailedError({ reason: 'Stripe PaymentIntent failed' })
   }
@@ -164,7 +169,7 @@ async function createWithSecretKey(parameters: {
   metadata: Record<string, string>
   request: { amount: unknown; currency: unknown }
   spt: string
-}): Promise<{ id: string; status: string }> {
+}): Promise<{ id: string; status: string; replayed: boolean }> {
   const { secretKey, challenge, metadata, request, spt } = parameters
 
   const body = new URLSearchParams({
@@ -190,7 +195,10 @@ async function createWithSecretKey(parameters: {
   })
 
   if (!response.ok) throw new VerificationFailedError({ reason: 'Stripe PaymentIntent failed' })
-  return (await response.json()) as { id: string; status: string }
+  // https://docs.stripe.com/error-low-level#idempotency
+  const replayed = response.headers.get('idempotent-replayed') === 'true'
+  const result = (await response.json()) as { id: string; status: string }
+  return { ...result, replayed }
 }
 
 /** @internal */

package/src/tempo/Methods.test.ts

@@ -51,6 +51,85 @@ 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 invalid request', () => {
     const result = Methods.charge.schema.request.safeParse({
       amount: '1',