velocious 1.0.474 → 1.0.476

package/build/database/query/remove-index-base.js

@@ -0,0 +1,39 @@
+// @ts-check
+
+import QueryBase from "./base.js"
+
+/**
+ * RemoveIndexBaseArgsType type.
+ * @typedef {object} RemoveIndexBaseArgsType
+ * @property {import("../drivers/base.js").default} driver - Database driver used to generate SQL.
+ * @property {string} name - Index name to drop.
+ * @property {string} tableName - Name of the table the index belongs to.
+ */
+
+export default class VelociousDatabaseQueryRemoveIndexBase extends QueryBase {
+  /**
+   * Runs constructor.
+   * @param {RemoveIndexBaseArgsType} args - Options object.
+   */
+  constructor({driver, name, tableName}) {
+    super({driver})
+    this.name = name
+    this.tableName = tableName
+  }
+
+  /**
+   * Runs to sqls.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async toSQLs() {
+    const databaseType = this.getDriver().getType()
+    const options = this.getOptions()
+    let sql = `DROP INDEX ${options.quoteIndexName(this.name)}`
+
+    if (databaseType == "mssql" || databaseType == "mysql") {
+      sql += ` ON ${options.quoteTableName(this.tableName)}`
+    }
+
+    return [sql]
+  }
+}

package/build/database/record/index.js

@@ -690,11 +690,14 @@ class VelociousDatabaseRecord {
         return await this.relationshipOrLoad(relationshipName, {preloadTranslations: true})
       }
 
-      prototype[`set${inflection.camelize(relationshipName)}`] = function(/** @type {?} */ model) {
+      prototype[`set${inflection.camelize(relationshipName)}`] = function(/** @type {VelociousDatabaseRecord | null | undefined} */ model) {
         const relationship = this.getRelationshipByName(relationshipName)
+        const foreignKeyValue = this._belongsToForeignKeyValue({model, relationship})
 
-        relationship.setLoaded(model)
+        relationship.setLoaded(model || undefined)
+        relationship.setPreloaded(true)
         relationship.setDirty(true)
+        this._setColumnAttribute(relationship.getForeignKey(), foreignKeyValue)
       }
     } else if (actualData.type == "hasMany") {
       relationship = new HasManyRelationship(actualData)
@@ -1783,6 +1786,20 @@ class VelociousDatabaseRecord {
     return loaded.readColumn(relationship.getPrimaryKey()) == normalizedValue
   }
 
+  /**
+   * Returns the foreign key value for a belongs-to relationship assignment.
+   * @param {object} args - Relationship assignment arguments.
+   * @param {VelociousDatabaseRecord | null | undefined} args.model - Assigned model.
+   * @param {import("./instance-relationships/base.js").default} args.relationship - Belongs-to relationship instance.
+   * @returns {string | number | null | undefined} - Foreign key value for the assignment.
+   */
+  _belongsToForeignKeyValue({model, relationship}) {
+    if (model == null) return null
+    if (!(model instanceof VelociousDatabaseRecord)) throw new Error(`Unexpected model type: ${typeof model}`)
+
+    return /** @type {string | number | null | undefined} */ (model.readColumn(relationship.getPrimaryKey()))
+  }
+
   /**
    * Runs clear loaded belongs to relationship.
    * @param {?} relationship - Relationship instance.
@@ -2364,8 +2381,9 @@ class VelociousDatabaseRecord {
             await model.save()
 
             const foreignKey = this._relationshipForeignKeyAttribute(instanceRelationship)
+            const foreignKeyValue = this._belongsToForeignKeyValue({model, relationship: instanceRelationship})
 
-            this.setAttribute(foreignKey, model.id())
+            this.setAttribute(foreignKey, foreignKeyValue)
 
             instanceRelationship.setPreloaded(true)
             instanceRelationship.setDirty(false)
@@ -3801,14 +3819,12 @@ class VelociousDatabaseRecord {
         const relationship = this._instanceRelationships[relationshipName]
 
         if (relationship.getType() == "belongsTo" && relationship.getDirty()) {
-          const model = relationship.loaded()
+          const model = relationship.getLoadedOrUndefined()
 
           if (model) {
-            if (model instanceof VelociousDatabaseRecord) {
-              belongsToChanges[relationship.getForeignKey()] = model?.id()
-            } else {
-              throw new Error(`Unexpected model type: ${typeof model}`)
-            }
+            if (Array.isArray(model)) throw new Error("Unexpected belongs-to model array")
+
+            belongsToChanges[relationship.getForeignKey()] = this._belongsToForeignKeyValue({model, relationship})
           }
         }
       }

package/build/environment-handlers/node/cli/commands/generate/base-models.js

@@ -120,6 +120,7 @@ export default class DbGenerateModel extends BaseCommand {
 
         const columns = await table.getColumns()
         const writeAttributeTypeName = `${modelNameCamelized}WriteAttributes`
+        const belongsToWriteAttributes = await this.belongsToWriteAttributesForModel({modelClass, modelsDir})
         const nestedWriteAttributes = this.nestedWriteAttributesForModel({modelClass})
 
         fileContent += `import DatabaseRecord from "${velociousPath}/database/record/index.js"\n\n`
@@ -135,6 +136,9 @@ export default class DbGenerateModel extends BaseCommand {
             fileContent += ` * @property {${setterJsdocType}${column.getNull() ? " | null" : ""}} [${camelizedColumnName}] - Value for the ${camelizedColumnName} attribute.\n`
           }
         }
+        for (const belongsToWriteAttribute of belongsToWriteAttributes) {
+          fileContent += ` * @property {${belongsToWriteAttribute.propertyType}} [${belongsToWriteAttribute.propertyName}] - Related ${belongsToWriteAttribute.relationshipName} record.\n`
+        }
         for (const nestedWriteAttribute of nestedWriteAttributes) {
           fileContent += ` * @property {${nestedWriteAttribute.propertyType}} [${nestedWriteAttribute.propertyName}] - Nested ${nestedWriteAttribute.relationshipName} attributes.\n`
         }
@@ -440,6 +444,38 @@ export default class DbGenerateModel extends BaseCommand {
     return this.jsDocTypeFromColumn(column, modelClass)
   }
 
+  /**
+   * Runs belongs to write attributes for model.
+   * @param {object} args - Arguments.
+   * @param {typeof import("../../../../../database/record/index.js").default} args.modelClass - Model class.
+   * @param {string} args.modelsDir - Source models directory.
+   * @returns {Promise<Array<{propertyName: string, propertyType: string, relationshipName: string}>>} - Belongs-to write attributes.
+   */
+  async belongsToWriteAttributesForModel({modelClass, modelsDir}) {
+    const writeAttributes = []
+
+    for (const relationship of modelClass.getRelationships()) {
+      if (relationship.getType() !== "belongsTo") continue
+      if (relationship.getPolymorphic()) continue
+
+      const targetModelClass = relationship.getTargetModelClass()
+
+      if (!targetModelClass) throw new Error(`Relationship '${relationship.getRelationshipName()}' on '${modelClass.getModelName()}' has no target model class`)
+
+      const targetModelFileName = inflection.dasherize(inflection.underscore(targetModelClass.getModelName()))
+      const targetModelPath = `${modelsDir}/${targetModelFileName}.js`
+      const targetImportPath = await fileExists(targetModelPath) ? `../models/${targetModelFileName}.js` : `./${targetModelFileName}.js`
+
+      writeAttributes.push({
+        propertyName: relationship.getRelationshipName(),
+        propertyType: `import("${targetImportPath}").default`,
+        relationshipName: relationship.getRelationshipName()
+      })
+    }
+
+    return writeAttributes
+  }
+
   /**
    * Runs nested write attributes for model.
    * @param {object} args - Arguments.

package/build/environment-handlers/node/cli/commands/generate/frontend-models.js

@@ -442,6 +442,13 @@ export default class DbGenerateFrontendModels extends BaseCommand {
       }
       fileContent += "      },\n"
     }
+    if (modelConfig.sync?.enabled) {
+      fileContent += this.formattedJsonProperty({
+        indent: "      ",
+        propertyName: "sync",
+        value: modelConfig.sync
+      })
+    }
     fileContent += "    }\n"
     fileContent += "  }\n"
 
@@ -999,6 +1006,62 @@ export default class DbGenerateFrontendModels extends BaseCommand {
     return output
   }
 
+  /**
+   * Runs formatted JSON property.
+   * @param {object} args - Formatting args.
+   * @param {string} args.indent - Base indentation.
+   * @param {string} args.propertyName - Object property name.
+   * @param {unknown} args.value - JSON-compatible value.
+   * @returns {string} - Formatted property.
+   */
+  formattedJsonProperty({indent, propertyName, value}) {
+    return `${indent}${propertyName}: ${this.formattedJsonValue({indent, value})},\n`
+  }
+
+  /**
+   * Runs formatted JSON value.
+   * @param {object} args - Formatting args.
+   * @param {string} args.indent - Indentation before this value.
+   * @param {unknown} args.value - JSON-compatible value.
+   * @returns {string} - Formatted value.
+   */
+  formattedJsonValue({indent, value}) {
+    if (Array.isArray(value)) {
+      let output = "[\n"
+
+      for (const entry of value) {
+        output += `${indent}  ${this.formattedJsonValue({indent: `${indent}  `, value: entry})},\n`
+      }
+
+      output += `${indent}]`
+
+      return output
+    }
+
+    if (value && typeof value === "object") {
+      let output = "{\n"
+
+      for (const key of Object.keys(value)) {
+        output += `${indent}  ${this.formattedObjectKey(key)}: ${this.formattedJsonValue({indent: `${indent}  `, value: /** @type {Record<string, unknown>} */ (value)[key]})},\n`
+      }
+
+      output += `${indent}}`
+
+      return output
+    }
+
+    return JSON.stringify(value)
+  }
+
+  /**
+   * Runs formatted object key.
+   * @param {string} key - Object key.
+   * @returns {string} - JavaScript object key.
+   */
+  formattedObjectKey(key) {
+    return /^[A-Za-z_$][\w$]*$/.test(key) ? key : JSON.stringify(key)
+  }
+
   /**
    * Runs attribute definitions for model.
    * @param {object} args - Arguments.

package/build/frontend-model-controller.js

@@ -5,7 +5,9 @@ import Controller from "./controller.js"
 import FrontendModelBaseResource from "./frontend-model-resource/base-resource.js"
 import Response from "./http-server/client/response.js"
 import {frontendModelResourcesWithBuiltInsForBackendProject} from "./frontend-models/built-in-resources.js"
-import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcePath, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
+import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcePath, frontendModelResourcesForBackendProject, frontendModelSyncManifestForBackendProjects} from "./frontend-models/resource-definition.js"
+import {createOfflineGrantFromBootstrap, verifyOfflineGrant} from "./sync/offline-grant.js"
+import {mutationIdempotencyKey, verifySignedMutation} from "./sync/device-identity.js"
 import {FrontendModelQueryError, normalizeGroup as normalizeQueryGroup, normalizeJoins as normalizeQueryJoins, normalizePluck as normalizeQueryPluck, normalizePreload as normalizeQueryPreload, normalizeSearchOperator as normalizeQuerySearchOperator, normalizeSort as normalizeQuerySort} from "./frontend-models/query.js"
 import {assignSafeProperty, deserializeFrontendModelTransportValue, isBackendModelInstance, serializeFrontendModelTransportValue} from "./frontend-models/transport-serialization.js"
 import {requestDetails} from "./error-reporting/request-details.js"
@@ -25,7 +27,11 @@ import {RansackQueryError, normalizeRansackGroup, parseRansackSort} from "./util
 function normalizeFrontendModelPreload(preload) {
   if (!preload) return null
 
-  return normalizeQueryPreload(preload)
+  try {
+    return normalizeQueryPreload(preload)
+  } catch (error) {
+    throwFrontendModelQueryErrorForParserError(error)
+  }
 }
 
 /**
@@ -167,6 +173,19 @@ const frontendModelWhereNoMatchSymbol = Symbol("frontendModelWhereNoMatch")
 const frontendModelClientSafeErrorMessage = "Request failed."
 const frontendModelDebugErrorEnvironments = new Set(["development", "test"])
 
+/**
+ * Builds a client-safe sync replay validation error.
+ * @param {string} message - Client-safe validation message.
+ * @param {unknown} [cause] - Original cause.
+ * @returns {VelociousError} - Client-safe replay error.
+ */
+function frontendSyncReplaySafeError(message, cause) {
+  return VelociousError.safe(message, {
+    cause,
+    code: "frontend_sync_replay_error"
+  })
+}
+
 /**
  * Runs frontend model query metadata.
  * @param {import("./database/query/model-class-query.js").default} query - Query instance.
@@ -863,13 +882,31 @@ export default class FrontendModelController extends Controller {
     for (const [relationshipName, relationshipPreload] of Object.entries(preload)) {
       if (relationshipPreload === false) continue
 
-      const relationship = modelClass.getRelationshipByName(relationshipName)
+      const relationship = modelClass.getRelationshipsMap()[relationshipName]
+      if (!relationship) {
+        throw frontendModelQueryError(`Unknown preload relationship "${relationshipName}" for ${modelClass.name}`)
+      }
+
       const targetModelClass = await this.ensureFrontendModelRelationshipTargetClassInitialized({
         backendProject,
         relationship
       })
 
-      if (!targetModelClass || !isPlainObject(relationshipPreload)) continue
+      if (!targetModelClass) {
+        if (isPlainObject(relationshipPreload) && Object.keys(relationshipPreload).length > 0) {
+          let message = `Cannot preload nested relationships through relationship "${relationshipName}" for ${modelClass.name} because its target model class could not be resolved`
+
+          if (relationship.getPolymorphic() && relationship.getType() === "belongsTo") {
+            message = `Cannot preload nested relationships through polymorphic relationship "${relationshipName}" for ${modelClass.name}`
+          }
+
+          throw frontendModelQueryError(message)
+        }
+
+        continue
+      }
+
+      if (!isPlainObject(relationshipPreload)) continue
 
       await this.ensureFrontendModelPreloadClassesInitialized({
         backendProject,
@@ -3438,6 +3475,366 @@ export default class FrontendModelController extends Controller {
     return {status: "success"}
   }
 
+  /**
+   * Runs frontend sync bootstrap.
+   * @returns {Promise<void>} - Sync bootstrap response with manifest and signed offline grant.
+   */
+  async frontendSyncBootstrap() {
+    if (this.request().httpMethod() === "OPTIONS") {
+      await this.render({status: 204, json: {}})
+      return
+    }
+
+    const params = /** @type {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} */ (deserializeFrontendModelTransportValue(this.params()))
+    const configuration = this.getConfiguration()
+    const syncManifest = frontendModelSyncManifestForBackendProjects(configuration.getBackendProjects())
+    const offlineGrant = await createOfflineGrantFromBootstrap({
+      deviceId: this.frontendSyncBootstrapDeviceId(params),
+      grantId: this.frontendSyncBootstrapGrantId(params),
+      grantTtlMs: configuration.getSyncConfiguration().offlineGrantTtlMs,
+      now: this.frontendSyncBootstrapNow(params),
+      resources: syncManifest,
+      scopes: this.frontendSyncBootstrapScopes(params),
+      signingKey: configuration.currentOfflineGrantSigningKey(),
+      userId: this.frontendSyncBootstrapUserId()
+    })
+
+    await this.render({
+      json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue({
+        offlineGrant,
+        status: "success",
+        syncManifest
+      }, this.transportSerializationOptions()))
+    })
+  }
+
+  /**
+   * Resolves device id for sync bootstrap.
+   * @param {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} params - Request params.
+   * @returns {string} - Device id.
+   */
+  frontendSyncBootstrapDeviceId(params) {
+    if (typeof params.deviceId === "string" && params.deviceId.length > 0) return params.deviceId
+
+    throw new Error("Expected sync bootstrap deviceId")
+  }
+
+  /**
+   * Resolves grant id for sync bootstrap.
+   * @param {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} params - Request params.
+   * @returns {string | undefined} - Deterministic grant id for tests, generated id otherwise.
+   */
+  frontendSyncBootstrapGrantId(params) {
+    if (this.getConfiguration().getEnvironment() === "test" && typeof params.grantId === "string") return params.grantId
+
+    return undefined
+  }
+
+  /**
+   * Resolves bootstrap issue time.
+   * @param {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} params - Request params.
+   * @returns {Date} - Issue time.
+   */
+  frontendSyncBootstrapNow(params) {
+    if (this.getConfiguration().getEnvironment() === "test" && typeof params.now === "string") return new Date(params.now)
+
+    return new Date()
+  }
+
+  /**
+   * Resolves sync bootstrap scopes.
+   * @param {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue | undefined>} params - Request params.
+   * @returns {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue>} - Grant scopes.
+   */
+  frontendSyncBootstrapScopes(params) {
+    const scopes = params.scopes
+
+    if (scopes && typeof scopes === "object" && !Array.isArray(scopes)) {
+      return /** @type {Record<string, import("./configuration-types.js").FrontendModelSyncJsonValue>} */ (scopes)
+    }
+
+    return {}
+  }
+
+  /**
+   * Resolves current user id for sync bootstrap.
+   * @returns {string} - User id.
+   */
+  frontendSyncBootstrapUserId() {
+    const ability = this.currentAbility()
+    const currentUser = ability?.currentUser()
+
+    if (typeof currentUser === "string" || typeof currentUser === "number") return String(currentUser)
+    if (currentUser && typeof currentUser === "object") {
+      const userRecord = /** @type {{id?: string | number | (() => string | number)}} */ (currentUser)
+      const idValue = typeof userRecord.id === "function" ? userRecord.id() : userRecord.id
+
+      if (typeof idValue === "string" || typeof idValue === "number") return String(idValue)
+    }
+
+    throw new Error("Expected sync bootstrap current user")
+  }
+
+  /**
+   * Runs frontend sync replay.
+   * @returns {Promise<void>} - Sync replay response with per-mutation results.
+   */
+  async frontendSyncReplay() {
+    if (this.request().httpMethod() === "OPTIONS") {
+      await this.render({status: 204, json: {}})
+      return
+    }
+
+    const params = /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(this.params()))
+    const signedMutations = this.frontendSyncReplaySignedMutations(params)
+    const results = []
+
+    for (const signedMutation of signedMutations) {
+      let idempotencyKey = null
+
+      try {
+        idempotencyKey = mutationIdempotencyKey(/** @type {import("./sync/device-identity.js").SignedSyncMutation} */ (signedMutation))
+        const response = await this.frontendSyncReplaySignedMutation(signedMutation)
+
+        results.push({idempotencyKey, response, status: "success"})
+      } catch (error) {
+        const errorContext = this.frontendModelEndpointErrorContext({
+          action: "frontendSyncReplay",
+          commandType: signedMutation && typeof signedMutation === "object" && "mutation" in signedMutation
+            ? /** @type {{mutation?: {operation?: ?}}} */ (signedMutation).mutation?.operation
+            : undefined,
+          error,
+          model: signedMutation && typeof signedMutation === "object" && "mutation" in signedMutation
+            ? /** @type {{mutation?: {model?: ?}}} */ (signedMutation).mutation?.model
+            : undefined
+        })
+
+        await this.frontendModelLogEndpointError({
+          action: errorContext.action,
+          commandType: errorContext.commandType,
+          error,
+          model: errorContext.model
+        })
+
+        results.push({
+          idempotencyKey,
+          response: await this.frontendModelClientErrorPayloadForError(error, errorContext),
+          status: "error"
+        })
+      }
+    }
+
+    await this.render({
+      json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue({
+        results,
+        status: "success"
+      }, this.transportSerializationOptions()))
+    })
+  }
+
+  /**
+   * Resolves signed replay mutations from request params.
+   * @param {Record<string, ?>} params - Request params.
+   * @returns {Array<?>} - Signed mutation envelopes.
+   */
+  frontendSyncReplaySignedMutations(params) {
+    if (Array.isArray(params.mutations)) return params.mutations
+    if (params.mutation) return [params.mutation]
+
+    throw new Error("Expected sync replay mutation or mutations")
+  }
+
+  /**
+   * Verifies and replays one signed sync mutation.
+   * @param {?} signedMutation - Signed mutation envelope.
+   * @returns {Promise<Record<string, ?>>} - Frontend-model command response.
+   */
+  async frontendSyncReplaySignedMutation(signedMutation) {
+    const configuration = this.getConfiguration()
+    const syncConfiguration = configuration.getSyncConfiguration()
+    const backendPublicKey = syncConfiguration.deviceCertificateBackendPublicKey
+
+    if (!backendPublicKey) throw frontendSyncReplaySafeError("sync.deviceCertificateBackendPublicKey is required for sync replay")
+
+    let mutation
+
+    try {
+      mutation = await verifySignedMutation({
+        backendPublicKey,
+        signedMutation: /** @type {import("./sync/device-identity.js").SignedSyncMutation} */ (signedMutation)
+      })
+    } catch (error) {
+      throw frontendSyncReplaySafeError(error instanceof Error ? error.message : String(error), error)
+    }
+
+    const syncManifest = frontendModelSyncManifestForBackendProjects(configuration.getBackendProjects())
+    const syncResource = syncManifest[mutation.model]
+
+    if (!syncResource) throw frontendSyncReplaySafeError(`Sync replay model is not enabled: ${mutation.model}`)
+    if (!syncResource.operations.includes(mutation.operation)) {
+      throw frontendSyncReplaySafeError(`Sync replay operation is not enabled for ${mutation.model}: ${mutation.operation}`)
+    }
+    if (syncResource.policyHash !== mutation.policyHash) {
+      throw frontendSyncReplaySafeError(`Sync replay policy hash mismatch for ${mutation.model}`)
+    }
+    if (!["create", "update", "destroy"].includes(mutation.operation)) {
+      throw frontendSyncReplaySafeError(`Sync replay operation is not supported yet: ${mutation.operation}`)
+    }
+
+    const signedOfflineGrant = this.frontendSyncReplaySignedOfflineGrant(signedMutation)
+    const offlineGrant = await this.frontendSyncReplayVerifiedOfflineGrant({
+      signedOfflineGrant,
+      signingKeys: syncConfiguration.offlineGrantSigningKeys
+    })
+
+    this.frontendSyncReplayValidateOfflineGrant({mutation, offlineGrant, syncResource})
+
+    const commandParams = await this.frontendSyncReplayCommandParams(mutation)
+
+    try {
+      return await this.withFrontendModelParams(commandParams, async () => {
+        return await this.withFrontendModelRequestContext(commandParams, this.response(), async () => {
+          return await this.frontendModelCommandPayload(/** @type {"create" | "update" | "destroy"} */ (mutation.operation)) || this.frontendModelErrorPayload("Action halted by beforeAction.")
+        })
+      })
+    } catch (error) {
+      const errorContext = this.frontendModelEndpointErrorContext({
+        action: "frontendSyncReplay",
+        commandType: /** @type {"create" | "update" | "destroy"} */ (mutation.operation),
+        error,
+        model: mutation.model
+      })
+
+      await this.frontendModelLogEndpointError({
+        action: errorContext.action,
+        commandType: errorContext.commandType,
+        error,
+        model: errorContext.model
+      })
+
+      return await this.frontendModelClientErrorPayloadForError(error, errorContext)
+    }
+  }
+
+  /**
+   * Resolves the signed offline grant carried by a replay request.
+   * @param {?} signedMutation - Signed mutation envelope.
+   * @returns {?} - Signed offline grant envelope.
+   */
+  frontendSyncReplaySignedOfflineGrant(signedMutation) {
+    if (!signedMutation || typeof signedMutation !== "object" || Array.isArray(signedMutation)) {
+      throw frontendSyncReplaySafeError("Expected sync replay signed offline grant")
+    }
+
+    const signedMutationRecord = /** @type {Record<string, ?>} */ (signedMutation)
+    const signedOfflineGrant = signedMutationRecord.signedOfflineGrant || signedMutationRecord.offlineGrant || signedMutationRecord.signedGrant
+
+    if (!signedOfflineGrant) throw frontendSyncReplaySafeError("Expected sync replay signed offline grant")
+
+    return signedOfflineGrant
+  }
+
+  /**
+   * Verifies a sync replay signed offline grant.
+   * @param {object} args - Arguments.
+   * @param {?} args.signedOfflineGrant - Signed offline grant envelope.
+   * @param {import("./sync/offline-grant.js").OfflineGrantSigningKey[]} args.signingKeys - Available signing keys.
+   * @returns {Promise<import("./sync/offline-grant.js").OfflineGrant>} - Verified offline grant.
+   */
+  async frontendSyncReplayVerifiedOfflineGrant({signedOfflineGrant, signingKeys}) {
+    try {
+      return await verifyOfflineGrant({
+        now: new Date(),
+        signedGrant: /** @type {import("./sync/offline-grant.js").SignedOfflineGrant} */ (signedOfflineGrant),
+        signingKeys
+      })
+    } catch (error) {
+      throw frontendSyncReplaySafeError(error instanceof Error ? error.message : String(error), error)
+    }
+  }
+
+  /**
+   * Validates that a verified offline grant authorizes a replayed mutation.
+   * @param {object} args - Arguments.
+   * @param {import("./sync/device-identity.js").SyncMutation} args.mutation - Verified mutation.
+   * @param {import("./sync/offline-grant.js").OfflineGrant} args.offlineGrant - Verified grant.
+   * @param {Record<string, ?>} args.syncResource - Current sync resource entry.
+   * @returns {void} - Throws when unauthorized.
+   */
+  frontendSyncReplayValidateOfflineGrant({mutation, offlineGrant, syncResource}) {
+    if (offlineGrant.grantId !== mutation.offlineGrantId) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant does not match mutation")
+    }
+    if (offlineGrant.deviceId !== mutation.actorDeviceId) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant device does not match mutation")
+    }
+    if (offlineGrant.userId !== mutation.actorUserId) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant user does not match mutation")
+    }
+
+    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 frontendSyncReplaySafeError(`Sync replay offline grant does not authorize ${mutation.model}`)
+    if (!grantOperations.includes(mutation.operation)) {
+      throw frontendSyncReplaySafeError(`Sync replay offline grant does not authorize ${mutation.model}: ${mutation.operation}`)
+    }
+    if (grantPolicyHash !== mutation.policyHash || grantPolicyHash !== syncResource.policyHash) {
+      throw frontendSyncReplaySafeError(`Sync replay offline grant policy hash mismatch for ${mutation.model}`)
+    }
+    if (!offlineGrant.scopes || typeof offlineGrant.scopes !== "object" || Array.isArray(offlineGrant.scopes)) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant scopes are invalid")
+    }
+  }
+
+  /**
+   * Builds frontend-model command params for a verified replay mutation.
+   * @param {import("./sync/device-identity.js").SyncMutation} mutation - Verified mutation.
+   * @returns {Promise<Record<string, ?>>} - Frontend-model command params.
+   */
+  async frontendSyncReplayCommandParams(mutation) {
+    const payload = mutation.payload && typeof mutation.payload === "object" && !Array.isArray(mutation.payload) ? mutation.payload : {}
+    const {attributes, primaryKeyValue} = await this.frontendSyncReplayCommandAttributes(mutation)
+    const commandParams = /** @type {Record<string, ?>} */ ({
+      ...payload,
+      attributes,
+      model: mutation.model
+    })
+
+    if (mutation.operation !== "create") {
+      const id = commandParams.id || commandParams.recordId || primaryKeyValue
+
+      if (typeof id !== "string" && typeof id !== "number") throw frontendSyncReplaySafeError(`Sync replay ${mutation.operation} requires an id`)
+
+      commandParams.id = id
+    }
+
+    return commandParams
+  }
+
+  /**
+   * Resolves command attributes and primary key from a replay mutation.
+   * @param {import("./sync/device-identity.js").SyncMutation} mutation - Verified mutation.
+   * @returns {Promise<{attributes: Record<string, ?>, primaryKeyValue: string | number | undefined}>} - Command attributes and primary key value.
+   */
+  async frontendSyncReplayCommandAttributes(mutation) {
+    const attributes = /** @type {Record<string, ?>} */ ({...(mutation.attributes || {})})
+    const frontendModelResource = this.getConfiguration().getBackendProjects()
+      .map((backendProject) => this.frontendModelResourceConfigurationForBackendProjectModelName({backendProject, modelName: mutation.model}))
+      .find((resourceConfiguration) => resourceConfiguration)
+
+    if (!frontendModelResource) return {attributes, primaryKeyValue: undefined}
+
+    const primaryKey = typeof frontendModelResource.resourceConfiguration.primaryKey === "string" ? frontendModelResource.resourceConfiguration.primaryKey : "id"
+    const primaryKeyAttribute = attributes[primaryKey]
+    const primaryKeyValue = typeof primaryKeyAttribute === "string" || typeof primaryKeyAttribute === "number" ? primaryKeyAttribute : undefined
+
+    if (primaryKeyValue !== undefined && mutation.operation !== "create") delete attributes[primaryKey]
+
+    return {attributes, primaryKeyValue}
+  }
+
   /**
    * Runs frontend api.
    * @returns {Promise<void>} - Shared frontend model API action with batch support.