mppx 0.3.4 → 0.3.5

package/src/Challenge.test.ts

@@ -73,7 +73,7 @@ describe('from', () => {
         intent: 'charge',
         request: { amount: '1000000' },
       },
-      expectedId: 'SOfbA51LV3LCkGE7RbomqwXdbWVlrZwlW-Z9aOHolxw',
+      expectedId: 'X6v1eo7fJ76gAxqY0xN9Jd__4lUyDDYmriryOM-5FO4',
     },
     {
       label: 'with expires',
@@ -84,7 +84,7 @@ describe('from', () => {
         request: { amount: '1000000' },
         expires: '2025-01-06T12:00:00Z',
       },
-      expectedId: 'R1ZSIwoIjkFhMCSzUGiCTesiigf5vV65EQ_3gVNtsNw',
+      expectedId: 'ChPX33RkKSZoSUyZcu8ai4hhkvjZJFkZVnvWs5s0iXI',
     },
     {
       label: 'with digest',
@@ -95,7 +95,7 @@ describe('from', () => {
         request: { amount: '1000000' },
         digest: 'sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE',
       },
-      expectedId: 'AiMmBdsSOkOYpXTupMnzVnrzZbqMY_P2i80vENRUSN4',
+      expectedId: 'JHB7EFsPVb-xsYCo8LHcOzeX1gfXWVoUSzQsZhKAfKM',
     },
     {
       label: 'with expires and digest',
@@ -107,7 +107,7 @@ describe('from', () => {
         expires: '2025-01-06T12:00:00Z',
         digest: 'sha-256=X48E9qOokqqrvdts8nOJRJN3OWDUoyWxBf7kbu9DBPE',
       },
-      expectedId: 'FMBGqN7MzpKagHsCcartZM09CnUqv7UgmaCy45Ozgug',
+      expectedId: 'm39jbWWCIfmfJZSwCfvKFFtBl0Qwf9X4nOmDb21peLA',
     },
     {
       label: 'with description (not in HMAC input)',
@@ -118,7 +118,7 @@ describe('from', () => {
         request: { amount: '1000000' },
         description: 'Test payment',
       },
-      expectedId: 'SOfbA51LV3LCkGE7RbomqwXdbWVlrZwlW-Z9aOHolxw',
+      expectedId: 'X6v1eo7fJ76gAxqY0xN9Jd__4lUyDDYmriryOM-5FO4',
     },
     {
       label: 'with multi-field request',
@@ -128,7 +128,7 @@ describe('from', () => {
         intent: 'charge',
         request: { amount: '1000000', currency: '0x1234', recipient: '0xabcd' },
       },
-      expectedId: '5CXJi4bWMz2W54WjnlmoxnwTYe-JKwhw0z32ICQ65Es',
+      expectedId: '_H5TOnnlW0zduQ5OhQ3EyLVze_TqxLDPda2CGZPZxOc',
     },
     {
       label: 'with nested methodDetails in request',
@@ -138,7 +138,7 @@ describe('from', () => {
         intent: 'charge',
         request: { amount: '1000000', currency: '0x1234', methodDetails: { chainId: 42431 } },
       },
-      expectedId: 'eid66xXUZsj46Pb30AfAf7m5kPehgianI16rZ-QY8HU',
+      expectedId: 'TqujwpuDDg_zsWGINAd5XObO2rRe6uYufpqvtDmr6N8',
     },
     {
       label: 'with empty request',
@@ -148,7 +148,7 @@ describe('from', () => {
         intent: 'charge',
         request: {},
       },
-      expectedId: '6kq-PYTyXtaGAHTHCVUrc_hIsAwLeskeQFtDZerMYhM',
+      expectedId: 'yLN7yChAejW9WNmb54HpJIWpdb1WWXeA3_aCx4dxmkU',
     },
     {
       label: 'different realm',
@@ -158,7 +158,7 @@ describe('from', () => {
         intent: 'charge',
         request: { amount: '1000000' },
       },
-      expectedId: '-gMjd8UeUvBcqUaUzarVj6ikH_YoDowpaNbEwK1Tmx8',
+      expectedId: '3F5bOo2a9RUihdwKk4hGRvBvzQmVPBMDvW0YM-8GD00',
     },
     {
       label: 'different method',
@@ -168,7 +168,7 @@ describe('from', () => {
         intent: 'charge',
         request: { amount: '1000000' },
       },
-      expectedId: 'DRH9ycmIlZ2lYUatIHCrxpm9K7ig5pniZ3ulleb7vl0',
+      expectedId: 'o0ra2sd7HcB4Ph0Vns69gRDUhSj5WNOnUopcDqKPLz4',
     },
     {
       label: 'different intent',
@@ -178,7 +178,7 @@ describe('from', () => {
         intent: 'session',
         request: { amount: '1000000' },
       },
-      expectedId: 'INeBi93MhinvbwdUxeUUIaT5Q_ufgLKPYZb5Tg43A1o',
+      expectedId: 'aAY7_IEDzsznNYplhOSE8cERQxvjFcT4Lcn-7FHjLVE',
     },
   ] as const
 
@@ -559,3 +559,193 @@ describe('verifyId', () => {
     expect(Challenge.verify(tampered, { secretKey: 'my-secret' })).toBe(false)
   })
 })
+
+describe('opaque', () => {
+  test('behavior: meta sets opaque on challenge via from()', () => {
+    const challenge = Challenge.from({
+      id: 'abc123',
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: { pi: 'pi_3abc123XYZ' },
+    })
+
+    expect(challenge.opaque).toEqual({ pi: 'pi_3abc123XYZ' })
+    expect((challenge.request as Record<string, unknown>).opaque).toBeUndefined()
+  })
+
+  test('behavior: meta sets opaque on challenge via fromMethod()', () => {
+    const challenge = Challenge.fromMethod(Methods.charge, {
+      id: 'abc123',
+      realm: 'api.example.com',
+      request: {
+        amount: '1',
+        currency: '0x20c0000000000000000000000000000000000001',
+        decimals: 6,
+        recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
+        expires: '2025-01-06T12:00:00Z',
+      },
+      meta: { payment_intent: 'pi_3abc123XYZ' },
+    })
+
+    expect(challenge.opaque).toEqual({ payment_intent: 'pi_3abc123XYZ' })
+  })
+
+  test('behavior: challenge.opaque is undefined when no meta', () => {
+    const challenge = Challenge.from({
+      id: 'abc123',
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+    })
+
+    expect(challenge.opaque).toBeUndefined()
+  })
+
+  test('behavior: opaque roundtrips through serialize/deserialize', () => {
+    const original = Challenge.from({
+      id: 'abc123',
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: { pi: 'pi_3abc123XYZ', deposit: 'dep_456' },
+    })
+
+    const header = Challenge.serialize(original)
+    const deserialized = Challenge.deserialize(header)
+
+    expect(deserialized.opaque).toEqual({ pi: 'pi_3abc123XYZ', deposit: 'dep_456' })
+  })
+
+  test('behavior: meta with empty object produces opaque: {}', () => {
+    const challenge = Challenge.from({
+      id: 'abc123',
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: {},
+    })
+
+    expect(challenge.opaque).toEqual({})
+  })
+
+  test('hmac: opaque affects challenge ID', () => {
+    const withMeta = Challenge.from({
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: { pi: 'pi_3abc123XYZ' },
+      secretKey: 'test-secret',
+    })
+
+    const withoutMeta = Challenge.from({
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      secretKey: 'test-secret',
+    })
+
+    expect(withMeta.id).not.toBe(withoutMeta.id)
+  })
+
+  test('hmac: different opaque values produce different IDs', () => {
+    const meta1 = Challenge.from({
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: { pi: 'pi_111' },
+      secretKey: 'test-secret',
+    })
+
+    const meta2 = Challenge.from({
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: { pi: 'pi_222' },
+      secretKey: 'test-secret',
+    })
+
+    expect(meta1.id).not.toBe(meta2.id)
+  })
+
+  test('hmac: same opaque produces same ID', () => {
+    const challenge1 = Challenge.from({
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: { pi: 'pi_3abc123XYZ' },
+      secretKey: 'test-secret',
+    })
+
+    const challenge2 = Challenge.from({
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: { pi: 'pi_3abc123XYZ' },
+      secretKey: 'test-secret',
+    })
+
+    expect(challenge1.id).toBe(challenge2.id)
+  })
+
+  test('hmac: verify succeeds with opaque', () => {
+    const challenge = Challenge.from({
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: { pi: 'pi_3abc123XYZ' },
+      secretKey: 'my-secret',
+    })
+
+    expect(Challenge.verify(challenge, { secretKey: 'my-secret' })).toBe(true)
+  })
+
+  test('hmac: verify detects tampered opaque', () => {
+    const challenge = Challenge.from({
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: { pi: 'pi_3abc123XYZ' },
+      secretKey: 'my-secret',
+    })
+
+    const tampered = {
+      ...challenge,
+      opaque: { pi: 'pi_TAMPERED' },
+    }
+    expect(Challenge.verify(tampered, { secretKey: 'my-secret' })).toBe(false)
+  })
+
+  test('behavior: multiple key-value pairs in opaque', () => {
+    const challenge = Challenge.from({
+      id: 'abc123',
+      realm: 'api.example.com',
+      method: 'tempo',
+      intent: 'charge',
+      request: { amount: '1000000' },
+      meta: {
+        payment_intent: 'pi_3abc123XYZ',
+        customer: 'cus_xyz',
+        session_id: 'sess_abc',
+      },
+    })
+
+    expect(challenge.opaque).toEqual({
+      payment_intent: 'pi_3abc123XYZ',
+      customer: 'cus_xyz',
+      session_id: 'sess_abc',
+    })
+  })
+})

package/src/Challenge.ts

@@ -27,6 +27,8 @@ export const Schema = z.object({
   intent: z.string(),
   /** Payment method (e.g., "tempo", "stripe"). */
   method: z.string(),
+  /** Optional server-defined correlation data. Flat string-to-string map; clients MUST NOT modify. */
+  opaque: z.optional(z.record(z.string(), z.string())),
   /** Server realm (e.g., hostname). */
   realm: z.string(),
   /** Method-specific request data. */
@@ -111,11 +113,20 @@ export function from<
   const methods extends readonly Method.Method[] | undefined = undefined,
 >(parameters: parameters, options?: from.Options<methods>): from.ReturnType<parameters, methods> {
   void options
-  const { description, digest, method: methodName, intent, realm, request, secretKey } = parameters
+  const {
+    description,
+    digest,
+    meta,
+    method: methodName,
+    intent,
+    realm,
+    request,
+    secretKey,
+  } = parameters
 
   const expires = (parameters.expires ?? request.expires) as string
   const id = secretKey
-    ? computeId({ ...parameters, expires }, { secretKey })
+    ? computeId({ ...parameters, expires, ...(meta && { opaque: meta }) }, { secretKey })
     : (parameters as { id: string }).id
 
   return Schema.parse({
@@ -127,6 +138,7 @@ export function from<
     ...(description && { description }),
     ...(digest && { digest }),
     ...(expires && { expires }),
+    ...(meta && { opaque: meta }),
   }) as from.ReturnType<parameters, methods>
 }
 
@@ -153,6 +165,8 @@ export declare namespace from {
     expires?: string | undefined
     /** Intent type (e.g., "charge", "session"). */
     intent: string
+    /** Optional server-defined correlation data (serialized as `opaque` on the challenge). Flat string-to-string map; clients MUST NOT modify. */
+    meta?: Record<string, string> | undefined
     /** Payment method (e.g., "tempo", "stripe"). */
     method: string
     /** Server realm (e.g., hostname). */
@@ -206,7 +220,7 @@ export function fromMethod<const method extends Method.Method>(
   parameters: fromMethod.Parameters<method>,
 ): fromMethod.ReturnType<method> {
   const { name: methodName, intent } = method
-  const { description, digest, expires, id, realm, secretKey } = parameters
+  const { description, digest, expires, id, meta, realm, secretKey } = parameters
 
   const request = PaymentRequest.fromMethod(method, parameters.request)
 
@@ -219,6 +233,7 @@ export function fromMethod<const method extends Method.Method>(
     description,
     digest,
     expires,
+    meta,
   } as from.Parameters) as fromMethod.ReturnType<method>
 }
 
@@ -239,6 +254,8 @@ export declare namespace fromMethod {
     digest?: string | undefined
     /** Optional expiration timestamp (ISO 8601). */
     expires?: string | undefined
+    /** Optional server-defined correlation data (serialized as `opaque` on the challenge). Flat string-to-string map; clients MUST NOT modify. */
+    meta?: Record<string, string> | undefined
     /** Server realm (e.g., hostname). */
     realm: string
     /** Method-specific request data. */
@@ -274,6 +291,8 @@ export function serialize(challenge: Challenge): string {
   if (challenge.description !== undefined) parts.push(`description="${challenge.description}"`)
   if (challenge.digest !== undefined) parts.push(`digest="${challenge.digest}"`)
   if (challenge.expires !== undefined) parts.push(`expires="${challenge.expires}"`)
+  if (challenge.opaque !== undefined)
+    parts.push(`opaque="${PaymentRequest.serialize(challenge.opaque)}"`)
 
   return `Payment ${parts.join(', ')}`
 }
@@ -314,13 +333,14 @@ export function deserialize<const methods extends readonly Method.Method[] | und
     }
   }
 
-  const { request, ...rest } = result
+  const { request, opaque, ...rest } = result
   if (!request) throw new Error('Missing request parameter.')
 
   return from(
     {
       ...rest,
       request: PaymentRequest.deserialize(request),
+      ...(opaque && { meta: PaymentRequest.deserialize(opaque) as Record<string, string> }),
     } as from.Parameters,
     options,
   )
@@ -404,8 +424,17 @@ export declare namespace verify {
   }
 }
 
+/** Alias for `challenge.opaque`. Extracts server-defined correlation data from a challenge. */
+export function meta(challenge: Challenge): Record<string, string> | undefined {
+  return challenge.opaque
+}
+
 /** @internal Computes HMAC-SHA256 challenge ID from parameters. */
 function computeId(challenge: Omit<Challenge, 'id'>, options: { secretKey: string }): string {
+  // Each field occupies a fixed positional slot joined by '|'. Optional fields
+  // use an empty string when absent so the slot count is stable — this avoids
+  // ambiguity between e.g. (expires set, no digest) vs (no expires, digest set)
+  // and means adding a new optional field changes all HMACs exactly once.
   const input = [
     challenge.realm,
     challenge.method,
@@ -413,6 +442,7 @@ function computeId(challenge: Omit<Challenge, 'id'>, options: { secretKey: strin
     PaymentRequest.serialize(challenge.request),
     challenge.expires ?? '',
     challenge.digest ?? '',
+    challenge.opaque ? PaymentRequest.serialize(challenge.opaque) : '',
   ].join('|')
 
   const key = Bytes.fromString(options.secretKey)

package/src/Store.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, test } from 'vitest'
+import * as Store from './Store.js'
+
+const nested = {
+  name: 'alice',
+  scores: [1, 2, 3],
+  meta: { active: true, tags: ['a', 'b'] },
+}
+
+function fakeKv(): Store.cloudflare.Parameters {
+  const map = new Map<string, string>()
+  return {
+    async get(key) {
+      return map.get(key) ?? null
+    },
+    async put(key, value) {
+      map.set(key, value)
+    },
+    async delete(key) {
+      map.delete(key)
+    },
+  }
+}
+
+describe.each([
+  { label: 'memory', create: () => Store.memory() },
+  { label: 'cloudflare', create: () => Store.cloudflare(fakeKv()) },
+  {
+    label: 'upstash',
+    create: () => {
+      const kv = fakeKv()
+      return Store.upstash({
+        get: kv.get,
+        set: (key, value) => kv.put(key, value as string),
+        del: (key) => kv.delete(key),
+      })
+    },
+  },
+])('$label', ({ create }) => {
+  test('roundtrip', async () => {
+    const store = create()
+    await store.put('k', nested)
+    expect(await store.get('k')).toEqual(nested)
+  })
+
+  test('get missing key returns null', async () => {
+    const store = create()
+    expect(await store.get('missing')).toBeNull()
+  })
+
+  test('delete removes key', async () => {
+    const store = create()
+    await store.put('k', 'value')
+    await store.delete('k')
+    expect(await store.get('k')).toBeNull()
+  })
+
+  test('put overwrites existing value', async () => {
+    const store = create()
+    await store.put('k', 'first')
+    await store.put('k', 'second')
+    expect(await store.get('k')).toBe('second')
+  })
+})
+
+describe('json roundtrip behavior', () => {
+  test('memory json-roundtrips nested objects', async () => {
+    const store = Store.memory()
+    const value = { a: [1, { b: 'c' }], d: null }
+    await store.put('k', value)
+    expect(await store.get('k')).toEqual(value)
+  })
+
+  test('cloudflare json-roundtrips nested objects', async () => {
+    const store = Store.cloudflare(fakeKv())
+    const value = { a: [1, { b: 'c' }], d: null }
+    await store.put('k', value)
+    expect(await store.get('k')).toEqual(value)
+  })
+
+  test('upstash passes values through without json serialization', async () => {
+    const kv = fakeKv()
+    const store = Store.upstash({
+      get: kv.get,
+      set: (key, value) => kv.put(key, value as string),
+      del: (key) => kv.delete(key),
+    })
+    const value = { a: 1 }
+    await store.put('k', value)
+    // upstash store does not JSON-serialize; the fake map holds the original reference
+    expect(await kv.get('k')).toBe(value)
+  })
+})