@korajs/core 1.0.0-beta.0 → 1.0.0-beta.10

package/dist/index.js

@@ -109,6 +109,226 @@ function formatUUID(bytes) {
   return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
 }
 
+// src/blob/blob-ref.ts
+async function hashBlob(bytes) {
+  const view = new Uint8Array(bytes.byteLength);
+  view.set(bytes);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", view);
+  const out = new Uint8Array(digest);
+  return Array.from(out, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function createBlobRef(bytes, metadata = {}) {
+  const hash = await hashBlob(bytes);
+  const ref = { hash, size: bytes.byteLength };
+  if (metadata.mimeType !== void 0) {
+    ref.mimeType = metadata.mimeType;
+  }
+  if (metadata.filename !== void 0) {
+    ref.filename = metadata.filename;
+  }
+  return ref;
+}
+function isBlobRef(value) {
+  if (typeof value !== "object" || value === null) {
+    return false;
+  }
+  const ref = value;
+  if (typeof ref.hash !== "string" || !/^[0-9a-f]{64}$/.test(ref.hash)) {
+    return false;
+  }
+  if (typeof ref.size !== "number" || !Number.isInteger(ref.size) || ref.size < 0) {
+    return false;
+  }
+  if (ref.mimeType !== void 0 && typeof ref.mimeType !== "string") {
+    return false;
+  }
+  if (ref.filename !== void 0 && typeof ref.filename !== "string") {
+    return false;
+  }
+  if (ref.manifestHash !== void 0 && (typeof ref.manifestHash !== "string" || !/^[0-9a-f]{64}$/.test(ref.manifestHash))) {
+    return false;
+  }
+  return true;
+}
+
+// src/secret/secret-crypto.ts
+var PBKDF2_ITERATIONS = 21e4;
+var SALT_BYTES = 16;
+var IV_BYTES = 12;
+var HASH_BYTES = 32;
+function toHex(bytes) {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function fromHex(hex) {
+  if (hex.length % 2 !== 0 || /[^0-9a-f]/i.test(hex)) {
+    throw new Error("Invalid hex string");
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+function randomBytes(n) {
+  const out = new Uint8Array(n);
+  globalThis.crypto.getRandomValues(out);
+  return out;
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) {
+    return false;
+  }
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= a[i] ^ b[i];
+  }
+  return diff === 0;
+}
+async function deriveAesKey(secretKey, salt) {
+  const baseKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secretKey),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  return globalThis.crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt, iterations: PBKDF2_ITERATIONS, hash: "SHA-256" },
+    baseKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+}
+async function encryptSecret(plaintext, secretKey) {
+  const salt = randomBytes(SALT_BYTES);
+  const iv = randomBytes(IV_BYTES);
+  const key = await deriveAesKey(secretKey, salt);
+  const ciphertext = await globalThis.crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    new TextEncoder().encode(plaintext)
+  );
+  return `v1.${toHex(salt)}.${toHex(iv)}.${toHex(new Uint8Array(ciphertext))}`;
+}
+async function decryptSecret(encrypted, secretKey) {
+  const parts = encrypted.split(".");
+  if (parts.length !== 4 || parts[0] !== "v1") {
+    throw new Error("Invalid encrypted secret format");
+  }
+  const salt = fromHex(parts[1]);
+  const iv = fromHex(parts[2]);
+  const ciphertext = fromHex(parts[3]);
+  const key = await deriveAesKey(secretKey, salt);
+  const plaintext = await globalThis.crypto.subtle.decrypt(
+    { name: "AES-GCM", iv },
+    key,
+    ciphertext
+  );
+  return new TextDecoder().decode(plaintext);
+}
+async function hashSecret(plaintext) {
+  const salt = randomBytes(SALT_BYTES);
+  const hash = await pbkdf2(plaintext, salt);
+  return `v1.${toHex(salt)}.${toHex(hash)}`;
+}
+async function verifySecret(plaintext, stored) {
+  const parts = stored.split(".");
+  if (parts.length !== 3 || parts[0] !== "v1") {
+    return false;
+  }
+  let salt;
+  let expected;
+  try {
+    salt = fromHex(parts[1]);
+    expected = fromHex(parts[2]);
+  } catch {
+    return false;
+  }
+  const actual = await pbkdf2(plaintext, salt);
+  return timingSafeEqual(actual, expected);
+}
+async function pbkdf2(plaintext, salt) {
+  const baseKey = await globalThis.crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(plaintext),
+    "PBKDF2",
+    false,
+    ["deriveBits"]
+  );
+  const bits = await globalThis.crypto.subtle.deriveBits(
+    { name: "PBKDF2", salt, iterations: PBKDF2_ITERATIONS, hash: "SHA-256" },
+    baseKey,
+    HASH_BYTES * 8
+  );
+  return new Uint8Array(bits);
+}
+
+// src/secret/secret-transform.ts
+var MissingSecretKeyError = class extends Error {
+  constructor(field) {
+    super(
+      `Secret field "${field}" is encrypted but no encryption key is configured. Provide sync.encryption.key (or a key provider) to createApp.`
+    );
+    this.field = field;
+    this.name = "MissingSecretKeyError";
+  }
+  field;
+};
+async function resolveKey(provider) {
+  if (!provider) {
+    return void 0;
+  }
+  return provider();
+}
+async function transformSecretFieldsForWrite(data, collectionDef, keyProvider) {
+  const hasSecret = Object.values(collectionDef.fields).some((f) => f.kind === "secret");
+  if (!hasSecret) {
+    return data;
+  }
+  const result = { ...data };
+  let key;
+  let keyResolved = false;
+  for (const [field, value] of Object.entries(data)) {
+    const descriptor = collectionDef.fields[field];
+    if (descriptor?.kind !== "secret") {
+      continue;
+    }
+    if (typeof value !== "string") {
+      continue;
+    }
+    const mode = descriptor.secretMode ?? "encrypted";
+    if (mode === "hashed") {
+      result[field] = await hashSecret(value);
+      continue;
+    }
+    if (!keyResolved) {
+      key = await resolveKey(keyProvider);
+      keyResolved = true;
+    }
+    if (key === void 0) {
+      throw new MissingSecretKeyError(field);
+    }
+    result[field] = await encryptSecret(value, key);
+  }
+  return result;
+}
+async function revealSecret(storedValue, mode, keyProvider, field = "secret") {
+  if (mode === "hashed") {
+    throw new Error(
+      `Secret field "${field}" is hashed (one-way) and cannot be revealed. Use verifySecretValue to check a candidate.`
+    );
+  }
+  const key = await resolveKey(keyProvider);
+  if (key === void 0) {
+    throw new MissingSecretKeyError(field);
+  }
+  return decryptSecret(storedValue, key);
+}
+async function verifySecretValue(candidate, storedValue) {
+  return verifySecret(candidate, storedValue);
+}
+
 // src/operations/apply-result.ts
 var APPLY_RESULTS = ["applied", "duplicate", "skipped", "rejected", "deferred"];
 var APPLY_FAILURE_CODES = {
@@ -145,32 +365,36 @@ var KORA_ATOMIC_OP = /* @__PURE__ */ Symbol.for("kora.atomic_op");
 function isAtomicOp(value) {
   return typeof value === "object" && value !== null && KORA_ATOMIC_OP in value && value[KORA_ATOMIC_OP] === true;
 }
-function resolveAtomicOp(currentValue, sentinel) {
-  switch (sentinel.type) {
+function applyAtomicOp(currentValue, atomicOp) {
+  switch (atomicOp.type) {
     case "increment": {
       const current = typeof currentValue === "number" ? currentValue : 0;
-      const operand = sentinel.value;
+      const operand = atomicOp.value;
       return current + operand;
     }
     case "max": {
       const current = typeof currentValue === "number" ? currentValue : Number.NEGATIVE_INFINITY;
-      return Math.max(current, sentinel.value);
+      return Math.max(current, atomicOp.value);
     }
     case "min": {
       const current = typeof currentValue === "number" ? currentValue : Number.POSITIVE_INFINITY;
-      return Math.min(current, sentinel.value);
+      return Math.min(current, atomicOp.value);
     }
     case "append": {
       const current = Array.isArray(currentValue) ? [...currentValue] : [];
-      current.push(sentinel.value);
+      current.push(atomicOp.value);
       return current;
     }
     case "remove": {
       if (!Array.isArray(currentValue)) return [];
-      return currentValue.filter((item) => item !== sentinel.value);
+      const target = JSON.stringify(atomicOp.value);
+      return currentValue.filter((item) => JSON.stringify(item) !== target);
     }
   }
 }
+function resolveAtomicOp(currentValue, sentinel) {
+  return applyAtomicOp(currentValue, { type: sentinel.type, value: sentinel.value });
+}
 function createSentinel(type, value) {
   return Object.freeze({
     [KORA_ATOMIC_OP]: true,
@@ -238,6 +462,46 @@ function toAtomicOp(sentinel) {
   return { type: sentinel.type, value: sentinel.value };
 }
 
+// src/operations/replay-record.ts
+function replayOperationsForRecord(ops) {
+  let record = null;
+  let deleted = false;
+  const lastWriterKind = {};
+  for (const op2 of ops) {
+    switch (op2.type) {
+      case "insert":
+        if (op2.data) {
+          record = { ...op2.data };
+          deleted = false;
+          for (const field of Object.keys(op2.data)) {
+            lastWriterKind[field] = "lww";
+          }
+        }
+        break;
+      case "update":
+        if (op2.data) {
+          const next = { ...record ?? {} };
+          for (const [field, value] of Object.entries(op2.data)) {
+            const atomicOp = op2.atomicOps?.[field];
+            if (atomicOp && lastWriterKind[field] === `atomic:${atomicOp.type}`) {
+              next[field] = applyAtomicOp(next[field], atomicOp);
+            } else {
+              next[field] = value;
+            }
+            lastWriterKind[field] = atomicOp ? `atomic:${atomicOp.type}` : "lww";
+          }
+          record = next;
+          deleted = false;
+        }
+        break;
+      case "delete":
+        deleted = true;
+        break;
+    }
+  }
+  return deleted ? null : record;
+}
+
 // src/operations/op-data-binary.ts
 function isKoraBytesValue(value) {
   if (typeof value !== "object" || value === null) {
@@ -488,7 +752,7 @@ function validateStateMachineDefinition(collectionName, sm, fields) {
 }
 
 // src/schema/define.ts
-var COLLECTION_NAME_RE = /^[a-z][a-z0-9_]*$/;
+var COLLECTION_NAME_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
 var FIELD_NAME_RE = /^[a-z][a-zA-Z0-9_]*$/;
 var RESERVED_FIELDS = /* @__PURE__ */ new Set(["id", "_created_at", "_updated_at", "_version", "_deleted"]);
 function defineSchema(input) {
@@ -553,7 +817,7 @@ function validateVersion(version) {
 function validateCollectionName(name) {
   if (!COLLECTION_NAME_RE.test(name)) {
     throw new SchemaValidationError(
-      `Collection name "${name}" is invalid. Must be lowercase, start with a letter, and contain only letters, numbers, and underscores.`,
+      `Collection name "${name}" is invalid. Must start with a letter and contain only letters, numbers, and underscores.`,
       { collection: name }
     );
   }
@@ -745,6 +1009,11 @@ function validateRelation(name, relation, collections) {
   }
 }
 
+// src/schema/quote-ident.ts
+function quoteIdent(name) {
+  return `"${name.replace(/"/g, '""')}"`;
+}
+
 // src/schema/sql-gen.ts
 function generateSQL(collectionName, collection, relations) {
   const statements = [];
@@ -756,7 +1025,7 @@ function generateSQL(collectionName, collection, relations) {
     if (relations) {
       for (const rel of Object.values(relations)) {
         if (rel.from === collectionName && rel.field === fieldName) {
-          colDef += ` REFERENCES ${rel.to}(id)`;
+          colDef += ` REFERENCES ${quoteIdent(rel.to)}(id)`;
           fkFields.push(fieldName);
           break;
         }
@@ -769,36 +1038,40 @@ function generateSQL(collectionName, collection, relations) {
   columns.push("_version TEXT NOT NULL DEFAULT ''");
   columns.push("_field_versions TEXT NOT NULL DEFAULT '{}'");
   columns.push("_deleted INTEGER NOT NULL DEFAULT 0");
-  statements.push(`CREATE TABLE IF NOT EXISTS ${collectionName} (
+  statements.push(
+    `CREATE TABLE IF NOT EXISTS ${quoteIdent(collectionName)} (
   ${columns.join(",\n  ")}
-)`);
+)`
+  );
   for (const [fieldName, descriptor] of Object.entries(collection.fields)) {
     const colDef = columnDefinition(fieldName, descriptor);
-    statements.push(`--kora:safe-alter
-ALTER TABLE ${collectionName} ADD COLUMN ${colDef}`);
+    statements.push(
+      `--kora:safe-alter
+ALTER TABLE ${quoteIdent(collectionName)} ADD COLUMN ${colDef}`
+    );
   }
   statements.push(
     `--kora:safe-alter
-ALTER TABLE ${collectionName} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
+ALTER TABLE ${quoteIdent(collectionName)} ADD COLUMN _version TEXT NOT NULL DEFAULT ''`
   );
   statements.push(
     `--kora:safe-alter
-ALTER TABLE ${collectionName} ADD COLUMN _field_versions TEXT NOT NULL DEFAULT '{}'`
+ALTER TABLE ${quoteIdent(collectionName)} ADD COLUMN _field_versions TEXT NOT NULL DEFAULT '{}'`
   );
   for (const indexField of collection.indexes) {
     statements.push(
-      `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${indexField} ON ${collectionName} (${indexField})`
+      `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${indexField} ON ${quoteIdent(collectionName)} (${quoteIdent(indexField)})`
     );
   }
   for (const fkField of fkFields) {
     if (!indexedFields.has(fkField)) {
       statements.push(
-        `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${fkField} ON ${collectionName} (${fkField})`
+        `CREATE INDEX IF NOT EXISTS idx_${collectionName}_${fkField} ON ${quoteIdent(collectionName)} (${quoteIdent(fkField)})`
       );
     }
   }
   statements.push(
-    `CREATE TABLE IF NOT EXISTS _kora_ops_${collectionName} (
+    `CREATE TABLE IF NOT EXISTS ${quoteIdent(`_kora_ops_${collectionName}`)} (
   id TEXT PRIMARY KEY NOT NULL,
   node_id TEXT NOT NULL,
   type TEXT NOT NULL,
@@ -812,7 +1085,7 @@ ALTER TABLE ${collectionName} ADD COLUMN _field_versions TEXT NOT NULL DEFAULT '
 )`
   );
   statements.push(
-    `CREATE INDEX IF NOT EXISTS idx_kora_ops_${collectionName}_record_id ON _kora_ops_${collectionName} (record_id)`
+    `CREATE INDEX IF NOT EXISTS idx_kora_ops_${collectionName}_record_id ON ${quoteIdent(`_kora_ops_${collectionName}`)} (record_id)`
   );
   return statements;
 }
@@ -830,6 +1103,9 @@ function generateFullDDL(schema) {
   statements.push(
     "CREATE TABLE IF NOT EXISTS _kora_sync_queue (\n  id TEXT PRIMARY KEY NOT NULL,\n  payload TEXT NOT NULL\n)"
   );
+  statements.push(
+    "CREATE TABLE IF NOT EXISTS _kora_sync_rejected (\n  operation_id TEXT PRIMARY KEY NOT NULL,\n  collection TEXT NOT NULL,\n  record_id TEXT NOT NULL,\n  code TEXT NOT NULL,\n  message TEXT NOT NULL,\n  retriable INTEGER NOT NULL,\n  rejected_at INTEGER NOT NULL\n)"
+  );
   statements.push(
     "CREATE TABLE IF NOT EXISTS _kora_audit_traces (\n  id TEXT PRIMARY KEY NOT NULL,\n  recorded_at INTEGER NOT NULL,\n  event_type TEXT NOT NULL,\n  collection TEXT NOT NULL,\n  record_id TEXT NOT NULL,\n  field TEXT NOT NULL,\n  strategy TEXT NOT NULL,\n  tier INTEGER NOT NULL,\n  constraint_name TEXT,\n  trace_json TEXT NOT NULL\n)"
   );
@@ -846,7 +1122,7 @@ function generateFullDDL(schema) {
 }
 function columnDefinition(fieldName, descriptor) {
   const sqlType = mapFieldType(descriptor);
-  const parts = [fieldName, sqlType];
+  const parts = [quoteIdent(fieldName), sqlType];
   if (descriptor.required && descriptor.defaultValue === void 0 && !descriptor.auto) {
     parts.push("NOT NULL");
   }
@@ -855,7 +1131,7 @@ function columnDefinition(fieldName, descriptor) {
   }
   if (descriptor.kind === "enum" && descriptor.enumValues) {
     const values = descriptor.enumValues.map((v) => `'${v}'`).join(", ");
-    parts.push(`CHECK (${fieldName} IN (${values}))`);
+    parts.push(`CHECK (${quoteIdent(fieldName)} IN (${values}))`);
   }
   return parts.join(" ");
 }
@@ -874,6 +1150,17 @@ function mapFieldType(descriptor) {
     case "array":
       return "TEXT";
     // JSON-serialized
+    case "object":
+      return "TEXT";
+    // JSON-serialized structured object
+    case "json":
+      return "TEXT";
+    // JSON-serialized dynamic-key value
+    case "blob":
+      return "TEXT";
+    // JSON-serialized content-addressed BlobRef (bytes stored out of band)
+    case "secret":
+      return "TEXT";
     case "richtext":
       return "BLOB";
   }
@@ -1107,6 +1394,160 @@ var ArrayFieldBuilder = class _ArrayFieldBuilder extends FieldBuilder {
     };
   }
 };
+var ObjectFieldBuilder = class _ObjectFieldBuilder extends FieldBuilder {
+  _fields;
+  constructor(fields, required = true, defaultValue = void 0, auto = false, mergeStrategy = null) {
+    super("object", required, defaultValue, auto, mergeStrategy);
+    this._fields = fields;
+  }
+  optional() {
+    return new _ObjectFieldBuilder(
+      this._fields,
+      false,
+      this._defaultValue,
+      this._auto,
+      this._mergeStrategy
+    );
+  }
+  default(value) {
+    return new _ObjectFieldBuilder(this._fields, false, value, this._auto, this._mergeStrategy);
+  }
+  auto() {
+    return new _ObjectFieldBuilder(this._fields, false, void 0, true, this._mergeStrategy);
+  }
+  merge(strategy) {
+    return new _ObjectFieldBuilder(
+      this._fields,
+      this._required,
+      this._defaultValue,
+      this._auto,
+      strategy
+    );
+  }
+  _build() {
+    const nestedFields = {};
+    for (const [key, builder] of Object.entries(this._fields)) {
+      nestedFields[key] = builder._build();
+    }
+    return {
+      kind: "object",
+      required: this._required,
+      defaultValue: this._defaultValue,
+      auto: this._auto,
+      enumValues: null,
+      itemKind: null,
+      mergeStrategy: this._mergeStrategy,
+      transitions: null,
+      nestedFields
+    };
+  }
+};
+var JsonFieldBuilder = class _JsonFieldBuilder extends FieldBuilder {
+  optional() {
+    return new _JsonFieldBuilder(
+      "json",
+      false,
+      this._defaultValue,
+      this._auto,
+      this._mergeStrategy
+    );
+  }
+  default(value) {
+    return new _JsonFieldBuilder(
+      "json",
+      false,
+      value,
+      this._auto,
+      this._mergeStrategy
+    );
+  }
+  auto() {
+    return new _JsonFieldBuilder("json", false, void 0, true, this._mergeStrategy);
+  }
+  merge(strategy) {
+    return new _JsonFieldBuilder(
+      "json",
+      this._required,
+      this._defaultValue,
+      this._auto,
+      strategy
+    );
+  }
+  _build() {
+    return {
+      kind: "json",
+      required: this._required,
+      defaultValue: this._defaultValue,
+      auto: this._auto,
+      enumValues: null,
+      itemKind: null,
+      mergeStrategy: this._mergeStrategy,
+      transitions: null,
+      nestedFields: null
+    };
+  }
+};
+var SecretFieldBuilder = class _SecretFieldBuilder extends FieldBuilder {
+  _secretMode;
+  constructor(secretMode = "encrypted", required = true, defaultValue = void 0, auto = false, mergeStrategy = null) {
+    super("secret", required, defaultValue, auto, mergeStrategy);
+    this._secretMode = secretMode;
+  }
+  /** Store this secret as a one-way salted hash (passwords: verify, never read back). */
+  hashed() {
+    return new _SecretFieldBuilder(
+      "hashed",
+      this._required,
+      this._defaultValue,
+      this._auto,
+      this._mergeStrategy
+    );
+  }
+  /** Store this secret as reversible ciphertext (tokens/keys: decrypt to use). */
+  encrypted() {
+    return new _SecretFieldBuilder(
+      "encrypted",
+      this._required,
+      this._defaultValue,
+      this._auto,
+      this._mergeStrategy
+    );
+  }
+  optional() {
+    return new _SecretFieldBuilder(
+      this._secretMode,
+      false,
+      this._defaultValue,
+      this._auto,
+      this._mergeStrategy
+    );
+  }
+  auto() {
+    return new _SecretFieldBuilder(this._secretMode, false, void 0, true, this._mergeStrategy);
+  }
+  merge(strategy) {
+    return new _SecretFieldBuilder(
+      this._secretMode,
+      this._required,
+      this._defaultValue,
+      this._auto,
+      strategy
+    );
+  }
+  _build() {
+    return {
+      kind: "secret",
+      required: this._required,
+      defaultValue: this._defaultValue,
+      auto: this._auto,
+      enumValues: null,
+      itemKind: null,
+      mergeStrategy: this._mergeStrategy,
+      transitions: null,
+      secretMode: this._secretMode
+    };
+  }
+};
 var t = {
   string() {
     return new FieldBuilder("string", true, void 0, false);
@@ -1128,6 +1569,18 @@ var t = {
   },
   array(itemBuilder) {
     return new ArrayFieldBuilder(itemBuilder, true, void 0, false);
+  },
+  object(fields) {
+    return new ObjectFieldBuilder(fields, true, void 0, false);
+  },
+  json() {
+    return new JsonFieldBuilder("json", true, void 0, false);
+  },
+  blob() {
+    return new FieldBuilder("blob", true, void 0, false);
+  },
+  secret() {
+    return new SecretFieldBuilder("encrypted", true, void 0, false);
   }
 };
 
@@ -1292,8 +1745,126 @@ function validateFieldValue(collection, fieldName, descriptor, value) {
       }
       break;
     }
+    case "object": {
+      if (!isPlainObject(value)) {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be a plain object, got ${describeType(value)}`,
+          {
+            collection,
+            field: fieldName,
+            expectedType: "object",
+            receivedType: describeType(value)
+          }
+        );
+      }
+      if (descriptor.nestedFields) {
+        for (const [nestedName, nestedDescriptor] of Object.entries(descriptor.nestedFields)) {
+          const nestedValue = value[nestedName];
+          if (nestedValue !== void 0 && nestedValue !== null) {
+            validateFieldValue(
+              collection,
+              `${fieldName}.${nestedName}`,
+              nestedDescriptor,
+              nestedValue
+            );
+          }
+        }
+      }
+      break;
+    }
+    case "json": {
+      const nonJson = findNonJsonSerializable(value, fieldName);
+      if (nonJson) {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be JSON-serializable; found ${nonJson.receivedType} at "${nonJson.path}"`,
+          {
+            collection,
+            field: fieldName,
+            expectedType: "json",
+            receivedType: nonJson.receivedType,
+            path: nonJson.path
+          }
+        );
+      }
+      break;
+    }
+    case "blob": {
+      if (!isBlobRef(value)) {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be a BlobRef (from the blob store), got ${describeType(value)}`,
+          { collection, field: fieldName, expectedType: "blob", receivedType: describeType(value) }
+        );
+      }
+      break;
+    }
+    case "secret": {
+      if (typeof value !== "string") {
+        throw new SchemaValidationError(
+          `Field "${fieldName}" in collection "${collection}" must be a string, got ${describeType(value)}`,
+          {
+            collection,
+            field: fieldName,
+            expectedType: "secret",
+            receivedType: describeType(value)
+          }
+        );
+      }
+      break;
+    }
   }
 }
+function isPlainObject(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === null || proto === Object.prototype;
+}
+function findNonJsonSerializable(value, path, seen = /* @__PURE__ */ new WeakSet()) {
+  if (value === null) {
+    return null;
+  }
+  const type = typeof value;
+  if (type === "string" || type === "number" || type === "boolean") {
+    if (type === "number" && !Number.isFinite(value)) {
+      return { path, receivedType: describeType(value) };
+    }
+    return null;
+  }
+  if (type === "undefined" || type === "function" || type === "symbol" || type === "bigint") {
+    return { path, receivedType: describeType(value) };
+  }
+  if (Array.isArray(value)) {
+    for (let index = 0; index < value.length; index++) {
+      const invalid = findNonJsonSerializable(value[index], `${path}[${index}]`, seen);
+      if (invalid) return invalid;
+    }
+    return null;
+  }
+  if (type === "object") {
+    const objectValue = value;
+    if (seen.has(objectValue)) {
+      return { path, receivedType: "circular object" };
+    }
+    seen.add(objectValue);
+    for (const [key, nestedValue] of Object.entries(objectValue)) {
+      const invalid = findNonJsonSerializable(nestedValue, `${path}.${key}`, seen);
+      if (invalid) return invalid;
+    }
+    seen.delete(objectValue);
+    return null;
+  }
+  return { path, receivedType: describeType(value) };
+}
+function describeType(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (Array.isArray(value)) {
+    return "array";
+  }
+  return typeof value;
+}
 function jsTypeForKind(kind) {
   switch (kind) {
     case "string":
@@ -1724,14 +2295,18 @@ function migrationStepsToSQL(steps) {
         statements.push(addFieldSQL(step.collection, step.field, step.descriptor));
         break;
       case "removeField":
-        statements.push(`ALTER TABLE ${step.collection} DROP COLUMN ${step.field}`);
+        statements.push(
+          `ALTER TABLE ${quoteIdent(step.collection)} DROP COLUMN ${quoteIdent(step.field)}`
+        );
         break;
       case "renameField":
-        statements.push(`ALTER TABLE ${step.collection} RENAME COLUMN ${step.from} TO ${step.to}`);
+        statements.push(
+          `ALTER TABLE ${quoteIdent(step.collection)} RENAME COLUMN ${quoteIdent(step.from)} TO ${quoteIdent(step.to)}`
+        );
         break;
       case "addIndex":
         statements.push(
-          `CREATE INDEX IF NOT EXISTS idx_${step.collection}_${step.field} ON ${step.collection} (${step.field})`
+          `CREATE INDEX IF NOT EXISTS idx_${step.collection}_${step.field} ON ${quoteIdent(step.collection)} (${quoteIdent(step.field)})`
         );
         break;
       case "removeIndex":
@@ -1749,13 +2324,13 @@ function rollbackStepsToSQL(migration) {
 }
 function addFieldSQL(collection, field, descriptor) {
   const sqlType = mapFieldType2(descriptor);
-  const parts = [`ALTER TABLE ${collection} ADD COLUMN ${field}`, sqlType];
+  const parts = [`ALTER TABLE ${quoteIdent(collection)} ADD COLUMN ${quoteIdent(field)}`, sqlType];
   if (descriptor.defaultValue !== void 0) {
     parts.push(`DEFAULT ${sqlDefault2(descriptor.defaultValue)}`);
   }
   if (descriptor.kind === "enum" && descriptor.enumValues) {
     const values = descriptor.enumValues.map((v) => `'${v}'`).join(", ");
-    parts.push(`CHECK (${field} IN (${values}))`);
+    parts.push(`CHECK (${quoteIdent(field)} IN (${values}))`);
   }
   return parts.join(" ");
 }
@@ -1773,6 +2348,14 @@ function mapFieldType2(descriptor) {
       return "INTEGER";
     case "array":
       return "TEXT";
+    case "object":
+      return "TEXT";
+    case "json":
+      return "TEXT";
+    case "blob":
+      return "TEXT";
+    case "secret":
+      return "TEXT";
     case "richtext":
       return "BLOB";
   }
@@ -1791,7 +2374,14 @@ var SCALAR_TYPE_MAP = {
   number: "double",
   boolean: "bool",
   timestamp: "int64",
-  richtext: "bytes"
+  richtext: "bytes",
+  // object/json values travel as JSON-serialized strings on the proto wire.
+  object: "string",
+  json: "string",
+  // A blob field carries a JSON-serialized content-addressed reference, not bytes.
+  blob: "string",
+  // A secret field's stored value is a JSON string (ciphertext or hash).
+  secret: "string"
 };
 var ARRAY_ITEM_TYPE_MAP = {
   string: "string",
@@ -2034,6 +2624,7 @@ export {
   MergeConflictError,
   MigrationBuilder,
   MigrationRollbackError,
+  MissingSecretKeyError,
   OperationError,
   RemoteClockDriftError,
   RollbackBuilder,
@@ -2041,6 +2632,7 @@ export {
   StorageError,
   SyncError,
   advanceVector,
+  applyAtomicOp,
   applyOperationTransforms,
   base64ToBytes,
   buildScopeMap,
@@ -2050,16 +2642,19 @@ export {
   collectSchemaScopeFields,
   collectSchemaScopeValueKeys,
   computeDelta,
+  createBlobRef,
   createOperation,
   createReversibleMigration,
   createVersionVector,
   decodeBytesFromOpData,
+  decryptSecret,
   defaultApplyFailureReason,
   defaultSequenceFormat,
   defineSchema,
   deserializeVector,
   dominates,
   encodeBytesForOpData,
+  encryptSecret,
   extractScopeValuesFromClaims,
   extractTimestamp,
   formatSequenceValue,
@@ -2072,8 +2667,11 @@ export {
   getKoraErrorFix,
   getTransitionMap,
   hasSchemaSyncRules,
+  hashBlob,
+  hashSecret,
   isApplyFailure,
   isAtomicOp,
+  isBlobRef,
   isCollectionSyncScoped,
   isKoraBytesValue,
   isLegacyNumericByteObject,
@@ -2083,14 +2681,20 @@ export {
   migrate,
   migrationStepsToSQL,
   op,
+  quoteIdent,
+  replayOperationsForRecord,
   resolveAtomicOp,
+  revealSecret,
   rollbackStepsToSQL,
   serializeVector,
   t,
   toAtomicOp,
+  transformSecretFieldsForWrite,
   validateRecord,
   validateTransition,
   vectorsEqual,
-  verifyOperationIntegrity
+  verifyOperationIntegrity,
+  verifySecret,
+  verifySecretValue
 };
 //# sourceMappingURL=index.js.map