velocious 1.0.571 → 1.0.573

package/build/src/utils/bearer-token.js

@@ -0,0 +1,29 @@
+// @ts-check
+import crypto from "node:crypto";
+/**
+ * Constant-time comparison so token checks don't leak length/contents through
+ * timing. Returns false for differing lengths before the timing-safe compare.
+ * @param {string} a - First value.
+ * @param {string} b - Second value.
+ * @returns {boolean} - Whether the values are equal.
+ */
+export function constantTimeEqual(a, b) {
+    const bufferA = Buffer.from(String(a));
+    const bufferB = Buffer.from(String(b));
+    if (bufferA.length !== bufferB.length)
+        return false;
+    return crypto.timingSafeEqual(bufferA, bufferB);
+}
+/**
+ * Extracts the bearer token from the Authorization header of a request.
+ * @param {import("../http-server/client/request.js").default | import("../http-server/client/websocket-request.js").default} request - Request object.
+ * @returns {string | null} - Bearer token from the Authorization header, if any.
+ */
+export function bearerToken(request) {
+    const header = request.header("authorization");
+    if (typeof header !== "string")
+        return null;
+    const match = header.match(/^Bearer\s+(.+)$/i);
+    return match ? match[1].trim() : null;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYmVhcmVyLXRva2VuLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3V0aWxzL2JlYXJlci10b2tlbi5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxZQUFZO0FBRVosT0FBTyxNQUFNLE1BQU0sYUFBYSxDQUFBO0FBRWhDOzs7Ozs7R0FNRztBQUNILE1BQU0sVUFBVSxpQkFBaUIsQ0FBQyxDQUFDLEVBQUUsQ0FBQztJQUNwQyxNQUFNLE9BQU8sR0FBRyxNQUFNLENBQUMsSUFBSSxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFBO0lBQ3RDLE1BQU0sT0FBTyxHQUFHLE1BQU0sQ0FBQyxJQUFJLENBQUMsTUFBTSxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUE7SUFFdEMsSUFBSSxPQUFPLENBQUMsTUFBTSxLQUFLLE9BQU8sQ0FBQyxNQUFNO1FBQUUsT0FBTyxLQUFLLENBQUE7SUFFbkQsT0FBTyxNQUFNLENBQUMsZUFBZSxDQUFDLE9BQU8sRUFBRSxPQUFPLENBQUMsQ0FBQTtBQUNqRCxDQUFDO0FBRUQ7Ozs7R0FJRztBQUNILE1BQU0sVUFBVSxXQUFXLENBQUMsT0FBTztJQUNqQyxNQUFNLE1BQU0sR0FBRyxPQUFPLENBQUMsTUFBTSxDQUFDLGVBQWUsQ0FBQyxDQUFBO0lBRTlDLElBQUksT0FBTyxNQUFNLEtBQUssUUFBUTtRQUFFLE9BQU8sSUFBSSxDQUFBO0lBRTNDLE1BQU0sS0FBSyxHQUFHLE1BQU0sQ0FBQyxLQUFLLENBQUMsa0JBQWtCLENBQUMsQ0FBQTtJQUU5QyxPQUFPLEtBQUssQ0FBQyxDQUFDLENBQUMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDLElBQUksRUFBRSxDQUFDLENBQUMsQ0FBQyxJQUFJLENBQUE7QUFDdkMsQ0FBQyIsInNvdXJjZXNDb250ZW50IjpbIi8vIEB0cy1jaGVja1xuXG5pbXBvcnQgY3J5cHRvIGZyb20gXCJub2RlOmNyeXB0b1wiXG5cbi8qKlxuICogQ29uc3RhbnQtdGltZSBjb21wYXJpc29uIHNvIHRva2VuIGNoZWNrcyBkb24ndCBsZWFrIGxlbmd0aC9jb250ZW50cyB0aHJvdWdoXG4gKiB0aW1pbmcuIFJldHVybnMgZmFsc2UgZm9yIGRpZmZlcmluZyBsZW5ndGhzIGJlZm9yZSB0aGUgdGltaW5nLXNhZmUgY29tcGFyZS5cbiAqIEBwYXJhbSB7c3RyaW5nfSBhIC0gRmlyc3QgdmFsdWUuXG4gKiBAcGFyYW0ge3N0cmluZ30gYiAtIFNlY29uZCB2YWx1ZS5cbiAqIEByZXR1cm5zIHtib29sZWFufSAtIFdoZXRoZXIgdGhlIHZhbHVlcyBhcmUgZXF1YWwuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBjb25zdGFudFRpbWVFcXVhbChhLCBiKSB7XG4gIGNvbnN0IGJ1ZmZlckEgPSBCdWZmZXIuZnJvbShTdHJpbmcoYSkpXG4gIGNvbnN0IGJ1ZmZlckIgPSBCdWZmZXIuZnJvbShTdHJpbmcoYikpXG5cbiAgaWYgKGJ1ZmZlckEubGVuZ3RoICE9PSBidWZmZXJCLmxlbmd0aCkgcmV0dXJuIGZhbHNlXG5cbiAgcmV0dXJuIGNyeXB0by50aW1pbmdTYWZlRXF1YWwoYnVmZmVyQSwgYnVmZmVyQilcbn1cblxuLyoqXG4gKiBFeHRyYWN0cyB0aGUgYmVhcmVyIHRva2VuIGZyb20gdGhlIEF1dGhvcml6YXRpb24gaGVhZGVyIG9mIGEgcmVxdWVzdC5cbiAqIEBwYXJhbSB7aW1wb3J0KFwiLi4vaHR0cC1zZXJ2ZXIvY2xpZW50L3JlcXVlc3QuanNcIikuZGVmYXVsdCB8IGltcG9ydChcIi4uL2h0dHAtc2VydmVyL2NsaWVudC93ZWJzb2NrZXQtcmVxdWVzdC5qc1wiKS5kZWZhdWx0fSByZXF1ZXN0IC0gUmVxdWVzdCBvYmplY3QuXG4gKiBAcmV0dXJucyB7c3RyaW5nIHwgbnVsbH0gLSBCZWFyZXIgdG9rZW4gZnJvbSB0aGUgQXV0aG9yaXphdGlvbiBoZWFkZXIsIGlmIGFueS5cbiAqL1xuZXhwb3J0IGZ1bmN0aW9uIGJlYXJlclRva2VuKHJlcXVlc3QpIHtcbiAgY29uc3QgaGVhZGVyID0gcmVxdWVzdC5oZWFkZXIoXCJhdXRob3JpemF0aW9uXCIpXG5cbiAgaWYgKHR5cGVvZiBoZWFkZXIgIT09IFwic3RyaW5nXCIpIHJldHVybiBudWxsXG5cbiAgY29uc3QgbWF0Y2ggPSBoZWFkZXIubWF0Y2goL15CZWFyZXJcXHMrKC4rKSQvaSlcblxuICByZXR1cm4gbWF0Y2ggPyBtYXRjaFsxXS50cmltKCkgOiBudWxsXG59XG4iXX0=

package/build/src/utils/mount-prefix.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Normalizes a mount prefix: ensures a leading slash and strips any trailing
+ * slash so `/velocious/jobs/` and `/velocious/jobs` behave identically.
+ * @param {string} at - Raw mount prefix.
+ * @returns {string} - Normalized prefix.
+ */
+export function normalizeMountPrefix(at: string): string;
+/**
+ * Extracts the request sub-path under a normalized mount prefix, or null when
+ * the path is outside the mount. A root mount (`/`) treats the whole path as
+ * the sub-path.
+ * @param {object} args - Options.
+ * @param {string} args.prefix - Normalized mount prefix.
+ * @param {string} args.path - Request path without query string.
+ * @returns {string | null} - Sub-path ("/" for the bare prefix) or null.
+ */
+export function mountSubPath({ prefix, path }: {
+    prefix: string;
+    path: string;
+}): string | null;
+//# sourceMappingURL=mount-prefix.d.ts.map

package/build/src/utils/mount-prefix.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-prefix.d.ts","sourceRoot":"","sources":["../../../src/utils/mount-prefix.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,yCAHW,MAAM,GACJ,MAAM,CAYlB;AAED;;;;;;;;GAQG;AACH,+CAJG;IAAqB,MAAM,EAAnB,MAAM;IACO,IAAI,EAAjB,MAAM;CACd,GAAU,MAAM,GAAG,IAAI,CAQzB"}

package/build/src/utils/mount-prefix.js

@@ -0,0 +1,35 @@
+// @ts-check
+/**
+ * Normalizes a mount prefix: ensures a leading slash and strips any trailing
+ * slash so `/velocious/jobs/` and `/velocious/jobs` behave identically.
+ * @param {string} at - Raw mount prefix.
+ * @returns {string} - Normalized prefix.
+ */
+export function normalizeMountPrefix(at) {
+    if (typeof at !== "string" || !at.startsWith("/")) {
+        throw new Error(`mount requires an 'at' path starting with '/', got: ${String(at)}`);
+    }
+    if (at.length > 1 && at.endsWith("/")) {
+        return at.slice(0, -1);
+    }
+    return at;
+}
+/**
+ * Extracts the request sub-path under a normalized mount prefix, or null when
+ * the path is outside the mount. A root mount (`/`) treats the whole path as
+ * the sub-path.
+ * @param {object} args - Options.
+ * @param {string} args.prefix - Normalized mount prefix.
+ * @param {string} args.path - Request path without query string.
+ * @returns {string | null} - Sub-path ("/" for the bare prefix) or null.
+ */
+export function mountSubPath({ prefix, path }) {
+    if (prefix === "/")
+        return path;
+    if (path === prefix)
+        return "/";
+    if (path.startsWith(`${prefix}/`))
+        return path.slice(prefix.length);
+    return null;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibW91bnQtcHJlZml4LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vc3JjL3V0aWxzL21vdW50LXByZWZpeC5qcyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxZQUFZO0FBRVo7Ozs7O0dBS0c7QUFDSCxNQUFNLFVBQVUsb0JBQW9CLENBQUMsRUFBRTtJQUNyQyxJQUFJLE9BQU8sRUFBRSxLQUFLLFFBQVEsSUFBSSxDQUFDLEVBQUUsQ0FBQyxVQUFVLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUNsRCxNQUFNLElBQUksS0FBSyxDQUFDLHVEQUF1RCxNQUFNLENBQUMsRUFBRSxDQUFDLEVBQUUsQ0FBQyxDQUFBO0lBQ3RGLENBQUM7SUFFRCxJQUFJLEVBQUUsQ0FBQyxNQUFNLEdBQUcsQ0FBQyxJQUFJLEVBQUUsQ0FBQyxRQUFRLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQztRQUN0QyxPQUFPLEVBQUUsQ0FBQyxLQUFLLENBQUMsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDLENBQUE7SUFDeEIsQ0FBQztJQUVELE9BQU8sRUFBRSxDQUFBO0FBQ1gsQ0FBQztBQUVEOzs7Ozs7OztHQVFHO0FBQ0gsTUFBTSxVQUFVLFlBQVksQ0FBQyxFQUFDLE1BQU0sRUFBRSxJQUFJLEVBQUM7SUFDekMsSUFBSSxNQUFNLEtBQUssR0FBRztRQUFFLE9BQU8sSUFBSSxDQUFBO0lBQy9CLElBQUksSUFBSSxLQUFLLE1BQU07UUFBRSxPQUFPLEdBQUcsQ0FBQTtJQUMvQixJQUFJLElBQUksQ0FBQyxVQUFVLENBQUMsR0FBRyxNQUFNLEdBQUcsQ0FBQztRQUFFLE9BQU8sSUFBSSxDQUFDLEtBQUssQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLENBQUE7SUFFbkUsT0FBTyxJQUFJLENBQUE7QUFDYixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gQHRzLWNoZWNrXG5cbi8qKlxuICogTm9ybWFsaXplcyBhIG1vdW50IHByZWZpeDogZW5zdXJlcyBhIGxlYWRpbmcgc2xhc2ggYW5kIHN0cmlwcyBhbnkgdHJhaWxpbmdcbiAqIHNsYXNoIHNvIGAvdmVsb2Npb3VzL2pvYnMvYCBhbmQgYC92ZWxvY2lvdXMvam9ic2AgYmVoYXZlIGlkZW50aWNhbGx5LlxuICogQHBhcmFtIHtzdHJpbmd9IGF0IC0gUmF3IG1vdW50IHByZWZpeC5cbiAqIEByZXR1cm5zIHtzdHJpbmd9IC0gTm9ybWFsaXplZCBwcmVmaXguXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBub3JtYWxpemVNb3VudFByZWZpeChhdCkge1xuICBpZiAodHlwZW9mIGF0ICE9PSBcInN0cmluZ1wiIHx8ICFhdC5zdGFydHNXaXRoKFwiL1wiKSkge1xuICAgIHRocm93IG5ldyBFcnJvcihgbW91bnQgcmVxdWlyZXMgYW4gJ2F0JyBwYXRoIHN0YXJ0aW5nIHdpdGggJy8nLCBnb3Q6ICR7U3RyaW5nKGF0KX1gKVxuICB9XG5cbiAgaWYgKGF0Lmxlbmd0aCA+IDEgJiYgYXQuZW5kc1dpdGgoXCIvXCIpKSB7XG4gICAgcmV0dXJuIGF0LnNsaWNlKDAsIC0xKVxuICB9XG5cbiAgcmV0dXJuIGF0XG59XG5cbi8qKlxuICogRXh0cmFjdHMgdGhlIHJlcXVlc3Qgc3ViLXBhdGggdW5kZXIgYSBub3JtYWxpemVkIG1vdW50IHByZWZpeCwgb3IgbnVsbCB3aGVuXG4gKiB0aGUgcGF0aCBpcyBvdXRzaWRlIHRoZSBtb3VudC4gQSByb290IG1vdW50IChgL2ApIHRyZWF0cyB0aGUgd2hvbGUgcGF0aCBhc1xuICogdGhlIHN1Yi1wYXRoLlxuICogQHBhcmFtIHtvYmplY3R9IGFyZ3MgLSBPcHRpb25zLlxuICogQHBhcmFtIHtzdHJpbmd9IGFyZ3MucHJlZml4IC0gTm9ybWFsaXplZCBtb3VudCBwcmVmaXguXG4gKiBAcGFyYW0ge3N0cmluZ30gYXJncy5wYXRoIC0gUmVxdWVzdCBwYXRoIHdpdGhvdXQgcXVlcnkgc3RyaW5nLlxuICogQHJldHVybnMge3N0cmluZyB8IG51bGx9IC0gU3ViLXBhdGggKFwiL1wiIGZvciB0aGUgYmFyZSBwcmVmaXgpIG9yIG51bGwuXG4gKi9cbmV4cG9ydCBmdW5jdGlvbiBtb3VudFN1YlBhdGgoe3ByZWZpeCwgcGF0aH0pIHtcbiAgaWYgKHByZWZpeCA9PT0gXCIvXCIpIHJldHVybiBwYXRoXG4gIGlmIChwYXRoID09PSBwcmVmaXgpIHJldHVybiBcIi9cIlxuICBpZiAocGF0aC5zdGFydHNXaXRoKGAke3ByZWZpeH0vYCkpIHJldHVybiBwYXRoLnNsaWNlKHByZWZpeC5sZW5ndGgpXG5cbiAgcmV0dXJuIG51bGxcbn1cbiJdfQ==

package/build/sync/signed-sync-envelope-replay-service.js

@@ -0,0 +1,342 @@
+// @ts-check
+
+import SyncEnvelopeReplayService from "./sync-envelope-replay-service.js"
+import {frontendModelSyncManifestForBackendProjects} from "../frontend-models/resource-definition.js"
+import {verifyOfflineGrant} from "./offline-grant.js"
+import {mutationIdempotencyKey, verifySignedMutation} from "./device-identity.js"
+import VelociousError from "../velocious-error.js"
+
+/**
+ * @typedef {import("./device-identity.js").SignedSyncMutation} SignedSyncMutation
+ * @typedef {import("./offline-grant.js").SignedOfflineGrant} SignedOfflineGrant
+ */
+
+/**
+ * Sync-envelope replay service that authenticates via backend-signed device
+ * certificates and signed offline grants instead of online session tokens.
+ *
+ * This is the generic Velocious primitive for long-offline and peer-forwarded
+ * mutations: the HTTP uploader may differ from the mutation actor, but replay
+ * authority is derived from the signed envelope and grant, not the uploader's
+ * session.
+ *
+ * Every mutation is validated against the current sync manifest (the same
+ * contract as the controller's sync replay endpoint): the model and operation
+ * must be enabled in the current manifest, the grant resource entry must be
+ * enabled and list the operation, and the grant policy hash must equal both the
+ * mutation policy hash and the current manifest policy hash. Routed resources
+ * are authorized through an actor/grant-scoped ability built by the configured
+ * `abilityFactory`; without one, routed signed replay fails closed.
+ */
+export default class SignedSyncEnvelopeReplayService extends SyncEnvelopeReplayService {
+  /**
+   * Creates a signed sync-envelope replay service.
+   * @param {object} args - Constructor arguments.
+   * @param {import("./device-identity.js").SyncJsonWebKey} args.backendPublicKey - Backend public key used to verify device certificates.
+   * @param {Array<import("./offline-grant.js").OfflineGrantSigningKey>} [args.offlineGrantSigningKeys] - Offline-grant verification keys.
+   * @param {(userId: string) => Promise<{id: () => string} | null>} [args.actorLookup] - Optional lookup from grant user id to an actor object with an `id()` method. Defaults to a wrapper around the grant user id.
+   * @param {(args: {actor: ?, configuration: import("../configuration.js").default | null, grant: import("./offline-grant.js").OfflineGrant}) => Promise<import("../authorization/ability.js").default | null> | import("../authorization/ability.js").default | null} [args.abilityFactory] - Builds the actor/grant-scoped ability used to authorize routed resources. Required for routed signed replay; without it every routed sync fails closed.
+   * @param {Record<string, ?>} [args.rest] - Remaining arguments forwarded to {@link SyncEnvelopeReplayService}.
+   */
+  constructor({abilityFactory, backendPublicKey, offlineGrantSigningKeys, actorLookup, ...rest}) {
+    super({
+      actorForeignKeyColumn: "authenticationTokenId",
+      ...rest
+    })
+
+    if (!backendPublicKey) throw new Error("SignedSyncEnvelopeReplayService requires backendPublicKey")
+
+    this.abilityFactory = abilityFactory || null
+    this.backendPublicKey = backendPublicKey
+    this.offlineGrantSigningKeys = offlineGrantSigningKeys || []
+    this.actorLookup = actorLookup || null
+  }
+
+  /**
+   * Verifies signed mutations and then runs the generic replay loop over the
+   * derived sync envelopes. Verified actor, grant, and derived syncs are kept
+   * in the request-local `requestState` object so concurrent replay calls on
+   * one service instance cannot cross their authentication state.
+   * @param {Record<string, ?>} params - Request params.
+   * @param {Record<string, ?>} [requestState] - Request-local state shared with the base replay hooks.
+   * @returns {Promise<{syncs: Array<Record<string, ?>>}>} Replay response.
+   */
+  async replay(params, requestState = {}) {
+    const verified = await this.verifyAndTransformSignedReplay(params)
+
+    requestState.signedReplayActor = verified.actor
+    requestState.signedReplayGrant = verified.grant
+    requestState.signedReplaySyncs = verified.syncs
+
+    const result = await super.replay(params, requestState)
+
+    return {
+      syncs: result.syncs.map((syncResponse, index) => {
+        const {id: _id, ...rest} = syncResponse
+        const idempotencyKey = verified.syncs[index]?.idempotencyKey
+
+        return idempotencyKey ? {...rest, idempotencyKey} : syncResponse
+      })
+    }
+  }
+
+  /**
+   * Returns the verified actor prepared during {@link SignedSyncEnvelopeReplayService#replay}.
+   * @param {Record<string, ?>} _params - Request params.
+   * @param {Record<string, ?>} requestState - Request-local state.
+   * @returns {Promise<{authenticated: true, actor: ?} | {authenticated: false, errorCode: string, errorMessage: string}>} Auth result.
+   */
+  async authenticateReplay(_params, requestState) {
+    const actor = requestState?.signedReplayActor
+
+    if (!actor) {
+      return {
+        authenticated: false,
+        errorCode: "missing-signed-replay",
+        errorMessage: "Expected a pre-verified signed replay"
+      }
+    }
+
+    return {actor, authenticated: true}
+  }
+
+  /**
+   * Returns the sync envelopes derived from the verified signed mutations.
+   * @param {Record<string, ?>} _params - Request params.
+   * @param {Record<string, ?>} requestState - Request-local state.
+   * @returns {Array<Record<string, ?>>} Sync envelopes.
+   */
+  replaySyncs(_params, requestState) {
+    return requestState?.signedReplaySyncs || []
+  }
+
+  /**
+   * Builds the replay context carrying the verified signed actor and grant
+   * (with its scopes) plus the offline runtime marker, so resource hooks and
+   * ability factories authorize against the signer instead of the uploader.
+   * @param {{actor: ?, params: Record<string, ?>, requestState: Record<string, ?>}} args - Actor, request params, and request-local state.
+   * @returns {Promise<Record<string, ?>>} Replay context.
+   */
+  async buildReplayContext({actor, requestState}) {
+    const grant = /** @type {import("./offline-grant.js").OfflineGrant | undefined} */ (requestState?.signedReplayGrant)
+
+    return {
+      currentUser: actor,
+      offlineGrant: grant,
+      offlineGrantScopes: grant?.scopes || {},
+      resourceRuntime: "offline"
+    }
+  }
+
+  /**
+   * Derives the routed-resource ability from the verified signed actor and
+   * grant through the configured `abilityFactory`. The constructor-wide
+   * uploader ability is never used for signed replay: without a factory (or a
+   * factory result) every routed sync fails closed with a client-safe error.
+   * @param {{actor: ?, context: Record<string, ?>}} args - Verified actor and replay context.
+   * @returns {Promise<{ability: import("../authorization/ability.js").default, abilityContext: Record<string, ?>}>} Scoped ability and resource context.
+   */
+  async replayAbilityFor({actor, context}) {
+    const grant = /** @type {import("./offline-grant.js").OfflineGrant} */ (context.offlineGrant)
+    const ability = this.abilityFactory
+      ? await this.abilityFactory({actor, configuration: this.configuration, grant})
+      : null
+
+    if (!ability) {
+      throw VelociousError.safe("Signed sync replay requires an actor/grant-scoped abilityFactory.", {code: "signed-replay-ability-missing"})
+    }
+
+    return {ability, abilityContext: context}
+  }
+
+  /**
+   * Verifies every signed mutation, its offline grant, and the actor/grant
+   * consistency, then transforms the envelopes into the sync format the base
+   * replay service understands.
+   * @param {Record<string, ?>} params - Request params.
+   * @returns {Promise<{actor: ?, grant: import("./offline-grant.js").OfflineGrant, syncs: Array<Record<string, ?>>}>} Verified actor, common grant, and derived syncs.
+   */
+  async verifyAndTransformSignedReplay(params) {
+    const rawEntries = Array.isArray(params.signedMutations) ? params.signedMutations : []
+
+    if (rawEntries.length === 0) {
+      throw VelociousError.safe("Expected signed mutations.", {code: "missing-signed-mutations"})
+    }
+
+    const syncManifest = this.configuration
+      ? frontendModelSyncManifestForBackendProjects(this.configuration.getBackendProjects())
+      : {}
+
+    /** @type {string | null} */
+    let grantUserId = null
+    /** @type {string | null} */
+    let grantDeviceId = null
+    /** @type {string | null} */
+    let grantId = null
+    /** @type {import("./offline-grant.js").OfflineGrant | null} */
+    let commonGrant = null
+    /** @type {Array<Record<string, ?>>} */
+    const syncs = []
+
+    for (const rawEntry of rawEntries) {
+      if (!rawEntry || typeof rawEntry !== "object") {
+        throw VelociousError.safe("Invalid signed mutation entry.", {code: "invalid-signed-mutation-entry"})
+      }
+
+      const signedMutation = /** @type {SignedSyncMutation} */ (rawEntry.signedMutation)
+      const signedOfflineGrant = /** @type {SignedOfflineGrant} */ (rawEntry.signedOfflineGrant)
+
+      if (!signedMutation || !signedOfflineGrant) {
+        throw VelociousError.safe("Expected signed mutation and signed offline grant.", {code: "incomplete-signed-mutation"})
+      }
+
+      const mutation = await verifySignedMutation({
+        backendPublicKey: this.backendPublicKey,
+        signedMutation
+      })
+      const offlineGrant = await verifyOfflineGrant({
+        signedGrant: signedOfflineGrant,
+        signingKeys: this.offlineGrantSigningKeys
+      })
+
+      if (mutation.actorUserId !== offlineGrant.userId) {
+        throw VelociousError.safe("Mutation actor does not match offline grant.", {code: "actor-grant-mismatch"})
+      }
+
+      if (mutation.actorDeviceId !== offlineGrant.deviceId) {
+        throw VelociousError.safe("Mutation device does not match offline grant.", {code: "device-grant-mismatch"})
+      }
+
+      if (mutation.offlineGrantId !== offlineGrant.grantId) {
+        throw VelociousError.safe("Mutation grant id does not match offline grant.", {code: "grant-id-mismatch"})
+      }
+
+      if (grantUserId === null) {
+        grantUserId = offlineGrant.userId
+        grantDeviceId = offlineGrant.deviceId
+        grantId = offlineGrant.grantId
+        commonGrant = offlineGrant
+      } else if (
+        grantUserId !== offlineGrant.userId ||
+        grantDeviceId !== offlineGrant.deviceId ||
+        grantId !== offlineGrant.grantId
+      ) {
+        throw VelociousError.safe("All signed mutations in a batch must share actor, device, and grant.", {code: "mixed-signed-replay-batch"})
+      }
+
+      this.validateCurrentSyncPolicy({mutation, syncManifest})
+      this.validateGrantAgainstSyncPolicy({mutation, offlineGrant, syncManifest})
+
+      const sync = this.syncFromSignedMutation({mutation})
+      const idempotencyKey = mutationIdempotencyKey({mutation})
+
+      syncs.push({...sync, id: idempotencyKey, idempotencyKey})
+    }
+
+    if (!grantUserId || !commonGrant) {
+      throw VelociousError.safe("Could not resolve signed replay actor.", {code: "missing-signed-replay-actor"})
+    }
+
+    if (this.actorLookup) {
+      const lookedUpActor = await this.actorLookup(grantUserId)
+
+      if (!lookedUpActor) {
+        throw VelociousError.safe("Signed replay actor not found.", {code: "signed-replay-actor-missing"})
+      }
+
+      return {actor: lookedUpActor, grant: commonGrant, syncs}
+    }
+
+    return {actor: {id: () => grantUserId}, grant: commonGrant, syncs}
+  }
+
+  /**
+   * Validates a mutation against the current sync manifest: the model and the
+   * operation must be enabled, and the mutation's policy hash must match the
+   * current manifest policy hash.
+   * @param {{mutation: import("./device-identity.js").SyncMutation, syncManifest: Record<string, import("../configuration-types.js").NormalizedFrontendModelResourceSyncConfiguration>}} args - Validation args.
+   * @returns {void} Throws a client-safe error when the current policy denies the mutation.
+   */
+  validateCurrentSyncPolicy({mutation, syncManifest}) {
+    const syncResource = syncManifest[mutation.model]
+
+    if (!syncResource) {
+      throw VelociousError.safe(`Sync replay model is not enabled: ${mutation.model}.`, {code: "sync-replay-model-not-enabled"})
+    }
+
+    if (!syncResource.operations.includes(mutation.operation)) {
+      throw VelociousError.safe(`Sync replay operation is not enabled for ${mutation.model}: ${mutation.operation}.`, {code: "sync-replay-operation-not-enabled"})
+    }
+
+    if (syncResource.policyHash !== mutation.policyHash) {
+      throw VelociousError.safe(`Sync replay policy hash mismatch for ${mutation.model}.`, {code: "sync-replay-policy-hash-mismatch"})
+    }
+  }
+
+  /**
+   * Validates the verified offline grant against the current sync policy, the
+   * same contract as the controller's sync replay endpoint: the grant resource
+   * entry must be a normalized manifest entry (enabled with an operations list
+   * and the current policy hash), it must list the mutation operation, and its
+   * policy hash must equal both the mutation and current manifest hashes.
+   * Legacy array/true grant-resource shortcuts are not the bootstrap contract
+   * and never authorize a mutation.
+   * @param {{mutation: import("./device-identity.js").SyncMutation, offlineGrant: import("./offline-grant.js").OfflineGrant, syncManifest: Record<string, import("../configuration-types.js").NormalizedFrontendModelResourceSyncConfiguration>}} args - Validation args.
+   * @returns {void} Throws a client-safe error when the grant does not authorize the mutation.
+   */
+  validateGrantAgainstSyncPolicy({mutation, offlineGrant, syncManifest}) {
+    const grantResource = /** @type {Record<string, ?> | undefined} */ (offlineGrant.resources[mutation.model])
+    const grantOperations = Array.isArray(grantResource?.operations) ? grantResource.operations : []
+    const grantPolicyHash = grantResource?.policyHash
+
+    if (!grantResource || grantResource.enabled !== true) {
+      throw VelociousError.safe(`Offline grant does not authorize ${mutation.model}.`, {code: "offline-grant-denied"})
+    }
+
+    if (!grantOperations.includes(mutation.operation)) {
+      throw VelociousError.safe(`Offline grant does not authorize ${mutation.model}: ${mutation.operation}.`, {code: "offline-grant-denied"})
+    }
+
+    if (grantPolicyHash !== mutation.policyHash || grantPolicyHash !== syncManifest[mutation.model]?.policyHash) {
+      throw VelociousError.safe(`Offline grant policy hash mismatch for ${mutation.model}.`, {code: "offline-grant-policy-hash-mismatch"})
+    }
+
+    if (!offlineGrant.scopes || typeof offlineGrant.scopes !== "object" || Array.isArray(offlineGrant.scopes)) {
+      throw VelociousError.safe("Offline grant scopes are invalid.", {code: "offline-grant-scopes-invalid"})
+    }
+  }
+
+  /**
+   * Transforms a verified signed mutation into a generic sync envelope.
+   * @param {{mutation: import("./device-identity.js").SyncMutation}} args - Transform args.
+   * @returns {Record<string, ?>} Sync envelope.
+   */
+  syncFromSignedMutation({mutation}) {
+    const operation = mutation.operation
+    const attributes = mutation.attributes || {}
+    const payload = mutation.payload || {}
+    let resourceId
+    let data
+
+    if (operation === "create") {
+      resourceId = String(attributes.id)
+      data = {...attributes}
+    } else if (operation === "update") {
+      resourceId = String(payload.id)
+      data = {...attributes}
+    } else {
+      // Domain commands carry their target identity in `payload.id`.
+      resourceId = String(payload.id)
+      data = {...payload}
+      delete data.id
+    }
+
+    return {
+      clientUpdatedAt: mutation.occurredAt,
+      data,
+      resourceId,
+      resourceType: mutation.model,
+      syncType: operation
+    }
+  }
+}

package/build/sync/sync-envelope-replay-service.js

@@ -64,7 +64,7 @@ export default class SyncEnvelopeReplayService {
    * @param {(args: {mutation: ?, applyResult: ?}) => ?} [args.persistSerializedData] - Overrides the persisted data payload (object results are JSON stringified).
    * @param {(broadcast: {channel: string, params: Record<string, ?>, body: ?}) => Promise<void>} [args.broadcaster] - Delivers declarative broadcasts. Required when broadcasts are configured.
    * @param {SyncReplayBroadcast[]} [args.broadcasts] - Broadcasts fanned out by the default afterReplayMutation.
-   * @param {{getBackendProjects: () => import("../configuration-types.js").BackendProjectConfiguration[]}} [args.configuration] - Configuration whose frontend-model registry routes mutations to resource classes.
+   * @param {import("../configuration.js").default} [args.configuration] - Configuration whose frontend-model registry routes mutations to resource classes.
    * @param {Record<string, import("../configuration-types.js").FrontendModelResourceClassType | string>} [args.resourceTypeOverrides] - Per-resourceType routing overrides: a resource class, or a string alias resolved through the registry.
    * @param {import("../authorization/ability.js").default} [args.ability] - Ability scoping routed record lookups and create membership checks.
    * @param {Record<string, ?>} [args.abilityContext] - Ability context passed to routed resources.
@@ -116,10 +116,11 @@ export default class SyncEnvelopeReplayService {
   /**
    * Replays a sync batch.
    * @param {Record<string, ?>} params - Request params carrying authentication and syncs.
+   * @param {Record<string, ?>} [requestState] - Request-local state passed to authentication/sync extraction hooks; subclasses may use this to share pre-computed per-request data without instance mutation.
    * @returns {Promise<{syncs: Array<Record<string, ?>>, status?: string, errorCode?: string, errorMessage?: string}>} Replay response.
    */
-  async replay(params) {
-    const actorResult = await this.authenticateReplay(params)
+  async replay(params, requestState = {}) {
+    const actorResult = await this.authenticateReplay(params, requestState)
 
     if (!actorResult.authenticated) {
       return {
@@ -131,9 +132,9 @@ export default class SyncEnvelopeReplayService {
     }
 
     const syncResponses = []
-    const context = await this.buildReplayContext({actor: actorResult.actor, params})
+    const context = await this.buildReplayContext({actor: actorResult.actor, params, requestState})
 
-    for (const rawSync of this.replaySyncs(params)) {
+    for (const rawSync of this.replaySyncs(params, requestState)) {
       const normalizedResult = this.normalizeReplaySync(rawSync)
 
       if (!normalizedResult.ok) {
@@ -195,9 +196,10 @@ export default class SyncEnvelopeReplayService {
    * Defaults to a token-model lookup when `authenticationTokenModel` is
    * configured; otherwise apps override this hook.
    * @param {Record<string, ?>} params - Request params.
+   * @param {Record<string, ?>} [_requestState] - Request-local state populated by subclasses before the base replay loop runs.
    * @returns {Promise<{authenticated: true, actor: ?} | {authenticated: false, errorCode: string, errorMessage: string}>} Auth result.
    */
-  async authenticateReplay(params) {
+  async authenticateReplay(params, _requestState) {
     if (!this.authenticationTokenModel) {
       throw new Error("SyncEnvelopeReplayService.authenticateReplay must be implemented (or configure authenticationTokenModel)")
     }
@@ -219,7 +221,7 @@ export default class SyncEnvelopeReplayService {
 
   /**
    * Builds per-batch mutable context for caches shared across sync items.
-   * @param {{actor: ?, params: Record<string, ?>}} _args - Actor and request params.
+   * @param {{actor: ?, params: Record<string, ?>, requestState: Record<string, ?>}} _args - Actor, request params, and request-local state.
    * @returns {Promise<Record<string, ?>>} Replay context.
    */
   async buildReplayContext(_args) {
@@ -229,9 +231,10 @@ export default class SyncEnvelopeReplayService {
   /**
    * Returns raw sync entries from request params.
    * @param {Record<string, ?>} params - Request params.
+   * @param {Record<string, ?>} [_requestState] - Request-local state populated by subclasses before the base replay loop runs.
    * @returns {Array<?>} Raw sync entries.
    */
-  replaySyncs(params) {
+  replaySyncs(params, _requestState) {
     return Array.isArray(params.syncs) ? params.syncs : []
   }
 
@@ -451,20 +454,35 @@ export default class SyncEnvelopeReplayService {
     }
   }
 
+  /**
+   * Resolves the ability and resource context used to authorize routed
+   * resources. Defaults to the constructor-wide ability/abilityContext;
+   * subclasses (signed replay) override this to derive authorization from a
+   * verified actor/grant instead of uploader-global state.
+   * @param {{actor: ?, context: Record<string, ?>}} _args - Replay actor and batch context.
+   * @returns {Promise<{ability: import("../authorization/ability.js").default | undefined, abilityContext: Record<string, ?>}>} Ability and resource context.
+   */
+  async replayAbilityFor(_args) {
+    return {ability: this.ability || undefined, abilityContext: this.abilityContext || {}}
+  }
+
   /**
    * Builds the routed resource instance handling one mutation.
    * @param {object} args - Options.
+   * @param {?} args.actor - Replay actor.
+   * @param {Record<string, ?>} args.context - Replay context.
    * @param {import("./sync-envelope-replay-service.js").SyncReplayMutation} args.mutation - Normalized replay mutation.
    * @param {SyncReplayResourceRegistration} args.registration - Resolved resource registration.
-   * @returns {import("../frontend-model-resource/base-resource.js").default} Routed resource instance.
+   * @returns {Promise<import("../frontend-model-resource/base-resource.js").default>} Routed resource instance.
    */
-  buildReplayResource({mutation, registration}) {
+  async buildReplayResource({actor, context, mutation, registration}) {
     const ResourceClass = registration.resourceClass
+    const {ability, abilityContext} = await this.replayAbilityFor({actor, context})
 
     return new ResourceClass({
-      ability: this.ability || undefined,
-      context: this.abilityContext || {},
-      locals: this.locals || {},
+      ability,
+      context: abilityContext,
+      locals: {...(this.locals || {}), ...(this.configuration ? {configuration: this.configuration} : {})},
       modelName: registration.modelName,
       params: mutation.data,
       ...(registration.resourceConfiguration ? {resourceConfiguration: registration.resourceConfiguration} : {})
@@ -480,14 +498,14 @@ export default class SyncEnvelopeReplayService {
    * @param {{actor: ?, context: Record<string, ?>, existingSync: ?, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} args - Actor, batch context, existing sync row, and mutation.
    * @returns {Promise<Record<string, ?>>} Apply result with record, created/deleted flags, and afterSyncApply extras.
    */
-  async applyRoutedReplayMutation({context, existingSync, mutation}) {
+  async applyRoutedReplayMutation({actor, context, existingSync, mutation}) {
     const registration = this.replayResourceRegistration(mutation.resourceType)
 
     if (!registration) {
       throw VelociousError.safe(`Unknown sync resource type: ${mutation.resourceType}.`, {code: "unknown-resource-type"})
     }
 
-    const resource = this.buildReplayResource({mutation, registration})
+    const resource = await this.buildReplayResource({actor, context, mutation, registration})
     const customApplyResult = await resource.applySync({context, existingSync, mutation})
 
     if (customApplyResult !== null) return customApplyResult
@@ -500,9 +518,86 @@ export default class SyncEnvelopeReplayService {
 
     if (mutation.syncType === "delete") return await this.applyRoutedReplayDelete({mutation, resource})
 
+    const commandApplyResult = await this.applyRoutedReplayCommand({context, mutation, resource})
+
+    if (commandApplyResult !== null) return commandApplyResult
+
     return await this.applyRoutedReplayUpsert({context, mutation, resource})
   }
 
+  /**
+   * Dispatches a routed sync mutation whose syncType matches a resource-declared
+   * custom command. Returns null when the mutation is not a command so the
+   * caller can fall through to the default upsert path.
+   * @param {{context: Record<string, ?>, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation, resource: import("../frontend-model-resource/base-resource.js").default}} args - Command dispatch args.
+   * @returns {Promise<Record<string, ?> | null>} Command apply result or null.
+   */
+  async applyRoutedReplayCommand({context, mutation, resource}) {
+    const commandConfig = this.resourceCommandConfig(resource)
+    const commandMethodName = this.commandMethodNameForSyncType({commandConfig, syncType: mutation.syncType})
+
+    if (!commandMethodName) return null
+
+    const commandMethod = resource.resourceMethod(commandMethodName)
+
+    if (!commandMethod) {
+      throw VelociousError.safe(`Sync command handler missing for: ${mutation.resourceType}.${mutation.syncType}.`, {code: "sync-command-handler-missing"})
+    }
+
+    const args = this.commandArgsForMutation({commandConfig, commandMethodName, mutation})
+    const result = await commandMethod.method.call(commandMethod.resource, args)
+
+    const afterExtras = await resource.afterSyncApply({context, created: false, mutation, record: null})
+    const resultObject = result && typeof result === "object" && !Array.isArray(result) ? result : {}
+
+    return {commandResult: result, created: false, deleted: false, record: null, ...resultObject, ...afterExtras}
+  }
+
+  /**
+   * Resolves the custom-command configuration declared on a routed resource.
+   * @param {import("../frontend-model-resource/base-resource.js").default} resource - Routed resource instance.
+   * @returns {{collectionCommands: Record<string, string>, memberCommands: Record<string, string>}} Command config.
+   */
+  resourceCommandConfig(resource) {
+    const config = /** @type {Record<string, ?>} */ (resource.resourceConfigurationValue || {})
+
+    return {
+      collectionCommands: config.collectionCommands || {},
+      memberCommands: config.memberCommands || {}
+    }
+  }
+
+  /**
+   * Resolves the resource method name for a syncType when it names a declared
+   * custom command.
+   * @param {{commandConfig: {collectionCommands: Record<string, string>, memberCommands: Record<string, string>}, syncType: string}} args - Lookup args.
+   * @returns {string | null} Method name or null.
+   */
+  commandMethodNameForSyncType({commandConfig, syncType}) {
+    if (commandConfig.memberCommands[syncType]) return syncType
+    if (commandConfig.collectionCommands[syncType]) return syncType
+
+    return null
+  }
+
+  /**
+   * Builds the arguments object passed to a resource command method. Member
+   * commands receive the envelope's resourceId as `id`; the envelope identity
+   * is assigned after the payload so a payload `id` can never retarget the
+   * command away from the resource the authorization hooks approved.
+   * @param {{commandConfig: {collectionCommands: Record<string, string>, memberCommands: Record<string, string>}, commandMethodName: string, mutation: import("./sync-envelope-replay-service.js").SyncReplayMutation}} args - Args builder args.
+   * @returns {Record<string, ?>} Command method arguments.
+   */
+  commandArgsForMutation({commandConfig, commandMethodName, mutation}) {
+    const isMember = commandConfig.memberCommands[commandMethodName] !== undefined
+
+    if (isMember) {
+      return {...mutation.data, id: mutation.resourceId}
+    }
+
+    return {...mutation.data}
+  }
+
   /**
    * Applies a routed delete mutation. The record is marked as a server apply
    * for the duration of the replay-owned destroy - an active SyncPublisher