Authenticated, scoped sync: signed requests and per-path subscriptions

- RequestAuth: clients sign `${timestamp}:${path}:${body}` (as in
  sync-server-example); headers carry public key, timestamp, signature and
  algorithm. Pluggable signers/verifiers; Ed25519 via WebCrypto built in.
  Timestamp window and replay protection.
- KVStorageHttpServer requires auth ('none' must be explicit). With auth, every
  key, scan range and subscription path must be under the caller's public key.
- POST /events with { paths }: subscribers only receive (and on resume only
  replay) changes under their authorized paths.
- KVStorageHttp: signer option; subscribe(path)/unsubscribe(path)/close()
  replace watch(); 401/403 reject instead of retrying.
- KVStorageComposite: prefix option scopes sync, cache and subscription.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017Qxbkp4tA7G5SCWjzWuxmE

test/kv-storage/kv-storage-http-auth.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import type { KVChangeEvent } from '../../src/kv-storage/base-kv-storage.js'
+import { KVStorageComposite } from '../../src/kv-storage/kv-storage-composite.js'
+import { KVStorageInMemory } from '../../src/kv-storage/kv-storage-in-memory.js'
+import { AuthError } from '../../src/utils/errors.js'
+import { Ed25519Signer, Ed25519Verifier } from '../../src/utils/request-auth.js'
+import { collect } from '../helpers.js'
+import { TestNetwork } from './sync-helpers.js'
+
+let network: TestNetwork
+let alice: Ed25519Signer
+let bob: Ed25519Signer
+
+beforeEach(async () => {
+  network = new TestNetwork({ auth: { verifiers: [new Ed25519Verifier()] } })
+  alice = await Ed25519Signer.generate()
+  bob = await Ed25519Signer.generate()
+  await network.store.writeMany([
+    [`${alice.publicKey}/profile`, { name: 'Alice' }],
+    [`${bob.publicKey}/profile`, { name: 'Bob' }],
+    [`${bob.publicKey}/posts/1`, { title: 'secret' }],
+  ])
+})
+afterEach(() => network.close())
+
+describe('authenticated KVStorageHttpServer', () => {
+  it('lets a user read, write and list their own keys', async () => {
+    const mine = network.client(alice).child(alice.publicKey)
+    expect(await mine.get('profile')).toEqual({ name: 'Alice' })
+    await mine.child('posts').set('1', { title: 'hello' })
+    expect(await collect(mine.keys())).toEqual(['posts', 'profile'])
+    expect(await collect(mine.child('posts').entries())).toEqual([['1', { title: 'hello' }]])
+  })
+
+  it("forbids reading, writing or scanning another user's keys", async () => {
+    const client = network.client(alice)
+    const theirs = client.child(bob.publicKey)
+    await expect(theirs.get('profile')).rejects.toMatchObject({ status: 403 })
+    await expect(theirs.set('profile', { name: 'hacked' })).rejects.toBeInstanceOf(AuthError)
+    await expect(theirs.delete('profile')).rejects.toMatchObject({ status: 403 })
+    await expect(collect(theirs.keys())).rejects.toMatchObject({ status: 403 })
+    await expect(collect(client.keys())).rejects.toMatchObject({ status: 403 }) // root listing
+    await expect(client.readMany([alice.publicKey + 'x/a'])).rejects.toMatchObject({ status: 403 }) // lookalike prefix
+    expect(await network.store.readMany([`${bob.publicKey}/profile`])).toEqual([{ name: 'Bob' }])
+  })
+
+  it('rejects unsigned requests', async () => {
+    await expect(network.client().child(alice.publicKey).get('profile')).rejects.toMatchObject({ status: 401 })
+  })
+
+  it('delivers only subscribed, authorized changes', async () => {
+    const watcher = network.client(alice)
+    const received: KVChangeEvent[] = []
+    watcher.on('change', (e) => e.origin === 'remote' && received.push(e))
+    await watcher.child(alice.publicKey).child('posts').subscribe()
+    const writer = network.client(alice).child(alice.publicKey)
+    await network.client(bob).child(bob.publicKey).child('posts').set('2', { title: 'bob only' })
+    await writer.set('profile', { name: 'Alice 2' }) // not subscribed
+    const arrived = watcher.waitFor('change', () => true)
+    await writer.child('posts').set('1', { title: 'mine' })
+    await arrived
+    expect(received.flatMap((e) => e.changes)).toEqual([{ key: `${alice.publicKey}/posts/1`, value: { title: 'mine' } }])
+  })
+
+  it("refuses subscriptions to another user's keys without retrying forever", async () => {
+    await expect(network.client(alice).child(bob.publicKey).subscribe()).rejects.toMatchObject({ status: 403 })
+    await expect(network.client(alice).subscribe('')).rejects.toMatchObject({ status: 403 })
+  })
+
+  it('replays only matching changes when resuming', async () => {
+    const watcher = network.client(alice)
+    const mine = watcher.child(alice.publicKey)
+    await mine.subscribe()
+    await mine.unsubscribe()
+    await network.client(bob).child(bob.publicKey).set('x', 1)
+    await network.client(alice).child(alice.publicKey).set('y', 2)
+    const replayed: KVChangeEvent[] = []
+    watcher.on('change', (e) => replayed.push(e))
+    await mine.subscribe()
+    expect(replayed.flatMap((e) => e.changes)).toEqual([{ key: `${alice.publicKey}/y`, value: 2 }])
+  })
+
+  it('a composite scoped to the user syncs only their data', async () => {
+    const db = new KVStorageComposite({ source: network.client(alice), prefix: alice.publicKey, replicas: [new KVStorageInMemory()] })
+    await db.synced()
+    expect(await collect(db.scan({ values: true }))).toEqual([[`${alice.publicKey}/profile`, { name: 'Alice' }]])
+    expect(await collect(db.keys())).toEqual([alice.publicKey])
+    await expect(db.child(bob.publicKey).get('profile')).rejects.toBeInstanceOf(RangeError)
+    const pushed = db.waitFor('change', (e) => e.origin === 'remote')
+    await network.client(bob).child(bob.publicKey).set('ignored', 1)
+    await network.client(alice).child(alice.publicKey).set('fromElsewhere', 1)
+    expect((await pushed).changes).toEqual([{ key: `${alice.publicKey}/fromElsewhere`, value: 1 }])
+    await db.close()
+  })
+})

test/kv-storage/kv-storage-http-watch.test.ts

@@ -6,11 +6,11 @@ import { TestNetwork } from './sync-helpers.js'
 let network: TestNetwork
 afterEach(() => network?.close())
 
-describe('KVStorageHttp.watch (SSE)', () => {
+describe('KVStorageHttp.subscribe (SSE)', () => {
   it('receives changes made by other clients as remote change events', async () => {
     network = new TestNetwork()
     const watcher = network.client()
-    await watcher.watch()
+    await watcher.subscribe('')
     const received = watcher.waitFor('change', (e) => e.origin === 'remote')
     await network.client().child('users').set('1', { name: 'Ada', n: 1n })
     const event = await received
@@ -23,16 +23,16 @@ describe('KVStorageHttp.watch (SSE)', () => {
     network = new TestNetwork()
     const writer = network.client()
     const watcher = network.client()
-    await watcher.watch()
+    await watcher.subscribe('')
     const first = watcher.waitFor('change', (e) => e.origin === 'remote')
     await writer.writeMany([['a', 1]])
     await first
-    await watcher.unwatch()
+    await watcher.unsubscribe('')
     await writer.writeMany([['b', 2]])
     await writer.writeMany([['c', 3]])
     const replayed: KVChangeEvent[] = []
     watcher.on('change', (e) => replayed.push(e))
-    await watcher.watch() // resolves once caught up, so the missed changes have been emitted
+    await watcher.subscribe('') // resolves once caught up, so the missed changes have been emitted
     expect(replayed.map((e) => e.changes)).toEqual([[{ key: 'b', value: 2 }], [{ key: 'c', value: 3 }]])
   })
 
@@ -40,15 +40,15 @@ describe('KVStorageHttp.watch (SSE)', () => {
     network = new TestNetwork({ historySize: 1 })
     const writer = network.client()
     const watcher = network.client()
-    await watcher.watch()
+    await watcher.subscribe('')
     const seen = watcher.waitFor('change', () => true)
     await writer.writeMany([['a', 1]])
     await seen
-    await watcher.unwatch()
+    await watcher.unsubscribe('')
     await writer.writeMany([['b', 2]])
     await writer.writeMany([['c', 3]])
     const resync = watcher.waitFor('resync', () => true)
-    await watcher.watch()
+    await watcher.subscribe('')
     expect(await resync).toEqual({ id: expect.stringMatching(/-3$/) })
   })
 

test/kv-storage/kv-storage-http.test.ts

@@ -9,7 +9,7 @@ import { runKVStorageConformance } from './kv-storage.conformance.js'
 import { serve } from './node-server.js'
 
 runKVStorageConformance('KVStorageHttp (in-process)', () => {
-  const server = new KVStorageHttpServer(new KVStorageInMemory(), { basePath: '/kv' })
+  const server = new KVStorageHttpServer(new KVStorageInMemory(), { auth: 'none', basePath: '/kv' })
   return new KVStorageHttp({ url: 'http://test/kv', fetch: async (input, init) => server.handle(new Request(input, init)) })
 })
 
@@ -22,7 +22,7 @@ describe('over a real socket', () => {
   })
   afterAll(() => server.close())
   const fresh = () => {
-    stores.push(new KVStorageHttpServer(new KVStorageInMemory(), { basePath: `/${stores.length}` }))
+    stores.push(new KVStorageHttpServer(new KVStorageInMemory(), { auth: 'none', basePath: `/${stores.length}` }))
     return new KVStorageHttp({ url: `${server.url}/${stores.length - 1}` })
   }
 
@@ -47,7 +47,7 @@ describe('over a real socket', () => {
 
 describe('server', () => {
   it('maps errors to 404 / 500', async () => {
-    const server = new KVStorageHttpServer(new KVStorageInMemory())
+    const server = new KVStorageHttpServer(new KVStorageInMemory(), { auth: 'none' })
     expect((await server.handle(new Request('http://x/nope', { method: 'POST', body: '{}' }))).status).toBe(404)
     expect((await server.handle(new Request('http://x/readMany', { method: 'POST', body: '{"keys": 5}' }))).status).toBe(500)
   })

test/kv-storage/sync-helpers.ts

@@ -1,6 +1,7 @@
 import { KVStorageHttp } from '../../src/kv-storage/kv-storage-http.js'
 import { KVStorageHttpServer, type KVStorageHttpServerOptions } from '../../src/kv-storage/kv-storage-http-server.js'
 import { KVStorageInMemory } from '../../src/kv-storage/kv-storage-in-memory.js'
+import type { RequestSigner } from '../../src/utils/request-auth.js'
 import { KVStorageCounting } from '../helpers.js'
 
 /**
@@ -13,13 +14,14 @@ export class TestNetwork {
   readonly server: KVStorageHttpServer
   private readonly clients: KVStorageHttp[] = []
 
-  constructor(options: KVStorageHttpServerOptions = {}) {
-    this.server = new KVStorageHttpServer(this.store, options)
+  constructor(options: Partial<KVStorageHttpServerOptions> = {}) {
+    this.server = new KVStorageHttpServer(this.store, { auth: 'none', ...options })
   }
 
-  client(): KVStorageHttp {
+  client(signer?: RequestSigner): KVStorageHttp {
     const client = new KVStorageHttp({
       url: 'http://server',
+      signer,
       fetch: async (url, init) => {
         if (!this.online) throw new TypeError('fetch failed')
         return this.server.handle(new Request(url, init))
@@ -30,6 +32,6 @@ export class TestNetwork {
   }
 
   async close(): Promise<void> {
-    await Promise.all(this.clients.map((c) => c.unwatch()))
+    await Promise.all(this.clients.map((c) => c.close()))
   }
 }