orez-sync-cf-host 0.5.17 → 0.5.18

package/README.md

@@ -19,14 +19,72 @@ required second transaction to advance the LMID marker.
 
 ## Wake channel and eviction
 
-`GET /<namespace>/wake?clientID=<id>` upgrades to a Durable Object hibernating
-WebSocket. Socket attachments carry only the client ID. A committed push sends a
-text `wake` frame to all connected clients except the pusher; a scheduler window
+`GET /<namespace>/wake?clientID=<id>&wakeToken=<capability>` upgrades to a
+Durable Object hibernating WebSocket after `authorizeWake` accepts the
+capability. Browser consumers should mint a short-lived, namespace-scoped token
+at their authenticated edge because the native WebSocket constructor cannot set
+an authorization header. Socket attachments carry only the client ID. A
+committed push sends a text `wake` frame to all connected clients except the
+pusher; a scheduler window
 coalesces a burst into one frame per socket. `ping` receives `pong`. The message
 contains no state and carries no correctness weight: clients pull after a wake
 and retain their safety poll. `ctx.getWebSockets()` plus serialized attachments
 means sockets remain discoverable after hibernation/re-instantiation.
 
+### Consumer-minted wake capabilities
+
+The consumer Worker owns both token minting and verification. Add an
+authenticated edge route that signs the namespace and a short expiry, typically
+30 to 60 seconds, with a secret that never reaches the browser. Return only the
+signed token:
+
+```ts
+// consumer edge route, after normal session authentication
+const expiresAt = Date.now() + 60_000
+const token = await signWakeToken({ namespace, userID, expiresAt }, env.WAKE_SECRET)
+return Response.json({ token, expiresAt })
+```
+
+Pass a mint callback to the canonical HTTP transport. It calls `getToken()` for
+every socket attempt, including reconnects, so short-lived tokens are never
+reused after the wake connection drops:
+
+```ts
+ensureHttpPullTransport({
+  origin: syncOrigin,
+  pullIntervalMs: 5_000,
+  wake: {
+    async getToken() {
+      const response = await fetch(`/api/sync/${namespace}/wake-token`, {
+        method: 'POST',
+      })
+      if (!response.ok) throw new Error('wake token mint failed')
+      return (await response.json()).token
+    },
+  },
+})
+```
+
+The transport appends that value as `wakeToken` because browser WebSockets
+cannot set an authorization header. Verify its signature, expiry, and namespace
+inside the consumer's `authorizeWake` callback. `sync-cf-host` deliberately does
+not prescribe a token format or hold the signing key:
+
+```ts
+authorizeWake(request, env) {
+  const url = new URL(request.url)
+  return verifyWakeToken(url.searchParams.get('wakeToken'), {
+    namespace: namespaceFrom(url),
+    secret: env.WAKE_SECRET,
+  })
+}
+```
+
+Treat the URL token as a narrowly scoped capability and avoid logging it. If
+minting or wake authorization is unavailable, the wake channel retries in the
+background while HTTP pulls and the safety poll continue to provide
+convergence.
+
 `/admin/status` reports a boot ID, hibernation simulation count, connected wake
 sockets, durable database size, engine watermark/floor, and aggregate counters.
 After the configured idle gap (5 seconds in the harness deployment), the local
@@ -42,6 +100,11 @@ callback succeeds or the request presents the deployment's `ADMIN_KEY` through
 includes the persisted writer-enabled state and wasm linear-memory byte length
 in addition to the engine/counter fields above.
 
+`POST /<namespace>/notify` is rejected unless `authorizeNotify` accepts a
+service or operator capability. Both `authorizeWake` and `authorizeNotify` run
+before `idFromName`, so rejected requests cannot instantiate namespace Durable
+Objects.
+
 `POST /admin/writer` with `{ "enabled": false }` durably stops pushes for that
 namespace. A stopped writer consumes and discards the request body, returns 503,
 and performs no engine or application write. Canary rollback drills must stop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orez-sync-cf-host",
-  "version": "0.5.17",
+  "version": "0.5.18",
   "type": "module",
   "exports": {
     ".": "./src/index.ts"

package/src/config.ts

@@ -10,6 +10,12 @@ export function validatePullCaps(caps: PullCaps): PullCaps {
 export function validateSyncHostConfig<Env extends SyncHostEnv>(
   config: SyncHostConfig<Env>
 ): SyncHostConfig<Env> {
+  if (typeof config.authorizeWake !== 'function') {
+    throw new TypeError('sync host config authorizeWake is required')
+  }
+  if (typeof config.authorizeNotify !== 'function') {
+    throw new TypeError('sync host config authorizeNotify is required')
+  }
   const hasMutators = config.mutators !== undefined
   const hasDelegate = config.mutateUrl !== undefined
   if (hasMutators === hasDelegate) {
@@ -21,6 +27,9 @@ export function validateSyncHostConfig<Env extends SyncHostEnv>(
   if (config.mutateBinding !== undefined && !hasDelegate) {
     throw new TypeError('sync host config mutateBinding requires mutateUrl')
   }
+  if (config.mutateOrigin !== undefined && !hasDelegate) {
+    throw new TypeError('sync host config mutateOrigin requires mutateUrl')
+  }
   if (config.delegatedPushRetry !== undefined && !hasDelegate) {
     throw new TypeError('sync host config delegatedPushRetry requires mutateUrl')
   }
@@ -35,6 +44,20 @@ export function validateSyncHostConfig<Env extends SyncHostEnv>(
   if (config.mutateUrl && !config.mutateUrl.startsWith('/')) {
     throw new TypeError('mutateUrl must be an absolute path')
   }
+  if (config.mutateOrigin !== undefined) {
+    let origin: URL
+    try {
+      origin = new URL(config.mutateOrigin)
+    } catch {
+      throw new TypeError('mutateOrigin must be an absolute http(s) origin')
+    }
+    if (
+      (origin.protocol !== 'http:' && origin.protocol !== 'https:') ||
+      origin.origin !== config.mutateOrigin
+    ) {
+      throw new TypeError('mutateOrigin must be an absolute http(s) origin')
+    }
+  }
   if (config.upstream) {
     if (!config.upstream.binding) throw new TypeError('upstream.binding is required')
     const limit = config.upstream.changeLimit ?? 1_000

package/src/generated/sync_wasm.d.ts

@@ -1,6 +1,18 @@
 /* tslint:disable */
 /* eslint-disable */
 
+/**
+ * Apply one ordered catch-up page to staging without touching the live table
+ * namespace or live upstream watermark.
+ */
+export function engine_apply_snapshot_changes(db: any, schema: any, generation: string, batch: any): any;
+
+/**
+ * Apply one bounded source page to staging and commit its opaque cursor with
+ * the rows. The host owns one transaction per call.
+ */
+export function engine_apply_snapshot_page(db: any, schema: any, generation: string, table: string, rows: any, next_cursor?: string | null): any;
+
 /**
  * Apply one ordered page from the upstream ZeroSqlDO change feed. The host
  * owns one transaction around this call; application triggers append the
@@ -15,6 +27,12 @@ export function engine_apply_upstream_snapshot(db: any, schema: any, snapshot: a
 
 export function engine_assemble_push_response(results: any): any;
 
+/**
+ * Create a new staged generation. `start_watermark` is captured by the host
+ * from the first source snapshot-page response. The host owns the transaction.
+ */
+export function engine_begin_snapshot_generation(db: any, schema: any, start_watermark: string): any;
+
 /**
  * Compile a validated Zero query AST for a consumer mutator's transactional
  * `tx.run(...)`. Execution remains in the host-owned application transaction.
@@ -23,6 +41,12 @@ export function engine_compile_query(schema: any, ast: any): any;
 
 export function engine_finalize(db: any, client_group_id: string, client_id: string, mutation_id: string): void;
 
+/**
+ * Atomically rename a drained staged generation into the live namespace,
+ * invalidate pre-cutover client cookies, and advance the live source cursor.
+ */
+export function engine_finalize_snapshot_generation(db: any, schema: any, generation: string, watermark: string): any;
+
 /**
  * Production pull entry. The TypeScript host owns `transactionSync`.
  */
@@ -63,6 +87,12 @@ export function engine_prune(db: any, retain_changes: string): void;
  */
 export function engine_push_validate(body: any): any;
 
+/**
+ * Strictly read resumable snapshot progress. Storage and row-shape failures
+ * are errors; only a successful query with no active row returns null.
+ */
+export function engine_read_snapshot_progress(db: any): any;
+
 export function engine_record_app_error(db: any, client_group_id: string, client_id: string, mutation_id: string, user_id: string): void;
 
 export function engine_state(db: any): any;
@@ -73,11 +103,15 @@ export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembl
 
 export interface InitOutput {
     readonly memory: WebAssembly.Memory;
+    readonly engine_apply_snapshot_changes: (a: any, b: any, c: number, d: number, e: any) => [number, number, number];
+    readonly engine_apply_snapshot_page: (a: any, b: any, c: number, d: number, e: number, f: number, g: any, h: number, i: number) => [number, number, number];
     readonly engine_apply_upstream: (a: any, b: any, c: any) => [number, number, number];
     readonly engine_apply_upstream_snapshot: (a: any, b: any, c: any) => [number, number, number];
     readonly engine_assemble_push_response: (a: any) => [number, number, number];
+    readonly engine_begin_snapshot_generation: (a: any, b: any, c: number, d: number) => [number, number, number];
     readonly engine_compile_query: (a: any, b: any) => [number, number, number];
     readonly engine_finalize: (a: any, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number];
+    readonly engine_finalize_snapshot_generation: (a: any, b: any, c: number, d: number, e: number, f: number) => [number, number, number];
     readonly engine_handle_pull: (a: any, b: any, c: any, d: any, e: number, f: number, g: any, h: number, i: number) => [number, number, number];
     readonly engine_handle_query_pull: (a: any, b: any, c: number, d: number, e: any, f: number, g: number) => [number, number, number];
     readonly engine_init_query_schema: (a: any) => [number, number];
@@ -87,6 +121,7 @@ export interface InitOutput {
     readonly engine_preflight: (a: any, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number, number];
     readonly engine_prune: (a: any, b: number, c: number) => [number, number];
     readonly engine_push_validate: (a: any) => [number, number, number];
+    readonly engine_read_snapshot_progress: (a: any) => [number, number, number];
     readonly engine_record_app_error: (a: any, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number];
     readonly engine_state: (a: any) => [number, number, number];
     readonly engine_version: () => [number, number];

package/src/generated/sync_wasm.js

@@ -1,5 +1,49 @@
 /* @ts-self-types="./sync_wasm.d.ts" */
 
+/**
+ * Apply one ordered catch-up page to staging without touching the live table
+ * namespace or live upstream watermark.
+ * @param {any} db
+ * @param {any} schema
+ * @param {string} generation
+ * @param {any} batch
+ * @returns {any}
+ */
+export function engine_apply_snapshot_changes(db, schema, generation, batch) {
+    const ptr0 = passStringToWasm0(generation, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.engine_apply_snapshot_changes(db, schema, ptr0, len0, batch);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
+/**
+ * Apply one bounded source page to staging and commit its opaque cursor with
+ * the rows. The host owns one transaction per call.
+ * @param {any} db
+ * @param {any} schema
+ * @param {string} generation
+ * @param {string} table
+ * @param {any} rows
+ * @param {string | null} [next_cursor]
+ * @returns {any}
+ */
+export function engine_apply_snapshot_page(db, schema, generation, table, rows, next_cursor) {
+    const ptr0 = passStringToWasm0(generation, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(table, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    var ptr2 = isLikeNone(next_cursor) ? 0 : passStringToWasm0(next_cursor, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len2 = WASM_VECTOR_LEN;
+    const ret = wasm.engine_apply_snapshot_page(db, schema, ptr0, len0, ptr1, len1, rows, ptr2, len2);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Apply one ordered page from the upstream ZeroSqlDO change feed. The host
  * owns one transaction around this call; application triggers append the
@@ -44,6 +88,24 @@ export function engine_assemble_push_response(results) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Create a new staged generation. `start_watermark` is captured by the host
+ * from the first source snapshot-page response. The host owns the transaction.
+ * @param {any} db
+ * @param {any} schema
+ * @param {string} start_watermark
+ * @returns {any}
+ */
+export function engine_begin_snapshot_generation(db, schema, start_watermark) {
+    const ptr0 = passStringToWasm0(start_watermark, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.engine_begin_snapshot_generation(db, schema, ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Compile a validated Zero query AST for a consumer mutator's transactional
  * `tx.run(...)`. Execution remains in the host-owned application transaction.
@@ -78,6 +140,27 @@ export function engine_finalize(db, client_group_id, client_id, mutation_id) {
     }
 }
 
+/**
+ * Atomically rename a drained staged generation into the live namespace,
+ * invalidate pre-cutover client cookies, and advance the live source cursor.
+ * @param {any} db
+ * @param {any} schema
+ * @param {string} generation
+ * @param {string} watermark
+ * @returns {any}
+ */
+export function engine_finalize_snapshot_generation(db, schema, generation, watermark) {
+    const ptr0 = passStringToWasm0(generation, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(watermark, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.engine_finalize_snapshot_generation(db, schema, ptr0, len0, ptr1, len1);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * Production pull entry. The TypeScript host owns `transactionSync`.
  * @param {any} db
@@ -221,6 +304,20 @@ export function engine_push_validate(body) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Strictly read resumable snapshot progress. Storage and row-shape failures
+ * are errors; only a successful query with no active row returns null.
+ * @param {any} db
+ * @returns {any}
+ */
+export function engine_read_snapshot_progress(db) {
+    const ret = wasm.engine_read_snapshot_progress(db);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
+    }
+    return takeFromExternrefTable0(ret[0]);
+}
+
 /**
  * @param {any} db
  * @param {string} client_group_id

package/src/harness-config.ts

@@ -329,6 +329,93 @@ const harnessMutators = registerMutators({
   },
 })
 
+const WAKE_TOKEN_TTL_MS = 60_000
+
+type HarnessWakeTokenPayload = {
+  namespace: string
+  userID: string
+  expiresAt: number
+}
+
+export async function mintHarnessWakeToken(
+  namespace: string,
+  userID: string,
+  secret: string
+): Promise<{ token: string; expiresAt: number }> {
+  const expiresAt = Date.now() + WAKE_TOKEN_TTL_MS
+  const payload = encodeBase64URL(
+    new TextEncoder().encode(JSON.stringify({ namespace, userID, expiresAt }))
+  )
+  return {
+    token: `${payload}.${await signWakeToken(payload, secret)}`,
+    expiresAt,
+  }
+}
+
+async function verifyHarnessWakeToken(
+  token: string,
+  namespace: string,
+  secret: string
+): Promise<boolean> {
+  try {
+    const [payload, signature, extra] = token.split('.')
+    if (!payload || !signature || extra) return false
+    const key = await wakeTokenKey(secret, ['verify'])
+    const valid = await crypto.subtle.verify(
+      'HMAC',
+      key,
+      decodeBase64URL(signature),
+      new TextEncoder().encode(payload)
+    )
+    if (!valid) return false
+    const claims = JSON.parse(
+      new TextDecoder().decode(decodeBase64URL(payload))
+    ) as HarnessWakeTokenPayload
+    return (
+      claims.namespace === namespace &&
+      typeof claims.userID === 'string' &&
+      claims.userID.length > 0 &&
+      Number.isFinite(claims.expiresAt) &&
+      claims.expiresAt > Date.now()
+    )
+  } catch {
+    return false
+  }
+}
+
+async function signWakeToken(payload: string, secret: string): Promise<string> {
+  const key = await wakeTokenKey(secret, ['sign'])
+  const signature = await crypto.subtle.sign(
+    'HMAC',
+    key,
+    new TextEncoder().encode(payload)
+  )
+  return encodeBase64URL(new Uint8Array(signature))
+}
+
+function wakeTokenKey(secret: string, usages: KeyUsage[]): Promise<CryptoKey> {
+  return crypto.subtle.importKey(
+    'raw',
+    new TextEncoder().encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    usages
+  )
+}
+
+function encodeBase64URL(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) binary += String.fromCharCode(byte)
+  return btoa(binary).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '')
+}
+
+function decodeBase64URL(value: string): ArrayBuffer {
+  const base64 = value.replaceAll('-', '+').replaceAll('_', '/')
+  const binary = atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '='))
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0))
+    .buffer as ArrayBuffer
+}
+
 export function harnessConfig<Env extends SyncHostEnv>(): SyncHostConfig<Env> {
   return {
     hostVersion: '0.1.0',
@@ -336,7 +423,9 @@ export function harnessConfig<Env extends SyncHostEnv>(): SyncHostConfig<Env> {
     mutators: harnessMutators,
     queryAware: false,
     queryTransformVersion: 1,
-    resolveQuery(name, args) {
+    async resolveQuery(name, args) {
+      const delayMs = Number((args[0] as { delayMs?: unknown } | undefined)?.delayMs ?? 0)
+      if (delayMs > 0) await scheduler.wait(delayMs)
       return queryNameToAst(name, args) as never
     },
     initialize: initializeHarness,
@@ -349,6 +438,21 @@ export function harnessConfig<Env extends SyncHostEnv>(): SyncHostConfig<Env> {
         ?.match(/^Bearer token-(.+)$/)?.[1]
       return userID ? { userID } : null
     },
+    authorizeWake(request, env) {
+      const url = new URL(request.url)
+      const namespace = url.pathname.split('/')[1]
+      if (!namespace || !env.ADMIN_KEY) return false
+      return verifyHarnessWakeToken(
+        url.searchParams.get('wakeToken') ?? '',
+        namespace,
+        env.ADMIN_KEY
+      )
+    },
+    authorizeNotify(request, env) {
+      return (
+        Boolean(env.ADMIN_KEY) && request.headers.get('x-admin-key') === env.ADMIN_KEY
+      )
+    },
     visibility: {
       rowLocal: false,
       filter(table, claims) {

package/src/harness-worker.ts

@@ -1,4 +1,4 @@
-import { harnessConfig } from './harness-config.js'
+import { harnessConfig, mintHarnessWakeToken } from './harness-config.js'
 import { createSyncDurableObject, createSyncWorker } from './index.js'
 
 import type { SyncHostEnv } from './index.js'
@@ -8,6 +8,26 @@ interface Env extends SyncHostEnv {
 }
 
 const config = harnessConfig<Env>()
+const syncWorker = createSyncWorker(config)
 
 export const SyncDurableObject = createSyncDurableObject(config)
-export default createSyncWorker(config)
+export default {
+  async fetch(request, env, ctx): Promise<Response> {
+    const url = new URL(request.url)
+    const namespace = config.namespace(request)
+    const route = url.pathname.split('/').slice(2).join('/')
+    if (namespace && route === 'auth/wake-token') {
+      const claims = await config.authenticate(request, env)
+      if (!claims) {
+        return Response.json({ error: 'missing authentication' }, { status: 401 })
+      }
+      if (!env.ADMIN_KEY) {
+        return Response.json({ error: 'wake token minting unavailable' }, { status: 503 })
+      }
+      return Response.json(
+        await mintHarnessWakeToken(namespace, claims.userID, env.ADMIN_KEY)
+      )
+    }
+    return syncWorker.fetch!(request, env, ctx)
+  },
+} satisfies ExportedHandler<Env>