velocious 1.0.514 → 1.0.516

package/src/http-server/server-client.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import EventEmitter from "../utils/event-emitter.js"
+import {createReadStream} from "node:fs"
 import Logger from "../logger.js"
 
 /**
@@ -205,6 +206,101 @@ export default class ServerClient {
     })
   }
 
+  /**
+   * Streams a file to the socket while respecting socket write backpressure.
+   * @param {string} filePath - File path.
+   * @param {boolean} [sendBody] - Whether to read and send the file body.
+   * @returns {Promise<"completed" | "aborted">} - Transfer result.
+   */
+  async sendFile(filePath, sendBody = true) {
+    if (this.socket.destroyed || this.socket.writableEnded || this.socket.writable === false) return "aborted"
+    if (!sendBody) return "completed"
+
+    const readStream = createReadStream(filePath)
+    let aborted = false
+    const abort = () => {
+      aborted = true
+      readStream.destroy()
+    }
+
+    this.socket.once("close", abort)
+    this.socket.once("error", abort)
+
+    try {
+      for await (const chunk of readStream) {
+        if (aborted || !await this.writeFileChunk(chunk)) return "aborted"
+      }
+
+      return aborted ? "aborted" : "completed"
+    } catch (error) {
+      this.logger.error(() => [`Socket ${this.clientCount} file response failed`, filePath, error])
+      if (!this.socket.destroyed) this.socket.destroy()
+
+      return "aborted"
+    } finally {
+      this.socket.off("close", abort)
+      this.socket.off("error", abort)
+      readStream.destroy()
+    }
+  }
+
+  /**
+   * Writes one file chunk and waits for both write acceptance and drain when required.
+   * @param {Buffer | Uint8Array} chunk - File chunk.
+   * @returns {Promise<boolean>} - Whether the chunk was accepted before the socket aborted.
+   */
+  writeFileChunk(chunk) {
+    return new Promise((resolve) => {
+      let callbackCompleted = false
+      let drained = false
+      let settled = false
+
+      const cleanup = () => {
+        this.socket.off("close", onAbort)
+        this.socket.off("error", onAbort)
+        this.socket.off("drain", onDrain)
+      }
+      const finish = (/** @type {boolean} */ result) => {
+        if (settled) return
+
+        settled = true
+        cleanup()
+        resolve(result)
+      }
+      const finishIfReady = () => {
+        if (callbackCompleted && drained) finish(true)
+      }
+      const onAbort = () => finish(false)
+      const onDrain = () => {
+        drained = true
+        finishIfReady()
+      }
+
+      this.socket.once("close", onAbort)
+      this.socket.once("error", onAbort)
+      this.socket.once("drain", onDrain)
+
+      try {
+        const accepted = this.socket.write(chunk, (error) => {
+          if (error) {
+            finish(false)
+            return
+          }
+
+          callbackCompleted = true
+          finishIfReady()
+        })
+
+        drained = accepted
+        if (accepted) this.socket.off("drain", onDrain)
+        finishIfReady()
+      } catch (error) {
+        this.logger.error(() => [`Socket ${this.clientCount} file write failed`, error])
+        finish(false)
+      }
+    })
+  }
+
   /**
    * Runs set worker.
    * @param {import("worker_threads").Worker} newWorker - New worker.

package/src/http-server/websocket-channel.js

@@ -20,7 +20,7 @@
 export default class VelociousWebsocketChannel {
   /**
    * Runs constructor.
-   * @param {object} args
+   * @param {object} args - Session, channel parameters, and client subscription identifier.
    * @param {string} args.subscriptionId - Client-assigned id, unique within the session.
    * @param {WebsocketParams} args.params - Subscribe params.
    * @param {import("./client/websocket-session.js").default} args.session - Owning session.
@@ -36,7 +36,7 @@ export default class VelociousWebsocketChannel {
    * Subscribe-time auth. Default is `false` (deny). Channel authors
    * MUST override to allow subscriptions. Returning a Promise defers
    * the `channel-subscribed` confirmation until it resolves.
-   * @returns {boolean | Promise<boolean>}
+   * @returns {boolean | Promise<boolean>} - Whether the subscription is authorized.
    */
   canSubscribe() { return false }
 
@@ -44,14 +44,14 @@ export default class VelociousWebsocketChannel {
    * Optional — called once after `canSubscribe` resolves truthy and
    * before `channel-subscribed` is sent to the client. Use for
    * initial snapshot delivery.
-   * @returns {void | Promise<void>}
+   * @returns {void | Promise<void>} - Completes after subscription setup.
    */
   subscribed() {}
 
   /**
    * Optional — called once when the subscription ends. Fires on
    * client-initiated `channel-unsubscribe` or on session teardown.
-   * @returns {void | Promise<void>}
+   * @returns {void | Promise<void>} - Completes after subscription teardown.
    */
   unsubscribed() {}
 
@@ -60,14 +60,14 @@ export default class VelociousWebsocketChannel {
    * moved into the paused/grace registry. Either `onResume` fires
    * on successful client reconnect, or `unsubscribed()` fires when
    * the grace window expires.
-   * @returns {void | Promise<void>}
+   * @returns {void | Promise<void>} - Completes after disconnect handling.
    */
   onDisconnect() {}
 
   /**
    * Called after a client reconnect + `session-resume` rebinds this
    * subscription to a new socket.
-   * @returns {void | Promise<void>}
+   * @returns {void | Promise<void>} - Completes after resume handling.
    */
   onResume() {}
 
@@ -76,7 +76,7 @@ export default class VelociousWebsocketChannel {
    * sign-in / locale change). Override to react to session-level
    * metadata updates.
    * @param {WebsocketParams} _metadata - Updated metadata.
-   * @returns {void | Promise<void>}
+   * @returns {void | Promise<void>} - Completes after metadata-change handling.
    */
   onMetadataChanged(_metadata) {}
 
@@ -101,9 +101,9 @@ export default class VelociousWebsocketChannel {
    * Delivers a matched broadcast to this subscriber. Subclasses can
    * override when the outbound body must be tailored to subscription
    * params before sending.
-   * @param {WebsocketJsonValue} body
+   * @param {WebsocketJsonValue} body - Broadcast payload offered to this subscription.
    * @param {{eventId?: string}} [meta] - Optional event metadata.
-   * @returns {void | Promise<void>}
+   * @returns {void | Promise<void>} - Completes after broadcast delivery.
    */
   deliverBroadcast(body, meta) {
     this.sendMessage(body, meta)
@@ -113,7 +113,7 @@ export default class VelociousWebsocketChannel {
    * Sends a `channel-message` frame to THIS subscriber only.
    * When `meta.eventId` is provided, the client receives it so it
    * can track its checkpoint for `lastEventId` replay on reconnect.
-   * @param {WebsocketJsonValue} body
+   * @param {WebsocketJsonValue} body - Channel payload to send to the subscribed client.
    * @param {{eventId?: string}} [meta] - Optional event metadata.
    * @returns {void}
    */
@@ -132,6 +132,7 @@ export default class VelociousWebsocketChannel {
 
   /**
    * Runs is closed.
-   * @returns {boolean} */
+   * @returns {boolean} - Whether the channel is closed.
+   */
   isClosed() { return this._closed }
 }

package/src/http-server/websocket-connection.js

@@ -12,7 +12,7 @@
 export default class VelociousWebsocketConnection {
   /**
    * Runs constructor.
-   * @param {object} args
+   * @param {object} args - Owning session, connection parameters, and client identifier.
    * @param {string} args.connectionId - Client-assigned id, unique within the session.
    * @param {Record<string, ?>} args.params - Opaque params from the `connection-open` message.
    * @param {import("./client/websocket-session.js").default} args.session - Owning session.
@@ -28,7 +28,7 @@ export default class VelociousWebsocketConnection {
    * Called once after the session registers this connection and before
    * any `onMessage` fires. Returning a Promise defers the first
    * `connection-opened` message to the client until it resolves.
-   * @returns {void | Promise<void>}
+   * @returns {void | Promise<void>} - Completes after connection setup.
    */
   onConnect() {}
 
@@ -36,8 +36,8 @@ export default class VelociousWebsocketConnection {
    * Called for each `connection-message` the client sends to this
    * specific connection. Messages arriving before `onConnect` has
    * resolved are queued and delivered in order once it finishes.
-   * @param {?} body
-   * @returns {void | Promise<void>}
+   * @param {?} body - Client-sent payload for this connection.
+   * @returns {void | Promise<void>} - Completes after message handling.
    */
   onMessage(body) { void body }
 
@@ -47,14 +47,14 @@ export default class VelociousWebsocketConnection {
    * itself survives; either `onResume` fires on a successful
    * client reconnect, or `onClose("grace_expired")` fires when the
    * grace window expires.
-   * @returns {void | Promise<void>}
+   * @returns {void | Promise<void>} - Completes after disconnect handling.
    */
   onDisconnect() {}
 
   /**
    * Called after a client reconnect + `session-resume` rebinds this
    * connection to a new socket.
-   * @returns {void | Promise<void>}
+   * @returns {void | Promise<void>} - Completes after resume handling.
    */
   onResume() {}
 
@@ -64,15 +64,15 @@ export default class VelociousWebsocketConnection {
    * (server-initiated `close()`), `session_destroyed` (socket dropped
    * and nothing to resume; grace path did not apply), `grace_expired`
    * (paused session's grace window ran out without resume), `error`.
-   * @param {"client_close" | "server_close" | "session_destroyed" | "grace_expired" | "error"} reason
-   * @returns {void | Promise<void>}
+   * @param {"client_close" | "server_close" | "session_destroyed" | "grace_expired" | "error"} reason - Lifecycle reason for permanent connection teardown.
+   * @returns {void | Promise<void>} - Completes after close handling.
    */
   onClose(reason) { void reason }
 
   /**
    * Sends a `connection-message` frame to the client side of this
    * connection. Throws if the connection has already been closed.
-   * @param {?} body
+   * @param {?} body - Connection payload to send to the client.
    * @returns {void}
    */
   sendMessage(body) {
@@ -90,7 +90,7 @@ export default class VelociousWebsocketConnection {
   /**
    * Closes this connection from the server side. Fires `onClose`
    * locally and notifies the client with `{type: "connection-closed"}`.
-   * @param {"server_close" | "error"} [reason]
+   * @param {"server_close" | "error"} [reason] - Reason reported to the close hook and client.
    * @returns {Promise<void>}
    */
   async close(reason = "server_close") {
@@ -111,7 +111,8 @@ export default class VelociousWebsocketConnection {
 
   /**
    * Runs is closed.
-   * @returns {boolean} */
+   * @returns {boolean} - Whether the connection is closed.
+   */
   isClosed() {
     return this._closed
   }

package/src/http-server/websocket-events-host.js

@@ -120,7 +120,7 @@ export class VelociousHttpServerWebsocketEventsHost {
    * @param {object} args - Options.
    * @param {?} args.body - Event body.
    * @param {string} args.channel - Channel name.
-   * @returns {Promise<{createdAt: string, id: string} | null>}
+   * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata when storage is enabled.
    */
   async _persistV2EventIfNeeded({body, channel}) {
     return await this._persistChannelEventIfNeeded({channel, payload: body})

package/src/http-server/worker-handler/in-process.js

@@ -26,6 +26,9 @@ export default class VelociousHttpServerInProcessHandler {
      * @type {Record<number, {httpClient: Client, serverClient: import("../server-client.js").default}>} */
     this.clients = {}
 
+    /** @type {Set<Promise<void>>} */
+    this.pendingClientCloseCleanups = new Set()
+
     this.logger = new Logger(this)
     this.workerCount = workerCount
     this.unregisterFromEventsHost = websocketEventsHost.register(/** @type {?} */ (this))
@@ -53,17 +56,48 @@ export default class VelociousHttpServerInProcessHandler {
       remoteAddress: serverClient.remoteAddress
     })
 
+    let deliveryQueue = Promise.resolve()
+    const enqueueDelivery = (/** @type {() => Promise<void>} */ delivery) => {
+      deliveryQueue = deliveryQueue
+        .catch(() => {})
+        .then(delivery)
+
+      return deliveryQueue
+    }
+
     httpClient.events.on("output", (output) => {
       if (output !== null && output !== undefined) {
-        void serverClient.send(output).catch((error) => {
+        void enqueueDelivery(() => serverClient.send(output)).catch((error) => {
           this.logger.error(() => ["Failed to deliver client output", {clientCount}, error])
         })
       }
     })
 
+    httpClient.events.on("file", ({filePath, sendBody, settle}) => {
+      void enqueueDelivery(async () => {
+        await settle(await serverClient.sendFile(filePath, sendBody))
+      }).catch((error) => {
+        this.logger.error(() => ["Failed to deliver file response", {clientCount, filePath}, error])
+        void settle("aborted")
+      })
+    })
+
     httpClient.events.on("close", () => {
-      void serverClient.end()
-      delete this.clients[clientCount]
+      void enqueueDelivery(() => serverClient.end())
+        .finally(() => delete this.clients[clientCount])
+    })
+
+    serverClient.events.on("close", () => {
+      const cleanup = httpClient.abortPendingFileResponses()
+        .catch((error) => {
+          this.logger.warn("Failed to abort file responses after client close", error)
+        })
+        .finally(() => {
+          this.pendingClientCloseCleanups.delete(cleanup)
+          delete this.clients[clientCount]
+        })
+
+      this.pendingClientCloseCleanups.add(cleanup)
     })
 
     this.clients[clientCount] = {httpClient, serverClient}
@@ -90,14 +124,19 @@ export default class VelociousHttpServerInProcessHandler {
   async stop() {
     this._stopping = true
 
-    for (const {serverClient} of Object.values(this.clients)) {
-      try {
-        void serverClient.end()
-      } catch (error) {
-        this.logger.warn("Failed to close client during shutdown", error)
-      }
+    for (const {httpClient, serverClient} of Object.values(this.clients)) {
+      await Promise.all([
+        httpClient.abortPendingFileResponses().catch((error) => {
+          this.logger.warn("Failed to abort file responses during shutdown", error)
+        }),
+        serverClient.end().catch((error) => {
+          this.logger.warn("Failed to close client during shutdown", error)
+        })
+      ])
     }
 
+    await Promise.all(this.pendingClientCloseCleanups)
+
     this.clients = {}
     this.unregisterFromEventsHost?.()
   }

package/src/http-server/worker-handler/index.js

@@ -58,6 +58,9 @@ export default class VelociousHttpServerWorker {
      * Narrows the runtime value to the documented type.
      * @type {Map<number, {resolve: (snapshot: Record<string, ?>) => void}>} */
     this._debugSnapshotRequests = new Map()
+
+    /** @type {Map<number, Promise<void>>} */
+    this._clientDeliveryQueues = new Map()
   }
 
   start() {
@@ -99,9 +102,25 @@ export default class VelociousHttpServerWorker {
     client.listen()
 
     this.clients[clientCount] = client
+    client.events.on("close", () => {
+      this.handleClientAbort(clientCount)
+    })
     this.worker.postMessage({command: "newClient", clientCount, remoteAddress: client.remoteAddress})
   }
 
+  /**
+   * Propagates a parent-side socket close and clears all parent state for the client.
+   * @param {number} clientCount - Client count.
+   * @returns {void}
+   */
+  handleClientAbort(clientCount) {
+    if (!this.clients[clientCount] && !this._clientDeliveryQueues.has(clientCount)) return
+
+    delete this.clients[clientCount]
+    this._clientDeliveryQueues.delete(clientCount)
+    this.worker?.postMessage({command: "clientAbort", clientCount})
+  }
+
   /**
    * On worker error.
    * @param {?} error - Error instance.
@@ -121,10 +140,10 @@ export default class VelociousHttpServerWorker {
   onWorkerExit = (code) => {
     this._hasExited = true
     this.workerStarted = false
+    this._closeAllClients()
 
     if (code !== 0 && !this._stopping) {
       this.logger.error(`Velocious worker ${this.workerCount} exited unexpectedly with code ${code}`)
-      void this._closeAllClients()
       throw new Error(`Client worker stopped with exit code ${code}`)
     } else {
       this.logger.debug(() => `Client worker stopped with exit code ${code}`)
@@ -160,6 +179,9 @@ export default class VelociousHttpServerWorker {
    * @param {string} data.command - Command.
    * @param {number} [data.clientCount] - Client count.
    * @param {string | Uint8Array} [data.output] - Output.
+   * @param {string} [data.filePath] - File path.
+   * @param {boolean} [data.sendBody] - Whether to send the file body.
+   * @param {number} [data.transferId] - File transfer id.
    * @param {string} [data.channel] - Channel name.
    * @param {number} [data.requestId] - Debug request id.
    * @param {Record<string, ?>} [data.snapshot] - Worker debug snapshot.
@@ -197,7 +219,7 @@ export default class VelociousHttpServerWorker {
       if (output !== null && output !== undefined) {
         const outputLength = typeof output === "string" ? output.length : output.byteLength
 
-        void client.send(output).then(() => {
+        void this.enqueueClientDelivery(client.clientCount, () => client.send(output)).then(() => {
           this.logger.debug(() => ["Client output delivered", {
             clientCount,
             outputLength,
@@ -210,6 +232,25 @@ export default class VelociousHttpServerWorker {
           }, error])
         })
       }
+    } else if (command == "clientFile") {
+      const {clientCount, filePath, sendBody, transferId} = data
+      const client = typeof clientCount === "number" ? this.clients[clientCount] : undefined
+
+      if (typeof transferId !== "number") throw new Error("clientFile transferId must be a number")
+
+      if (!client || typeof filePath !== "string") {
+        this.worker?.postMessage({command: "clientFileResult", result: "aborted", transferId})
+        return
+      }
+
+      void this.enqueueClientDelivery(client.clientCount, async () => {
+        const result = await client.sendFile(filePath, sendBody !== false)
+
+        this.worker?.postMessage({command: "clientFileResult", result, transferId})
+      }).catch((error) => {
+        this.logger.error(() => ["Failed to deliver file response", {clientCount: client.clientCount, filePath}, error])
+        this.worker?.postMessage({command: "clientFileResult", result: "aborted", transferId})
+      })
     } else if (command == "clientClose") {
       const {clientCount} = data
       const client = typeof clientCount === "number" ? this.clients[clientCount] : undefined
@@ -219,11 +260,8 @@ export default class VelociousHttpServerWorker {
         return
       }
 
-      void client.end()
-
-      if (typeof clientCount === "number") {
-        delete this.clients[clientCount]
-      }
+      void this.enqueueClientDelivery(client.clientCount, () => client.end())
+        .finally(() => delete this.clients[client.clientCount])
     } else if (command == "debugSnapshot") {
       const {requestId, snapshot} = data
       if (typeof requestId !== "number") throw new Error("debugSnapshot requestId must be a number")
@@ -257,6 +295,28 @@ export default class VelociousHttpServerWorker {
     }
   }
 
+  /**
+   * Preserves socket output ordering for one client.
+   * @param {number} clientCount - Client count.
+   * @param {() => Promise<void>} delivery - Delivery operation.
+   * @returns {Promise<void>} - Queued delivery.
+   */
+  enqueueClientDelivery(clientCount, delivery) {
+    const previous = this._clientDeliveryQueues.get(clientCount) || Promise.resolve()
+    const queued = previous
+      .catch(() => {})
+      .then(delivery)
+
+    this._clientDeliveryQueues.set(clientCount, queued)
+    const clearQueue = () => {
+      if (this._clientDeliveryQueues.get(clientCount) === queued) this._clientDeliveryQueues.delete(clientCount)
+    }
+
+    void queued.then(clearQueue, clearQueue)
+
+    return queued
+  }
+
   /**
    * Runs get debug snapshot.
    * @returns {Promise<Record<string, ?>>} - Worker-local debug snapshot.

package/src/http-server/worker-handler/worker-thread.js

@@ -42,6 +42,10 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
     this.parentPort = parentPort
     this.workerData = workerData
     this.workerCount = workerCount
+    this.fileTransferCount = 0
+
+    /** @type {Map<number, {clientCount: number, settle: (result: "completed" | "aborted") => Promise<void>}>} */
+    this.fileTransfers = new Map()
 
     parentPort.on("message", errorLogger(this.onCommand))
 
@@ -98,6 +102,8 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
    * @param {string} [data.createdAt] - Event creation time.
    * @param {string} [data.eventId] - Event identifier.
    * @param {number} [data.requestId] - Debug request id.
+   * @param {number} [data.transferId] - File transfer id.
+   * @param {"completed" | "aborted"} [data.result] - File transfer result.
    * @param {?} [data.payload] - Payload data.
    * @param {Record<string, ?>} [data.broadcastParams] - V2 broadcast filter params.
    * @param {?} [data.body] - V2 broadcast body.
@@ -111,6 +117,10 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
       this.handleNewClient(data)
     } else if (command == "clientWrite") {
       await this.handleClientWrite(data)
+    } else if (command == "clientFileResult") {
+      await this.handleClientFileResult(data)
+    } else if (command == "clientAbort") {
+      await this.handleClientAbort(data)
     } else if (command == "websocketEvent") {
       await this.handleWebsocketEvent(data)
     } else if (command == "websocketV2Broadcast") {
@@ -148,6 +158,13 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
       this.parentPort.postMessage({command: "clientOutput", clientCount, output})
     })
 
+    client.events.on("file", ({filePath, sendBody, settle}) => {
+      const transferId = ++this.fileTransferCount
+
+      this.fileTransfers.set(transferId, {clientCount, settle})
+      this.parentPort.postMessage({command: "clientFile", clientCount, filePath, sendBody, transferId})
+    })
+
     client.events.on("close", (output) => {
       this.logger.debugLowLevel(() => "Close received from client in worker - forwarding to worker parent")
       this.parentPort.postMessage({command: "clientClose", clientCount, output})
@@ -156,6 +173,54 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
     this.clients[clientCount] = client
   }
 
+  /**
+   * Settles a file response after the parent finishes socket delivery.
+   * @param {object} data - File result message.
+   * @param {number} [data.transferId] - File transfer id.
+   * @param {"completed" | "aborted"} [data.result] - File transfer result.
+   * @returns {Promise<void>} - Resolves after the worker-side completion callback settles.
+   */
+  async handleClientFileResult(data) {
+    const {result, transferId} = data
+
+    if (typeof transferId !== "number") throw new Error("transferId must be a number")
+    if (result !== "completed" && result !== "aborted") throw new Error(`Unknown file transfer result: ${result}`)
+
+    const transfer = this.fileTransfers.get(transferId)
+
+    if (!transfer) return
+
+    this.fileTransfers.delete(transferId)
+    await transfer.settle(result)
+  }
+
+  /**
+   * Aborts file responses belonging to a closed parent-side socket.
+   * @param {object} data - Client abort message.
+   * @param {number} [data.clientCount] - Client count.
+   * @returns {Promise<void>} - Resolves after pending completion callbacks settle.
+   */
+  async handleClientAbort(data) {
+    const {clientCount} = data
+
+    if (typeof clientCount !== "number") throw new Error("clientCount must be a number")
+
+    const settlements = []
+    const client = this.clients[clientCount]
+
+    if (client) settlements.push(client.abortPendingFileResponses())
+
+    for (const [transferId, transfer] of this.fileTransfers) {
+      if (transfer.clientCount !== clientCount) continue
+
+      this.fileTransfers.delete(transferId)
+      settlements.push(transfer.settle("aborted"))
+    }
+
+    delete this.clients[clientCount]
+    await Promise.all(settlements)
+  }
+
   /**
    * Runs handle client write.
    * @param {object} data - Data payload.
@@ -238,6 +303,9 @@ export default class VelociousHttpServerWorkerHandlerWorkerThread {
    * @returns {Promise<void>} Resolves after worker shutdown has been requested.
    */
   async handleShutdown() {
+    await Promise.all(Object.values(this.clients).map((client) => client.abortPendingFileResponses()))
+    this.fileTransfers.clear()
+
     if (this.configuration?.closeDatabaseConnections) {
       await this.configuration.closeDatabaseConnections()
     }

package/src/sync/device-identity.js

@@ -5,7 +5,7 @@ const ECDSA_P256_SHA256_SIGNATURE_PREFIX = "ecdsa-p256-sha256-"
 
 /**
  * JSON Web Key used by the sync signing helpers.
- * @typedef {JsonWebKey} SyncJsonWebKey
+ * @typedef {import("node:crypto").webcrypto.JsonWebKey} SyncJsonWebKey
  */
 
 /**
@@ -223,7 +223,7 @@ function signedMutationSignatureValue({deviceCertificate, mutation}) {
  */
 async function signStableJson({privateKey, value}) {
   const key = await cryptoSubtle().importKey("jwk", privateKey, {name: "ECDSA", namedCurve: "P-256"}, false, ["sign"])
-  const signature = await cryptoSubtle().sign({hash: "SHA-256", name: "ECDSA"}, key, /** @type {BufferSource} */ (utf8(stableJsonStringify(value))))
+  const signature = await cryptoSubtle().sign({hash: "SHA-256", name: "ECDSA"}, key, /** @type {Uint8Array<ArrayBuffer>} */ (utf8(stableJsonStringify(value))))
 
   return `${ECDSA_P256_SHA256_SIGNATURE_PREFIX}${base64UrlEncode(new Uint8Array(signature))}`
 }
@@ -240,7 +240,7 @@ async function verifyStableJsonSignature({publicKey, signature, value}) {
   const key = await cryptoSubtle().importKey("jwk", publicKey, {name: "ECDSA", namedCurve: "P-256"}, false, ["verify"])
   const signatureBytes = base64UrlDecode(signatureWithoutPrefix(signature))
 
-  return await cryptoSubtle().verify({hash: "SHA-256", name: "ECDSA"}, key, /** @type {BufferSource} */ (signatureBytes), /** @type {BufferSource} */ (utf8(stableJsonStringify(value))))
+  return await cryptoSubtle().verify({hash: "SHA-256", name: "ECDSA"}, key, /** @type {Uint8Array<ArrayBuffer>} */ (signatureBytes), /** @type {Uint8Array<ArrayBuffer>} */ (utf8(stableJsonStringify(value))))
 }
 
 /**

package/src/sync/local-mutation-log.js

@@ -20,7 +20,6 @@ const STORAGE_KEY_LOCKS = new Map()
  * Implementations should store each mutation log record as its own row/entry.
  * Native apps should back this with SQLite and indexes on storage key, status,
  * and sequence. Avoid storing the whole log as one JSON blob.
- *
  * @typedef {object} LocalMutationLogStorage
  * @property {(storageKey: string, record: LocalMutationLogRecord) => Promise<void> | void} appendRecord - Appends one log record.
  * @property {(storageKey: string, ids: string[]) => Promise<void> | void} deleteRecords - Deletes log records by id.

package/src/sync/query-scope.js

@@ -50,13 +50,18 @@ export function serializedScopeFromQuery(query) {
  * its own local identity and cursor — a user scope's empty-conditions cursor
  * never leaks across accounts on a shared device, while the same user
  * reconnecting keeps continuity. Owner-less scopes keep their pre-owner key.
+ *
+ * A null `resourceType` is the all-types scope (the user scope): one scope
+ * covering every resource type the server authorizes for the caller, rather
+ * than one scope per type. It keys as an empty resource type, so it never
+ * collides with a type-declared scope.
  * @param {import("./sync-client-types.js").SerializedSyncScope} scope - Serialized sync scope.
  * @returns {string} Stable scope key.
  */
 export function scopeKey(scope) {
   const ownerPrefix = scope.owner === undefined || scope.owner === null ? "" : `owner=${stableJsonStringify(scope.owner)}|`
 
-  return `${ownerPrefix}${scope.resourceType}:${stableJsonStringify(scope.conditions)}`
+  return `${ownerPrefix}${scope.resourceType ?? ""}:${stableJsonStringify(scope.conditions)}`
 }
 
 /**