mppx 0.8.17 → 0.8.18

package/src/Store.ts

@@ -1,397 +0,0 @@
-/**
- * Async key-value store interface.
- *
- * Modeled after Cloudflare KV's API (`get`/`put`/`delete`).
- * Implementations handle serialization internally.
- *
- * ## Type architecture
- *
- * Uses a two-slot generic pattern inspired by Viem's `Client` type:
- *
- * - `itemMap` — constrains keys and their value types
- * - `extended` — accumulates additional capabilities (e.g., atomic `update`)
- *
- * `AtomicStore` is a type alias that fills the `extended` slot with
- * `AtomicActions`, just like Viem's `PublicClient = Client<..., PublicActions>`.
- */
-import { Json } from 'ox'
-
-import type { MaybePromise } from './internal/types.js'
-
-export type StoreItemMap = Record<string, unknown>
-
-/**
- * Describes the outcome of an atomic {@link Update} callback.
- *
- * - `noop` — leave the stored value unchanged.
- * - `set`  — write `value` for the key.
- * - `delete` — remove the key.
- *
- * Every variant carries a `result` that is forwarded to the caller.
- */
-export type Change<value, result> =
-  | { op: 'noop'; result: result }
-  | { op: 'set'; value: value; result: result }
-  | { op: 'delete'; result: result }
-
-/**
- * Atomic read-modify-write for a single key.
- *
- * `fn` receives the current value (or `null`) and returns a {@link Change}
- * describing the write to perform. Implementations may retry `fn`, so it
- * must be synchronous and free of side effects.
- */
-export type Update<itemMap extends StoreItemMap = StoreItemMap> = <
-  key extends keyof itemMap & string,
-  result,
->(
-  key: key,
-  fn: (current: itemMap[key] | null) => Change<itemMap[key], result>,
-) => Promise<result>
-
-/** Attempts to atomically record first use of a replay key through its expiry. */
-export type TryClaim<itemMap extends StoreItemMap = StoreItemMap> = <
-  key extends keyof itemMap & string,
->(
-  key: key,
-  expires: number,
-) => MaybePromise<boolean>
-
-/** Persisted marker used by the {@link tryClaim} fallback. */
-export type ReplayMarker = {
-  expires: number
-  type: 'mppx:replay'
-}
-
-/** Base key-value actions available on every {@link Store}. */
-export type StoreActions<itemMap extends StoreItemMap = StoreItemMap> = {
-  get: <key extends keyof itemMap & string>(key: key) => Promise<itemMap[key] | null>
-  put: <key extends keyof itemMap & string>(key: key, value: itemMap[key]) => Promise<void>
-  delete: <key extends keyof itemMap & string>(key: key) => Promise<void>
-}
-
-/** Atomic actions that can be provided via the `extended` slot. */
-export type AtomicActions<itemMap extends StoreItemMap = StoreItemMap> = {
-  update: Update<itemMap>
-  /** Optional single-operation fast path for recording expiring replay keys. */
-  tryClaim?: TryClaim<itemMap> | undefined
-}
-
-/**
- * Async key-value store.
- *
- * The second generic `extended` accumulates additional capabilities
- * (like {@link AtomicActions}) without structural patching.
- */
-export type Store<
-  itemMap extends StoreItemMap = StoreItemMap,
-  extended extends Record<string, unknown> | undefined = undefined,
-> = StoreActions<itemMap> & (extended extends Record<string, unknown> ? extended : unknown)
-
-/**
- * A {@link Store} whose atomic {@link Update} method is guaranteed to exist.
- *
- * Use this when atomicity is required (e.g., replay protection, channel
- * deductions). Factory functions return `AtomicStore` when the backing
- * adapter provides an `update` implementation.
- *
- * Equivalent to `Store<itemMap, AtomicActions<itemMap>>`.
- */
-export type AtomicStore<itemMap extends StoreItemMap = StoreItemMap> = Store<
-  itemMap,
-  AtomicActions<itemMap>
->
-
-/**
- * Attempts to atomically record first use of a replay key through its expiry.
- *
- * Returns `true` when this call recorded the key and `false` when it was already
- * recorded and unexpired. `expires` is a Unix timestamp in milliseconds.
- * Uses the adapter's optimized primitive when available and otherwise falls
- * back to {@link AtomicStore.update}.
- */
-export function tryClaim<itemMap extends StoreItemMap, key extends keyof itemMap & string>(
-  store: AtomicStore<itemMap>,
-  key: key,
-  expires: number,
-): MaybePromise<boolean> {
-  if (store.tryClaim) return store.tryClaim(key, expires)
-  return store.update(key, (current) => {
-    if (current !== null && (!isReplayMarker(current) || current.expires > Date.now()))
-      return { op: 'noop', result: false }
-    return {
-      op: 'set',
-      value: { expires, type: 'mppx:replay' } as itemMap[key],
-      result: true,
-    }
-  })
-}
-
-function isReplayMarker(value: unknown): value is ReplayMarker {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    'expires' in value &&
-    typeof value.expires === 'number' &&
-    'type' in value &&
-    value.type === 'mppx:replay'
-  )
-}
-
-/** Options shared by store constructors. */
-export type Options = {
-  /** Prefix prepended to every backing store key. */
-  keyPrefix?: string | undefined
-}
-
-const keyPrefixCache = new WeakMap<Store, Map<string, Store | AtomicStore>>()
-
-/** Creates a {@link Store} from an existing implementation. */
-export function from<store extends AtomicStore<any>>(store: store, options?: Options): store
-export function from<store extends Store<any>>(store: store, options?: Options): store
-export function from(store: Store | AtomicStore, options?: Options) {
-  return withKeyPrefix(store, options?.keyPrefix)
-}
-
-function withKeyPrefix(store: Store | AtomicStore, keyPrefix = ''): Store | AtomicStore {
-  if (!keyPrefix) return store
-
-  const cached = keyPrefixCache.get(store)?.get(keyPrefix)
-  if (cached) return cached
-
-  const backing = store as Store
-  const prefixedKey = (key: string) => `${keyPrefix}${key}`
-  const prefixed = from({
-    async get(key: string) {
-      return backing.get(prefixedKey(key)) as Promise<unknown>
-    },
-    async put(key: string, value: unknown) {
-      await backing.put(prefixedKey(key), value)
-    },
-    async delete(key: string) {
-      await backing.delete(prefixedKey(key))
-    },
-    ...('update' in store
-      ? {
-          async update<result>(
-            key: string,
-            fn: (current: unknown | null) => Change<unknown, result>,
-          ) {
-            return (store as AtomicStore).update(prefixedKey(key), fn as never)
-          },
-        }
-      : {}),
-    ...('tryClaim' in store && typeof store.tryClaim === 'function'
-      ? {
-          tryClaim(key: string, expires: number) {
-            return store.tryClaim!(prefixedKey(key), expires)
-          },
-        }
-      : {}),
-  } satisfies Store | AtomicStore)
-
-  const cachedByPrefix = keyPrefixCache.get(store) ?? new Map<string, Store | AtomicStore>()
-  cachedByPrefix.set(keyPrefix, prefixed)
-  keyPrefixCache.set(store, cachedByPrefix)
-  return prefixed
-}
-
-function wrapJsonUpdate(
-  update:
-    | (<result>(
-        key: string,
-        fn: (current: string | null) => Change<string, result>,
-      ) => Promise<result>)
-    | undefined,
-): AtomicActions | {} {
-  if (!update) return {}
-  return {
-    async update(key, fn) {
-      return update(key, (current) => {
-        const parsed = current == null ? null : (Json.parse(current) as never)
-        const change = fn(parsed)
-        if (change.op !== 'set') return change
-        return { ...change, value: Json.stringify(change.value) }
-      })
-    },
-  } satisfies AtomicActions
-}
-
-/** Wraps a Cloudflare KV namespace. */
-export function cloudflare(
-  kv: cloudflare.AtomicParameters,
-  options?: cloudflare.Options,
-): AtomicStore
-export function cloudflare(kv: cloudflare.Parameters, options?: cloudflare.Options): Store
-export function cloudflare(kv: cloudflare.Parameters, options?: cloudflare.Options): Store {
-  return from(
-    {
-      async get(key: string) {
-        const raw = await kv.get(key)
-        if (raw == null) return null as any
-        return Json.parse(raw as string)
-      },
-      async put(key: string, value: unknown) {
-        await kv.put(key, Json.stringify(value))
-      },
-      async delete(key: string) {
-        await kv.delete(key)
-      },
-      ...wrapJsonUpdate(kv.update),
-    },
-    options,
-  )
-}
-
-export declare namespace cloudflare {
-  export type Options = {
-    /** Prefix prepended to every backing store key. */
-    keyPrefix?: string | undefined
-  }
-
-  export type Parameters = {
-    get: (key: string) => Promise<unknown>
-    put: (key: string, value: string) => Promise<void>
-    delete: (key: string) => Promise<void>
-    update?: <result>(
-      key: string,
-      fn: (current: string | null) => Change<string, result>,
-    ) => Promise<result>
-  }
-
-  export type AtomicParameters = Omit<Parameters, 'update'> & {
-    update: NonNullable<Parameters['update']>
-  }
-}
-
-/** In-memory store backed by a `Map`. JSON-roundtrips values to match production behavior. */
-export function memory(options?: memory.Options): AtomicStore {
-  const store = new Map<string, string>()
-  return from(
-    {
-      async get(key: string) {
-        const raw = store.get(key)
-        if (raw === undefined) return null as any
-        return Json.parse(raw)
-      },
-      async put(key: string, value: unknown) {
-        store.set(key, Json.stringify(value))
-      },
-      async delete(key: string) {
-        store.delete(key)
-      },
-      async update<result>(key: string, fn: (current: unknown | null) => Change<unknown, result>) {
-        const current = store.has(key) ? (Json.parse(store.get(key)!) as never) : null
-        const change = fn(current)
-        if (change.op === 'set') store.set(key, Json.stringify(change.value))
-        if (change.op === 'delete') store.delete(key)
-        return change.result
-      },
-      tryClaim(key: string, expires: number) {
-        const current = store.has(key) ? Json.parse(store.get(key)!) : null
-        if (current !== null && (!isReplayMarker(current) || current.expires > Date.now()))
-          return false
-        store.set(key, Json.stringify({ expires, type: 'mppx:replay' }))
-        return true
-      },
-    },
-    options,
-  )
-}
-
-export declare namespace memory {
-  export type Options = {
-    /** Prefix prepended to every backing store key. */
-    keyPrefix?: string | undefined
-  }
-}
-
-/** Wraps a standard Redis client (ioredis, node-redis, Valkey). */
-export function redis(client: redis.AtomicParameters, options?: redis.Options): AtomicStore
-export function redis(client: redis.Parameters, options?: redis.Options): Store
-export function redis(client: redis.Parameters, options?: redis.Options): Store {
-  return from(
-    {
-      async get(key: string) {
-        const raw = await client.get(key)
-        if (raw == null) return null as any
-        return Json.parse(raw)
-      },
-      async put(key: string, value: unknown) {
-        await client.set(key, Json.stringify(value))
-      },
-      async delete(key: string) {
-        await client.del(key)
-      },
-      ...wrapJsonUpdate(client.update),
-    },
-    options,
-  )
-}
-
-export declare namespace redis {
-  export type Options = {
-    /** Prefix prepended to every backing store key. */
-    keyPrefix?: string | undefined
-  }
-
-  export type Parameters = {
-    get: (key: string) => Promise<string | null>
-    set: (key: string, value: string) => Promise<unknown>
-    del: (key: string) => Promise<unknown>
-    update?: <result>(
-      key: string,
-      fn: (current: string | null) => Change<string, result>,
-    ) => Promise<result>
-  }
-
-  export type AtomicParameters = Omit<Parameters, 'update'> & {
-    update: NonNullable<Parameters['update']>
-  }
-}
-
-/** Wraps an Upstash Redis instance (e.g. Vercel KV). */
-export function upstash(redis: upstash.AtomicParameters, options?: upstash.Options): AtomicStore
-export function upstash(redis: upstash.Parameters, options?: upstash.Options): Store
-export function upstash(redis: upstash.Parameters, options?: upstash.Options): Store {
-  return from(
-    {
-      async get(key: string) {
-        return (await redis.get(key)) as any
-      },
-      async put(key: string, value: unknown) {
-        await redis.set(key, value)
-      },
-      async delete(key: string) {
-        await redis.del(key)
-      },
-      ...(redis.update
-        ? {
-            update: redis.update as Update,
-          }
-        : {}),
-    },
-    options,
-  )
-}
-
-export declare namespace upstash {
-  export type Options = {
-    /** Prefix prepended to every backing store key. */
-    keyPrefix?: string | undefined
-  }
-
-  export type Parameters = {
-    get: (key: string) => Promise<unknown>
-    set: (key: string, value: unknown) => Promise<unknown>
-    del: (key: string) => Promise<unknown>
-    update?: <result>(
-      key: string,
-      fn: (current: unknown | null) => Change<unknown, result>,
-    ) => Promise<result>
-  }
-
-  export type AtomicParameters = Omit<Parameters, 'update'> & {
-    update: NonNullable<Parameters['update']>
-  }
-}

package/src/attestation/Attestation.integration.test.ts

@@ -1,208 +0,0 @@
-import type { RequestListener } from 'node:http'
-
-import { Constants as MppConstants, Credential, Method, Receipt, z } from 'mppx'
-import * as Attestation from 'mppx/attestation'
-import * as Tap from 'mppx/attestation/tap'
-import * as WebBotAuth from 'mppx/attestation/web-bot-auth'
-import { Mppx as ClientMppx } from 'mppx/client'
-import { Mppx, Request as ServerRequest } from 'mppx/server'
-import { expect, test } from 'vp/test'
-import { jwkThumbprint, keyPair } from '~test/Attestation.js'
-import * as Http from '~test/Http.js'
-
-const method = Method.from({
-  name: 'test',
-  intent: 'charge',
-  schema: {
-    credential: { payload: z.object({ token: z.string() }) },
-    request: z.object({ amount: z.string(), currency: z.string(), recipient: z.string() }),
-  },
-})
-
-const clientMethod = Method.toClient(method, {
-  async createCredential({ challenge }) {
-    return Credential.serialize({ challenge, payload: { token: 'paid' } })
-  },
-})
-
-const serverMethod = Method.toServer(method, {
-  async verify({ credential }) {
-    if (credential.payload.token !== 'paid') throw new Error('Payment credential is invalid.')
-    return Receipt.from({
-      method: 'test',
-      reference: 'test-payment',
-      status: 'success',
-      timestamp: new Date().toISOString(),
-    })
-  },
-})
-
-const charge = {
-  amount: '1',
-  currency: 'USD',
-  expires: new Date(Date.now() + 60_000).toISOString(),
-  recipient: 'merchant',
-} as const
-
-test('composes TAP and the Web Bot Auth directory profile across an MPP payment retry', async () => {
-  const tapKeys = await keyPair()
-  const webBotAuthKeys = await keyPair()
-  const webBotAuthKeyId = await jwkThumbprint(webBotAuthKeys.publicKey)
-  const signatureAgent = 'https://agent.example'
-  const nonceStore = Attestation.Store.memory()
-  const verifiers = {
-    tap: Tap.Server.verifier({
-      keyResolver: ({ keyId }) => (keyId === 'tap-agent' ? tapKeys.publicKey : undefined),
-      nonceStore,
-    }),
-    webBotAuth: WebBotAuth.Server.verifier({
-      keyResolver: ({ keyId, signatureAgent: advertisedAgent }) =>
-        keyId === webBotAuthKeyId && advertisedAgent === signatureAgent
-          ? webBotAuthKeys.publicKey
-          : undefined,
-      maxAge: 60,
-      nonceStore,
-    }),
-  }
-  const seen = await createServer(verifiers, async (request, payments) => {
-    const result = await payments.charge(charge)(request)
-    return result.status === 402 ? result.challenge : result.withReceipt(new Response('paid'))
-  })
-
-  try {
-    const client = ClientMppx.create({
-      attestation: {
-        tap: Tap.Client.signer({
-          intent: Tap.Constants.intents.payment,
-          key: tapKeys.privateKey,
-          keyId: 'tap-agent',
-        }),
-        webBotAuth: WebBotAuth.Client.signer({
-          key: webBotAuthKeys.privateKey,
-          keyId: webBotAuthKeyId,
-          signatureAgent,
-        }),
-      },
-      methods: [clientMethod],
-      polyfill: false,
-    })
-
-    const response = await client.fetch(seen.server.url)
-    expect(response.status).toBe(200)
-    expect(await response.text()).toBe('paid')
-    expect(seen.requests).toEqual([false, true])
-
-    const attemptNonces = seen.signatureInputs.map((input) =>
-      [...input.matchAll(/nonce="([^"]+)"/g)].map((match) => match[1]),
-    )
-    expect(attemptNonces).toHaveLength(2)
-    for (const nonces of attemptNonces) {
-      expect(nonces).toHaveLength(2)
-      expect(new Set(nonces).size).toBe(1)
-      expect(nonces[0]).toMatch(/^[A-Za-z0-9_-]{86}$/)
-    }
-    expect(attemptNonces[0]![0]).not.toBe(attemptNonces[1]![0])
-  } finally {
-    seen.server.close()
-  }
-})
-
-test('requires every configured server attestation', async () => {
-  const keys = await keyPair()
-  const seen = await createServer(
-    {
-      tap: Tap.Server.verifier({
-        keyResolver: () => keys.publicKey,
-        nonceStore: Attestation.Store.memory(),
-      }),
-    },
-    async (request, payments) => {
-      const result = await payments.charge(charge)(request)
-      return result.status === 402 ? result.challenge : result.withReceipt(new Response('paid'))
-    },
-  )
-
-  try {
-    const response = await fetch(seen.server.url)
-    expect(response.status).toBe(403)
-    expect(await response.text()).toMatch(/tap.*required/)
-  } finally {
-    seen.server.close()
-  }
-})
-
-test('rejects an invalid server attestation before creating a payment challenge', async () => {
-  const trustedKeys = await keyPair()
-  const untrustedKeys = await keyPair()
-  const seen = await createServer(
-    {
-      tap: Tap.Server.verifier({
-        keyResolver: () => trustedKeys.publicKey,
-        nonceStore: Attestation.Store.memory(),
-      }),
-    },
-    async (request, payments) => {
-      const result = await payments.charge(charge)(request)
-      return result.status === 402 ? result.challenge : result.withReceipt(new Response('paid'))
-    },
-  )
-
-  try {
-    const signer = Tap.Client.signer({
-      intent: Tap.Constants.intents.payment,
-      key: untrustedKeys.privateKey,
-      keyId: 'tap-agent',
-    })
-    const request = await signer.sign(new Request(seen.server.url))
-    const response = await fetch(request)
-    expect(response.status).toBe(401)
-    expect(await response.text()).toMatch(/tap.*invalid/)
-    expect(seen.requests).toEqual([false])
-  } finally {
-    seen.server.close()
-  }
-})
-
-test('rejects empty client and server attestation maps', () => {
-  expect(() =>
-    ClientMppx.create({
-      attestation: {},
-      methods: [clientMethod],
-      polyfill: false,
-    }),
-  ).toThrow('Mppx client attestation must configure at least one signer.')
-  expect(() =>
-    Mppx.create({
-      attestation: {},
-      methods: [serverMethod],
-      realm: 'localhost',
-      secretKey: 'test-secret-key-test-secret-key-32',
-    }),
-  ).toThrow('Mppx server attestation must configure at least one verifier.')
-})
-
-async function createServer(
-  verifiers: Attestation.VerifierMap,
-  handler: (request: Request, payments: ReturnType<typeof createPayments>) => Promise<Response>,
-) {
-  const payments = createPayments(verifiers)
-  const requests: boolean[] = []
-  const signatureInputs: string[] = []
-  const listener = ServerRequest.toNodeListener(async (request) => {
-    requests.push(request.headers.has(MppConstants.Headers.authorization))
-    signatureInputs.push(request.headers.get(Attestation.Headers.signatureInput) ?? '')
-    return handler(request, payments)
-  })
-  const server = await Http.createServer(((request, response) =>
-    listener(request, response)) as RequestListener)
-  return { requests, server, signatureInputs }
-}
-
-function createPayments(attestation: Attestation.VerifierMap) {
-  return Mppx.create({
-    attestation,
-    methods: [serverMethod],
-    realm: 'localhost',
-    secretKey: 'test-secret-key-test-secret-key-32',
-  })
-}

package/src/attestation/Client.test.ts

@@ -1,83 +0,0 @@
-import * as Attestation from 'mppx/attestation'
-import * as Tap from 'mppx/attestation/tap'
-import * as WebBotAuth from 'mppx/attestation/web-bot-auth'
-import { expect, test } from 'vp/test'
-import { jwkThumbprint, keyPair } from '~test/Attestation.js'
-
-test('shares one immutable context and composes signature dictionaries', async () => {
-  const tapKeys = await keyPair()
-  const webBotAuthKeys = await keyPair()
-  const webBotAuthKeyId = await jwkThumbprint(webBotAuthKeys.publicKey)
-  const tapSigner = Tap.Client.signer({
-    intent: Tap.Constants.intents.payment,
-    key: tapKeys.privateKey,
-    keyId: 'tap-agent',
-  })
-  const webBotAuthSigner = WebBotAuth.Client.signer({
-    key: webBotAuthKeys.privateKey,
-    keyId: webBotAuthKeyId,
-    signatureAgent: 'https://agent.example',
-  })
-
-  for (const signers of [
-    [webBotAuthSigner, tapSigner],
-    [tapSigner, webBotAuthSigner],
-  ] as const) {
-    const contexts: Attestation.SigningContext[] = []
-    const observingSigners = signers.map((signer) => ({
-      ...signer,
-      sign(request: Request, context?: Attestation.SigningContext) {
-        if (context) contexts.push(context)
-        return signer.sign(request, context)
-      },
-    })) as [Attestation.Signer, Attestation.Signer]
-    const signed = await Attestation.Client.composeSigners(...observingSigners).sign(
-      new Request('https://merchant.example/resource'),
-    )
-
-    expect(contexts).toHaveLength(2)
-    expect(contexts[0]).toBe(contexts[1])
-    expect(Object.isFrozen(contexts[0])).toBe(true)
-    const input = signed.headers.get(Attestation.Headers.signatureInput) ?? ''
-    const signature = signed.headers.get(Attestation.Headers.signature) ?? ''
-    expect(input).toContain(`${WebBotAuth.Constants.label}=`)
-    expect(input).toContain(`${Tap.Constants.label}=`)
-    expect(signature).toContain(`${WebBotAuth.Constants.label}=`)
-    expect(signature).toContain(`${Tap.Constants.label}=`)
-  }
-})
-
-test('rejects duplicate and mismatched signature labels', async () => {
-  const tapKeys = await keyPair()
-  const webBotAuthKeys = await keyPair()
-  const webBotAuthKeyId = await jwkThumbprint(webBotAuthKeys.publicKey)
-  const signer = Attestation.Client.composeSigners(
-    WebBotAuth.Client.signer({
-      key: webBotAuthKeys.privateKey,
-      keyId: webBotAuthKeyId,
-      label: 'agent',
-      signatureAgent: 'https://agent.example',
-    }),
-    Tap.Client.signer({
-      intent: Tap.Constants.intents.payment,
-      key: tapKeys.privateKey,
-      keyId: 'tap-agent',
-      label: 'agent',
-    }),
-  )
-
-  await expect(signer.sign(new Request('https://merchant.example/resource'))).rejects.toThrow(
-    'HTTP message signature label "agent" already exists.',
-  )
-  await expect(
-    Tap.Client.signer({
-      intent: Tap.Constants.intents.payment,
-      key: tapKeys.privateKey,
-      keyId: 'tap-agent',
-    }).sign(
-      new Request('https://merchant.example/resource', {
-        headers: { [Attestation.Headers.signatureInput]: 'orphan=("@authority")' },
-      }),
-    ),
-  ).rejects.toThrow('Signature-Input and Signature must contain the same labels.')
-})