mppx 0.3.3 → 0.3.5

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/Errors.test.ts

@@ -305,7 +305,7 @@ describe('InsufficientBalanceError', () => {
         "message": "Insufficient balance.",
         "name": "InsufficientBalanceError",
         "status": 402,
-        "type": "https://paymentauth.org/problems/stream/insufficient-balance",
+        "type": "https://paymentauth.org/problems/session/insufficient-balance",
       }
     `)
   })
@@ -318,7 +318,7 @@ describe('InsufficientBalanceError', () => {
           "message": "Insufficient balance: requested 500, available 100.",
           "name": "InsufficientBalanceError",
           "status": 402,
-          "type": "https://paymentauth.org/problems/stream/insufficient-balance",
+          "type": "https://paymentauth.org/problems/session/insufficient-balance",
         }
       `)
   })
@@ -331,7 +331,7 @@ describe('InvalidSignatureError', () => {
         "message": "Invalid signature.",
         "name": "InvalidSignatureError",
         "status": 402,
-        "type": "https://paymentauth.org/problems/stream/invalid-signature",
+        "type": "https://paymentauth.org/problems/session/invalid-signature",
       }
     `)
   })
@@ -344,7 +344,7 @@ describe('InvalidSignatureError', () => {
           "message": "Invalid signature: ECDSA recovery failed.",
           "name": "InvalidSignatureError",
           "status": 402,
-          "type": "https://paymentauth.org/problems/stream/invalid-signature",
+          "type": "https://paymentauth.org/problems/session/invalid-signature",
         }
       `)
   })
@@ -357,7 +357,7 @@ describe('SignerMismatchError', () => {
         "message": "Signer is not authorized for this channel.",
         "name": "SignerMismatchError",
         "status": 402,
-        "type": "https://paymentauth.org/problems/stream/signer-mismatch",
+        "type": "https://paymentauth.org/problems/session/signer-mismatch",
       }
     `)
   })
@@ -370,7 +370,7 @@ describe('AmountExceedsDepositError', () => {
         "message": "Voucher amount exceeds channel deposit.",
         "name": "AmountExceedsDepositError",
         "status": 402,
-        "type": "https://paymentauth.org/problems/stream/amount-exceeds-deposit",
+        "type": "https://paymentauth.org/problems/session/amount-exceeds-deposit",
       }
     `)
   })
@@ -383,7 +383,7 @@ describe('DeltaTooSmallError', () => {
         "message": "Amount increase below minimum voucher delta.",
         "name": "DeltaTooSmallError",
         "status": 402,
-        "type": "https://paymentauth.org/problems/stream/delta-too-small",
+        "type": "https://paymentauth.org/problems/session/delta-too-small",
       }
     `)
   })
@@ -396,7 +396,7 @@ describe('ChannelNotFoundError', () => {
         "message": "No channel with this ID exists.",
         "name": "ChannelNotFoundError",
         "status": 410,
-        "type": "https://paymentauth.org/problems/stream/channel-not-found",
+        "type": "https://paymentauth.org/problems/session/channel-not-found",
       }
     `)
   })
@@ -409,7 +409,7 @@ describe('ChannelClosedError', () => {
         "message": "Channel is closed.",
         "name": "ChannelClosedError",
         "status": 410,
-        "type": "https://paymentauth.org/problems/stream/channel-finalized",
+        "type": "https://paymentauth.org/problems/session/channel-finalized",
       }
     `)
   })
@@ -422,7 +422,7 @@ describe('ChannelClosedError', () => {
           "message": "Channel closed: channel is finalized on-chain.",
           "name": "ChannelClosedError",
           "status": 410,
-          "type": "https://paymentauth.org/problems/stream/channel-finalized",
+          "type": "https://paymentauth.org/problems/session/channel-finalized",
         }
       `)
   })

package/src/Errors.ts

@@ -270,7 +270,7 @@ export class InsufficientBalanceError extends PaymentError {
   override readonly name = 'InsufficientBalanceError'
   readonly title = 'Insufficient Balance'
   override readonly status = 402
-  readonly type = 'https://paymentauth.org/problems/stream/insufficient-balance'
+  readonly type = 'https://paymentauth.org/problems/session/insufficient-balance'
 
   constructor(options: InsufficientBalanceError.Options = {}) {
     const { reason } = options
@@ -292,7 +292,7 @@ export class InvalidSignatureError extends PaymentError {
   override readonly name = 'InvalidSignatureError'
   readonly title = 'Invalid Signature'
   override readonly status = 402
-  readonly type = 'https://paymentauth.org/problems/stream/invalid-signature'
+  readonly type = 'https://paymentauth.org/problems/session/invalid-signature'
 
   constructor(options: InvalidSignatureError.Options = {}) {
     const { reason } = options
@@ -313,7 +313,7 @@ export class SignerMismatchError extends PaymentError {
   override readonly name = 'SignerMismatchError'
   readonly title = 'Signer Mismatch'
   override readonly status = 402
-  readonly type = 'https://paymentauth.org/problems/stream/signer-mismatch'
+  readonly type = 'https://paymentauth.org/problems/session/signer-mismatch'
 
   constructor(options: SignerMismatchError.Options = {}) {
     const { reason } = options
@@ -334,7 +334,7 @@ export class AmountExceedsDepositError extends PaymentError {
   override readonly name = 'AmountExceedsDepositError'
   readonly title = 'Amount Exceeds Deposit'
   override readonly status = 402
-  readonly type = 'https://paymentauth.org/problems/stream/amount-exceeds-deposit'
+  readonly type = 'https://paymentauth.org/problems/session/amount-exceeds-deposit'
 
   constructor(options: AmountExceedsDepositError.Options = {}) {
     const { reason } = options
@@ -355,7 +355,7 @@ export class DeltaTooSmallError extends PaymentError {
   override readonly name = 'DeltaTooSmallError'
   readonly title = 'Delta Too Small'
   override readonly status = 402
-  readonly type = 'https://paymentauth.org/problems/stream/delta-too-small'
+  readonly type = 'https://paymentauth.org/problems/session/delta-too-small'
 
   constructor(options: DeltaTooSmallError.Options = {}) {
     const { reason } = options
@@ -376,7 +376,7 @@ export class ChannelNotFoundError extends PaymentError {
   override readonly name = 'ChannelNotFoundError'
   readonly title = 'Channel Not Found'
   override readonly status = 410
-  readonly type = 'https://paymentauth.org/problems/stream/channel-not-found'
+  readonly type = 'https://paymentauth.org/problems/session/channel-not-found'
 
   constructor(options: ChannelNotFoundError.Options = {}) {
     const { reason } = options
@@ -397,7 +397,7 @@ export class ChannelClosedError extends PaymentError {
   override readonly name = 'ChannelClosedError'
   readonly title = 'Channel Closed'
   override readonly status = 410
-  readonly type = 'https://paymentauth.org/problems/stream/channel-finalized'
+  readonly type = 'https://paymentauth.org/problems/session/channel-finalized'
 
   constructor(options: ChannelClosedError.Options = {}) {
     const { reason } = options

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)
+  })
+})