orez-sync-cf-host 0.12.4 → 0.12.5

package/README.md

@@ -90,11 +90,21 @@ must not run the Vite loader.
 
 ## Wake channel and eviction
 
-`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
+`createZeroClientTransport()` opens `GET /<namespace>/wake?clientID=<id>` by
+default and keeps a five-minute pull as a safety check. It carries the auth token
+Zero already supplied in a WebSocket subprotocol. The sync worker converts that
+credential to the ordinary `Authorization` header before calling
+`authorizeWake`, so the standard setup reuses the application's existing
+authentication:
+
+```ts
+authorizeWake: async (request, env) => {
+  const claims = await authenticate(request, env)
+  return claims ? { userID: claims.userID } : false
+}
+```
+
+Socket attachments carry only the client ID and normalized user identity. 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
@@ -102,12 +112,10 @@ 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
+### Custom 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:
+Deployments that cannot reuse Zero's bearer token can provide a custom
+short-lived capability. The consumer Worker owns both minting and verification:
 
 ```ts
 // consumer edge route, after normal session authentication
@@ -116,7 +124,7 @@ const token = await signWakeToken({ namespace, userID, expiresAt }, env.WAKE_SEC
 return Response.json({ token, expiresAt })
 ```
 
-Pass a mint callback to the canonical HTTP transport. It calls `getToken()` for
+Pass a mint callback to the low-level HTTP transport. It calls `getToken()` for
 every socket attempt, including reconnects, so short-lived tokens are never
 reused after the wake connection drops:
 
@@ -125,7 +133,7 @@ import { ensureHttpPullTransport } from 'orez-lite/client'
 
 ensureHttpPullTransport({
   origin: syncOrigin,
-  pullIntervalMs: 5_000,
+  pullIntervalMs: 300_000,
   wake: {
     async getToken() {
       const response = await fetch(`/api/sync/${namespace}/wake-token`, {

package/dist/host.js

@@ -179,7 +179,29 @@ export function createSyncWorker(config) {
             const isAdmin = route.startsWith('/admin/');
             let wakeUserID = null;
             if (route === '/wake') {
-                const wake = await config.authorizeWake(request, env);
+                let wakeRequest = request;
+                const protocol = request.headers.get('sec-websocket-protocol')?.trim();
+                const encodedAuth = protocol?.startsWith('orez-auth.') === true
+                    ? protocol.slice('orez-auth.'.length)
+                    : null;
+                if (!request.headers.has('authorization') &&
+                    encodedAuth &&
+                    /^[A-Za-z0-9_-]+$/.test(encodedAuth)) {
+                    try {
+                        const base64 = encodedAuth.replaceAll('-', '+').replaceAll('_', '/');
+                        const binary = globalThis.atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, '='));
+                        const authToken = new TextDecoder().decode(Uint8Array.from(binary, (character) => character.charCodeAt(0)));
+                        if (authToken) {
+                            const wakeHeaders = new Headers(request.headers);
+                            wakeHeaders.set('authorization', `Bearer ${authToken}`);
+                            wakeRequest = new Request(request, { headers: wakeHeaders });
+                        }
+                    }
+                    catch {
+                        // malformed subprotocol credentials remain unauthenticated
+                    }
+                }
+                const wake = await config.authorizeWake(wakeRequest, env);
                 if (!wake)
                     return json({ error: 'missing wake capability' }, 401);
                 if (typeof wake === 'object')
@@ -209,10 +231,10 @@ export function createSyncWorker(config) {
             headers.delete(UPSTREAM_PATH_HEADER);
             headers.delete(IDENTITY_HEADER);
             let forwardedBody = null;
-            // /wake and /realtime/produce are both websocket upgrades, which cannot
-            // carry an Authorization header from a browser and have no body to put
-            // claims in. Each has its own capability check above and in the DO, so
-            // neither passes through the bearer-token gate below.
+            // /wake and /realtime/produce are both websocket upgrades and have no
+            // body to put claims in. wake authentication is normalized from its
+            // WebSocket subprotocol above; each route has its own authorization check
+            // before either reaches the Durable Object.
             if (!isAdmin &&
                 route !== '/wake' &&
                 route !== '/notify' &&
@@ -1384,7 +1406,12 @@ export function createSyncDurableObject(config) {
             // namespace poll upstream forever after its first request, even across
             // DO eviction, producing a permanent rows-written floor at zero traffic.
             this.#armUpstreamAlarm();
-            return new Response(null, { status: 101, webSocket: client });
+            const protocol = request.headers.get('sec-websocket-protocol');
+            return new Response(null, {
+                status: 101,
+                headers: protocol ? { 'Sec-WebSocket-Protocol': protocol } : undefined,
+                webSocket: client,
+            });
         }
         #admin(route, request, upstreamPath) {
             if (route === '/admin/health')

package/dist/types.d.ts

@@ -73,16 +73,16 @@ export type SyncHostConfig<Env extends SyncHostEnv = SyncHostEnv, S extends Sche
     /** Authorize authenticated application access before selecting a namespace DO. */
     authorize(request: Request, claims: NormalizedClaims, namespace: string, env: Env): boolean | Promise<boolean>;
     /** Authorize the advisory wake socket before selecting a namespace DO.
-     * Browser clients should present a short-lived, namespace-scoped capability
-     * in the query string because WebSocket cannot set request headers.
+     * The standard client carries its existing Zero auth token in a WebSocket
+     * subprotocol. The host normalizes that to the ordinary Authorization header
+     * before this callback runs.
      *
      * Return `{ userID }` instead of `true` to also identify the socket, which is
      * what a namespace serving `streamingManifest` must do: field subscriptions
      * ride this socket and are authorized against that userID. Returning bare
      * `true` there is refused rather than quietly downgraded to a wake-only
      * socket, because the failure would otherwise look like streaming that just
-     * never arrives. The capability is the only credential available here, so the
-     * userID belongs inside it. */
+     * never arrives. */
     authorizeWake(request: Request, env: Env): boolean | {
         userID: string;
     } | Promise<boolean | {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orez-sync-cf-host",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "description": "Internal orez Cloudflare sync host. Do not import directly: consumers use orez-lite/cloudflare/sync.",
   "type": "module",
   "exports": {
@@ -58,7 +58,7 @@
     "test:large-data": "bun run build:dist && bun large-data-test.mjs"
   },
   "dependencies": {
-    "orez-sync-executor": "0.12.4"
+    "orez-sync-executor": "0.12.5"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "4.20260617.1",