mppx 0.5.7 → 0.5.9

package/src/Method.ts

@@ -67,6 +67,58 @@ export type Client<
 }
 export type AnyClient = Client<any, any>
 
+/** Transport-captured request metadata used as the authoritative request snapshot. */
+export type CapturedRequest = {
+  readonly headers: Headers
+  readonly method: string
+  readonly url: URL
+}
+
+/** Verified challenge + credential pair, bound to the captured request snapshot. */
+export type VerifiedChallengeEnvelope<
+  request extends Record<string, unknown> = Record<string, unknown>,
+  payload = unknown,
+  intent extends string = string,
+  MethodName extends string = string,
+> = {
+  readonly capturedRequest: CapturedRequest
+  readonly challenge: Challenge.Challenge<request, intent, MethodName>
+  readonly credential: Credential.Credential<
+    payload,
+    Challenge.Challenge<request, intent, MethodName>
+  >
+}
+
+/** Request hook parameters for a single method. */
+export type RequestContext<method extends Method> = {
+  capturedRequest?: CapturedRequest
+  credential?: Credential.Credential | null
+  request: z.input<method['schema']['request']>
+}
+
+/** Verification hook parameters for a single method. */
+export type VerifyContext<method extends Method> = {
+  credential: Credential.Credential<
+    z.output<method['schema']['credential']['payload']>,
+    Challenge.Challenge<z.output<method['schema']['request']>, method['intent'], method['name']>
+  >
+  envelope?:
+    | VerifiedChallengeEnvelope<
+        z.output<method['schema']['request']>,
+        z.output<method['schema']['credential']['payload']>,
+        method['intent'],
+        method['name']
+      >
+    | undefined
+  request: z.input<method['schema']['request']>
+}
+
+/** Response hook parameters for a single method. */
+export type RespondContext<method extends Method> = VerifyContext<method> & {
+  input: globalThis.Request
+  receipt: Receipt.Receipt
+}
+
 /**
  * A server-side configured method with verification logic.
  */
@@ -96,19 +148,14 @@ export type CreateCredentialFn<method extends Method, context = unknown> = (
 ) => Promise<string>
 
 /** Request transform function for a single method. */
-export type RequestFn<method extends Method> = (options: {
-  credential?: Credential.Credential | null | undefined
-  request: z.input<method['schema']['request']>
-}) => MaybePromise<z.input<method['schema']['request']>>
+export type RequestFn<method extends Method> = (
+  options: RequestContext<method>,
+) => MaybePromise<z.input<method['schema']['request']>>
 
 /** Verification function for a single method. */
-export type VerifyFn<method extends Method> = (parameters: {
-  credential: Credential.Credential<
-    z.output<method['schema']['credential']['payload']>,
-    Challenge.Challenge<z.output<method['schema']['request']>, method['intent'], method['name']>
-  >
-  request: z.input<method['schema']['request']>
-}) => Promise<Receipt.Receipt>
+export type VerifyFn<method extends Method> = (
+  parameters: VerifyContext<method>,
+) => Promise<Receipt.Receipt>
 
 /**
  * Optional respond function for a server-side method.
@@ -123,15 +170,9 @@ export type VerifyFn<method extends Method> = (parameters: {
  * **HTTP-only.** The `input` parameter is a `Request` object; MCP transports
  * do not invoke this hook.
  */
-export type RespondFn<method extends Method> = (parameters: {
-  credential: Credential.Credential<
-    z.output<method['schema']['credential']['payload']>,
-    Challenge.Challenge<z.output<method['schema']['request']>, method['intent'], method['name']>
-  >
-  input: globalThis.Request
-  receipt: Receipt.Receipt
-  request: z.input<method['schema']['request']>
-}) => MaybePromise<globalThis.Response | undefined>
+export type RespondFn<method extends Method> = (
+  parameters: RespondContext<method>,
+) => MaybePromise<globalThis.Response | undefined>
 
 /** Partial request type for defaults. */
 export type RequestDefaults<method extends Method> = ExactPartial<

package/src/Store.test-d.ts

@@ -3,18 +3,39 @@ import { expectTypeOf, test } from 'vp/test'
 import * as Store from './Store.js'
 
 test('default Store accepts any string key', () => {
-  const store = Store.memory()
+  const store = {} as Store.Store
   expectTypeOf(store.get).parameter(0).toBeString()
   expectTypeOf(store.put).parameter(0).toBeString()
   expectTypeOf(store.delete).parameter(0).toBeString()
 })
 
 test('default Store get returns unknown', async () => {
-  const store = Store.memory()
+  const store = {} as Store.Store
   const value = await store.get('anything')
   expectTypeOf(value).toEqualTypeOf<unknown>()
 })
 
+test('default AtomicStore accepts any string key on update', () => {
+  const store = {} as Store.AtomicStore
+  expectTypeOf(store.update).parameter(0).toBeString()
+})
+
+test('memory returns AtomicStore', () => {
+  const store = Store.memory()
+  expectTypeOf(store).toEqualTypeOf<Store.AtomicStore>()
+})
+
+test('AtomicStore is assignable to Store', () => {
+  const atomic = {} as Store.AtomicStore
+  expectTypeOf(atomic).toMatchTypeOf<Store.Store>()
+})
+
+test('Store is not assignable to AtomicStore', () => {
+  const store = {} as Store.Store
+  // @ts-expect-error — Store has no update method
+  const _atomic: Store.AtomicStore = store
+})
+
 test('typed Store constrains keys', () => {
   type ItemMap = { [key: `mppx:charge:${string}`]: number }
   const store = {} as Store.Store<ItemMap>
@@ -24,6 +45,13 @@ test('typed Store constrains keys', () => {
   expectTypeOf(store.delete).parameter(0).toEqualTypeOf<`mppx:charge:${string}`>()
 })
 
+test('typed AtomicStore constrains keys on update', () => {
+  type ItemMap = { [key: `mppx:charge:${string}`]: number }
+  const store = {} as Store.AtomicStore<ItemMap>
+
+  expectTypeOf(store.update).parameter(0).toEqualTypeOf<`mppx:charge:${string}`>()
+})
+
 test('typed Store infers value from key', async () => {
   type ItemMap = { [key: `mppx:charge:${string}`]: number }
   const store = {} as Store.Store<ItemMap>
@@ -40,6 +68,26 @@ test('typed Store enforces value type on put', () => {
   store.put('mppx:charge:0x123', 'wrong')
 })
 
+test('typed AtomicStore update infers value and result types', () => {
+  type ItemMap = { [key: `mppx:charge:${string}`]: number }
+  const store = {} as Store.AtomicStore<ItemMap>
+
+  const result = store.update('mppx:charge:0x123', (current) => {
+    if (current === null) return { op: 'set', value: 1, result: 'inserted' as const }
+    return { op: 'noop', result: 'existing' as const }
+  })
+
+  expectTypeOf(result).toEqualTypeOf<Promise<'inserted' | 'existing'>>()
+})
+
+test('typed AtomicStore update enforces set value type', () => {
+  type ItemMap = { [key: `mppx:charge:${string}`]: number }
+  const store = {} as Store.AtomicStore<ItemMap>
+
+  // @ts-expect-error — update set value must be number, not string
+  store.update('mppx:charge:0x123', (_current) => ({ op: 'set', value: 'wrong', result: true }))
+})
+
 test('cloudflare returns generic Store', () => {
   const store = Store.cloudflare({
     get: async () => null,
@@ -57,3 +105,33 @@ test('upstash returns generic Store', () => {
   })
   expectTypeOf(store).toEqualTypeOf<Store.Store>()
 })
+
+test('cloudflare with update returns AtomicStore', () => {
+  const store = Store.cloudflare({
+    get: async () => null,
+    put: async () => {},
+    delete: async () => {},
+    update: async (_key, fn) => fn(null).result,
+  })
+  expectTypeOf(store).toEqualTypeOf<Store.AtomicStore>()
+})
+
+test('redis with update returns AtomicStore', () => {
+  const store = Store.redis({
+    get: async () => null,
+    set: async () => null,
+    del: async () => null,
+    update: async (_key, fn) => fn(null).result,
+  })
+  expectTypeOf(store).toEqualTypeOf<Store.AtomicStore>()
+})
+
+test('upstash with update returns AtomicStore', () => {
+  const store = Store.upstash({
+    get: async () => null,
+    set: async () => null,
+    del: async () => null,
+    update: async (_key, fn) => fn(null).result,
+  })
+  expectTypeOf(store).toEqualTypeOf<Store.AtomicStore>()
+})

package/src/Store.test.ts

@@ -8,7 +8,17 @@ const nested = {
   meta: { active: true, tags: ['a', 'b'] },
 }
 
-function fakeKv() {
+function applyChange<value, result>(
+  map: Map<string, value>,
+  key: string,
+  change: Store.Change<value, result>,
+) {
+  if (change.op === 'set') map.set(key, change.value)
+  if (change.op === 'delete') map.delete(key)
+  return change.result
+}
+
+function fakeStringKv() {
   const map = new Map<string, string>()
   return {
     async get(key: string) {
@@ -20,16 +30,43 @@ function fakeKv() {
     async delete(key: string) {
       map.delete(key)
     },
+    async update<result>(
+      key: string,
+      fn: (current: string | null) => Store.Change<string, result>,
+    ) {
+      return applyChange(map, key, fn(map.get(key) ?? null))
+    },
+  }
+}
+
+function fakeUnknownKv() {
+  const map = new Map<string, unknown>()
+  return {
+    async get(key: string) {
+      return map.get(key) ?? null
+    },
+    async set(key: string, value: unknown) {
+      map.set(key, value)
+    },
+    async del(key: string) {
+      map.delete(key)
+    },
+    async update<result>(
+      key: string,
+      fn: (current: unknown | null) => Store.Change<unknown, result>,
+    ) {
+      return applyChange(map, key, fn(map.get(key) ?? null))
+    },
   }
 }
 
 describe.each([
   { label: 'memory', create: () => Store.memory() },
-  { label: 'cloudflare', create: () => Store.cloudflare(fakeKv()) },
+  { label: 'cloudflare', create: () => Store.cloudflare(fakeStringKv()) },
   {
     label: 'redis',
     create: () => {
-      const kv = fakeKv()
+      const kv = fakeStringKv()
       return Store.redis({
         get: kv.get,
         set: kv.put,
@@ -40,11 +77,11 @@ describe.each([
   {
     label: 'upstash',
     create: () => {
-      const kv = fakeKv()
+      const kv = fakeUnknownKv()
       return Store.upstash({
         get: kv.get,
-        set: (key, value) => kv.put(key, value as string),
-        del: (key) => kv.delete(key),
+        set: kv.set,
+        del: kv.del,
       })
     },
   },
@@ -77,14 +114,14 @@ describe.each([
 
 describe('json roundtrip behavior', () => {
   test('cloudflare json-roundtrips nested objects', async () => {
-    const store = Store.cloudflare(fakeKv())
+    const store = Store.cloudflare(fakeStringKv())
     const value = { a: [1, { b: 'c' }], d: null }
     await store.put('k', value)
     expect(await store.get('k')).toEqual(value)
   })
 
   test('cloudflare roundtrips BigInt values', async () => {
-    const store = Store.cloudflare(fakeKv())
+    const store = Store.cloudflare(fakeStringKv())
     const value = { amount: 1000000000000000000n, nested: { big: 42n } }
     await store.put('k', value)
     expect(await store.get('k')).toEqual(value)
@@ -105,7 +142,7 @@ describe('json roundtrip behavior', () => {
   })
 
   test('redis json-roundtrips nested objects', async () => {
-    const kv = fakeKv()
+    const kv = fakeStringKv()
     const store = Store.redis({
       get: kv.get,
       set: kv.put,
@@ -117,7 +154,7 @@ describe('json roundtrip behavior', () => {
   })
 
   test('redis roundtrips BigInt values', async () => {
-    const kv = fakeKv()
+    const kv = fakeStringKv()
     const store = Store.redis({
       get: kv.get,
       set: kv.put,
@@ -129,15 +166,115 @@ describe('json roundtrip behavior', () => {
   })
 
   test('upstash passes values through without json serialization', async () => {
-    const kv = fakeKv()
+    const kv = fakeUnknownKv()
     const store = Store.upstash({
       get: kv.get,
-      set: (key, value) => kv.put(key, value as string),
-      del: (key) => kv.delete(key),
+      set: kv.set,
+      del: kv.del,
     })
     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)
   })
+
+  test('memory update can noop, set, and delete with typed results', async () => {
+    const store = Store.memory()
+
+    const inserted = await store.update('k', (current) => {
+      expect(current).toBeNull()
+      return { op: 'set', value: { count: 1 }, result: 'inserted' as const }
+    })
+    const preserved = await store.update('k', (current) => {
+      expect(current).toEqual({ count: 1 })
+      return { op: 'noop', result: 'unchanged' as const }
+    })
+    const deleted = await store.update('k', (current) => {
+      expect(current).toEqual({ count: 1 })
+      return { op: 'delete', result: 'removed' as const }
+    })
+
+    expect(inserted).toBe('inserted')
+    expect(preserved).toBe('unchanged')
+    expect(deleted).toBe('removed')
+    expect(await store.get('k')).toBeNull()
+  })
+
+  test('cloudflare update adapts JSON values through the wrapper', async () => {
+    const kv = fakeStringKv()
+    const store = Store.cloudflare(kv)
+
+    await store.put('k', { count: 1 })
+    const result = await store.update('k', (current) => {
+      expect(current).toEqual({ count: 1 })
+      return {
+        op: 'set',
+        value: { count: (current as { count: number }).count + 1 },
+        result: 'updated' as const,
+      }
+    })
+
+    expect(result).toBe('updated')
+    expect(await store.get('k')).toEqual({ count: 2 })
+  })
+
+  test('redis update adapts JSON values through the wrapper', async () => {
+    const kv = fakeStringKv()
+    const store = Store.redis({
+      get: kv.get,
+      set: kv.put,
+      del: (key) => kv.delete(key),
+      update: kv.update,
+    })
+
+    await store.put('k', { count: 1 })
+    const result = await store.update('k', (current) => {
+      expect(current).toEqual({ count: 1 })
+      return {
+        op: 'set',
+        value: { count: (current as { count: number }).count + 1 },
+        result: 'updated' as const,
+      }
+    })
+
+    expect(result).toBe('updated')
+    expect(await store.get('k')).toEqual({ count: 2 })
+  })
+
+  test('upstash update passes values through the wrapper', async () => {
+    const kv = fakeUnknownKv()
+    const store = Store.upstash({
+      get: kv.get,
+      set: kv.set,
+      del: kv.del,
+      update: kv.update,
+    })
+
+    await store.put('k', { count: 1 })
+    const result = await store.update('k', (current) => {
+      expect(current).toEqual({ count: 1 })
+      return {
+        op: 'set',
+        value: { count: (current as { count: number }).count + 1 },
+        result: 'updated' as const,
+      }
+    })
+
+    expect(result).toBe('updated')
+    expect(await store.get('k')).toEqual({ count: 2 })
+  })
+
+  test('upstash update passes through unencoded values', async () => {
+    const kv = fakeUnknownKv()
+    const store = Store.upstash(kv)
+
+    await store.put('k', { count: 1 })
+    const result = await store.update!('k', (current) => {
+      expect(current).toEqual({ count: 1 })
+      return { op: 'set', value: { count: (current as { count: number }).count + 1 }, result: 2 }
+    })
+
+    expect(result).toBe(2)
+    expect(await kv.get('k')).toEqual({ count: 2 })
+  })
 })

package/src/Store.ts

@@ -3,23 +3,118 @@
  *
  * 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'
 
 export type StoreItemMap = Record<string, unknown>
 
-export type Store<itemMap extends StoreItemMap = StoreItemMap> = {
+/**
+ * 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>
+
+/** 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>
+}
+
+/**
+ * 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>
+>
+
 /** Creates a {@link Store} from an existing implementation. */
-export function from<store extends Store>(store: store): store {
+export function from<store extends Store>(store: store): store
+export function from<store extends AtomicStore>(store: store): store
+export function from(store: Store | AtomicStore) {
   return store
 }
 
+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): AtomicStore
+export function cloudflare(kv: cloudflare.Parameters): Store
 export function cloudflare(kv: cloudflare.Parameters): Store {
   return from({
     async get(key) {
@@ -33,6 +128,7 @@ export function cloudflare(kv: cloudflare.Parameters): Store {
     async delete(key) {
       await kv.delete(key)
     },
+    ...wrapJsonUpdate(kv.update),
   })
 }
 
@@ -41,11 +137,19 @@ export declare namespace cloudflare {
     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(): Store {
+export function memory(): AtomicStore {
   const store = new Map<string, string>()
   return from({
     async get(key) {
@@ -59,10 +163,19 @@ export function memory(): Store {
     async delete(key) {
       store.delete(key)
     },
+    async update(key, fn) {
+      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
+    },
   })
 }
 
 /** Wraps a standard Redis client (ioredis, node-redis, Valkey). */
+export function redis(client: redis.AtomicParameters): AtomicStore
+export function redis(client: redis.Parameters): Store
 export function redis(client: redis.Parameters): Store {
   return from({
     async get(key) {
@@ -76,6 +189,7 @@ export function redis(client: redis.Parameters): Store {
     async delete(key) {
       await client.del(key)
     },
+    ...wrapJsonUpdate(client.update),
   })
 }
 
@@ -84,10 +198,20 @@ export declare namespace redis {
     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): AtomicStore
+export function upstash(redis: upstash.Parameters): Store
 export function upstash(redis: upstash.Parameters): Store {
   return from({
     async get(key) {
@@ -99,6 +223,11 @@ export function upstash(redis: upstash.Parameters): Store {
     async delete(key) {
       await redis.del(key)
     },
+    ...(redis.update
+      ? {
+          update: redis.update as Update,
+        }
+      : {}),
   })
 }
 
@@ -107,5 +236,13 @@ export declare namespace upstash {
     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/mcp-sdk/server/Transport.test.ts

@@ -26,6 +26,18 @@ const credential: Credential = {
 }
 
 describe('mcpSdk', () => {
+  describe('captureRequest', () => {
+    test('captures a stable synthetic MCP SDK request snapshot', async () => {
+      const transport = mcpSdk()
+
+      expect(await transport.captureRequest?.({})).toEqual({
+        headers: new Headers(),
+        method: 'POST',
+        url: new URL('mcp://request/sdk'),
+      })
+    })
+  })
+
   describe('getCredential', () => {
     test('returns credential from _meta', () => {
       const transport = mcpSdk()