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

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { R as RandomSource, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, C as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, b as CollectionDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-BynBOsO3.cjs';
-export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, B as SequenceConfig, D as StateMachineDefinition, G as SyncDiagnosticsSnapshot, I as SyncRuleDefinition, J as TimeSource, L as migrate, N as t } from './events-BynBOsO3.cjs';
-export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-BpZlYSpe.cjs';
-export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-BIeawJzC.cjs';
+import { R as RandomSource, B as BlobRef, C as CollectionDefinition, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, b as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, J as JsonFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-3z0Tema3.cjs';
+export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, D as SecretMode, G as SequenceConfig, I as StateMachineDefinition, L as SyncDiagnosticsSnapshot, N as SyncRuleDefinition, P as TimeSource, Q as migrate, U as t } from './events-3z0Tema3.cjs';
+export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-BvBgl-4c.cjs';
+export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-B8dpCt6P.cjs';
 
 /**
  * Base error class for all Kora errors.
@@ -161,6 +161,137 @@ declare function extractTimestamp(uuid: string): number;
  */
 declare function isValidUUIDv7(uuid: string): boolean;
 
+/**
+ * Compute the hex-encoded SHA-256 content hash of a byte buffer.
+ *
+ * This is the content address of a blob: identical bytes always hash to the same
+ * value, which is what lets the blob store deduplicate content and lets a peer
+ * skip transferring bytes it already holds.
+ *
+ * @param bytes - The binary content to hash
+ * @returns The hex-encoded SHA-256 hash
+ */
+declare function hashBlob(bytes: Uint8Array): Promise<string>;
+/** Optional metadata carried alongside a blob reference. */
+interface BlobRefMetadata {
+    mimeType?: string;
+    filename?: string;
+}
+/**
+ * Create a content-addressed {@link BlobRef} for a byte buffer.
+ *
+ * @param bytes - The binary content
+ * @param metadata - Optional MIME type and filename
+ * @returns A reference carrying the content hash, size, and metadata
+ */
+declare function createBlobRef(bytes: Uint8Array, metadata?: BlobRefMetadata): Promise<BlobRef>;
+/**
+ * Type guard: whether a value is a structurally valid {@link BlobRef}.
+ *
+ * Validates the shape only (a non-empty hex hash and a non-negative size); it
+ * does not verify that the bytes behind the hash exist or match. Integrity
+ * verification against the actual bytes happens in the blob store on read.
+ */
+declare function isBlobRef(value: unknown): value is BlobRef;
+
+/**
+ * Field-level cryptography for `secret` fields.
+ *
+ * Two protection modes, matching the two ways secrets are used:
+ * - `encrypted`: reversible AES-256-GCM (tokens, API keys — decrypt to use).
+ * - `hashed`: one-way PBKDF2-SHA-256 with a random salt (passwords — verify only).
+ *
+ * These primitives use only the standard WebCrypto API so they live in
+ * `@korajs/core` with no dependency on `@korajs/auth`; a `secret` field is
+ * therefore self-contained. Higher-level key management composes on top.
+ */
+/**
+ * Encrypt a secret's plaintext with AES-256-GCM under a key derived from
+ * `secretKey`. The returned string bundles the salt, IV, and ciphertext (all hex,
+ * dot-separated) so it is self-describing and safe to store and sync.
+ *
+ * @param plaintext - The secret value to protect
+ * @param secretKey - The key material (from a key provider), never stored
+ * @returns An opaque `v1.salt.iv.ciphertext` string
+ */
+declare function encryptSecret(plaintext: string, secretKey: string): Promise<string>;
+/**
+ * Decrypt a value produced by {@link encryptSecret} with the same key.
+ *
+ * @param encrypted - The `v1.salt.iv.ciphertext` string
+ * @param secretKey - The key material used to encrypt
+ * @returns The original plaintext
+ * @throws If the format is invalid or the key is wrong (GCM auth failure)
+ */
+declare function decryptSecret(encrypted: string, secretKey: string): Promise<string>;
+/**
+ * One-way hash a secret (a password) with PBKDF2-SHA-256 and a random salt.
+ * The result bundles the salt and hash so {@link verifySecret} needs nothing
+ * else. There is no way to recover the plaintext from the result.
+ *
+ * @param plaintext - The secret value to hash
+ * @returns An opaque `v1.salt.hash` string
+ */
+declare function hashSecret(plaintext: string): Promise<string>;
+/**
+ * Verify a plaintext against a value produced by {@link hashSecret}, in constant
+ * time with respect to the stored hash.
+ *
+ * @param plaintext - The candidate secret
+ * @param stored - The `v1.salt.hash` string
+ * @returns Whether the plaintext matches
+ */
+declare function verifySecret(plaintext: string, stored: string): Promise<boolean>;
+
+/**
+ * Provider of the key material used to encrypt reversible (`encrypted`) secret
+ * fields. Called at write and reveal time so the key can be loaded lazily (for
+ * example derived from a user passphrase after unlock). Returns undefined when
+ * no key is available.
+ */
+type SecretKeyProvider = () => string | undefined | Promise<string | undefined>;
+/** Thrown when an `encrypted` secret field is written or read without a key. */
+declare class MissingSecretKeyError extends Error {
+    readonly field: string;
+    constructor(field: string);
+}
+/**
+ * Transform the secret fields of a record's write payload into their at-rest
+ * form BEFORE the operation is created, so plaintext never enters the operation
+ * log, the store, or the sync stream.
+ *
+ * - `hashed` fields become a one-way salted hash.
+ * - `encrypted` fields become ciphertext (requires a key).
+ *
+ * Non-secret fields, and secret fields not present in `data`, are passed through
+ * untouched. Null/undefined secret values are left as-is (nothing to protect).
+ *
+ * @param data - The validated write payload (plaintext secret values)
+ * @param collectionDef - The collection definition (for field kinds/modes)
+ * @param keyProvider - Supplies the encryption key for `encrypted` fields
+ * @returns A new payload with secret fields replaced by their at-rest form
+ */
+declare function transformSecretFieldsForWrite(data: Record<string, unknown>, collectionDef: CollectionDefinition, keyProvider?: SecretKeyProvider): Promise<Record<string, unknown>>;
+/**
+ * Reveal the plaintext of an `encrypted` secret field's stored value. Throws for
+ * `hashed` fields, which are one-way and cannot be revealed.
+ *
+ * @param storedValue - The at-rest value (ciphertext)
+ * @param mode - The field's secret mode
+ * @param keyProvider - Supplies the decryption key
+ * @param field - Field name (for error messages)
+ * @returns The decrypted plaintext
+ */
+declare function revealSecret(storedValue: string, mode: 'hashed' | 'encrypted', keyProvider: SecretKeyProvider | undefined, field?: string): Promise<string>;
+/**
+ * Verify a plaintext candidate against a `hashed` secret field's stored value.
+ *
+ * @param candidate - The plaintext to check (for example a login password)
+ * @param storedValue - The stored one-way hash
+ * @returns Whether the candidate matches
+ */
+declare function verifySecretValue(candidate: string, storedValue: string): Promise<boolean>;
+
 /**
  * Outcome of applying a single operation to materialized storage (local or remote).
  */
@@ -228,6 +359,20 @@ interface AtomicOpSentinel {
  * @returns true if the value is an AtomicOpSentinel
  */
 declare function isAtomicOp(value: unknown): value is AtomicOpSentinel;
+/**
+ * Apply a plain atomic op (`{ type, value }`) to a current value, producing the
+ * concrete result. This is the single source of truth for atomic-op semantics:
+ * {@link resolveAtomicOp} (sentinel form, used on the write path) delegates here,
+ * and the server's materialization replays stored atomic ops through it, so the
+ * server's materialized view composes concurrent atomic writes identically to the
+ * client. Folding this over a field's writes in HLC order yields, for a same-type
+ * atomic chain, exactly the composed intent (sum of increments, max of maxes, ...).
+ *
+ * @param currentValue - The current value of the field
+ * @param atomicOp - The atomic op to apply (type + operand)
+ * @returns The resulting concrete value
+ */
+declare function applyAtomicOp(currentValue: unknown, atomicOp: AtomicOp): unknown;
 /**
  * Resolve an atomic op sentinel against a current value to produce a concrete result.
  *
@@ -306,6 +451,40 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/** One operation's contribution to a record's materialized state. */
+interface ReplayOperation {
+    type: string;
+    data: Record<string, unknown> | null;
+    /**
+     * Atomic-op intents carried by this operation, per field. When present, a field
+     * is composed (rather than overwritten) if the previous writer on that field was
+     * an atomic op of the same type. Absent means every field resolves by
+     * last-write-wins.
+     */
+    atomicOps?: Record<string, AtomicOp> | null;
+}
+/**
+ * Replay a list of operations (MUST be pre-sorted in HLC total order —
+ * wallTime, then logical, then nodeId) to produce the current state of a single
+ * record, composing atomic-op intents.
+ *
+ * Per field, an atomic op composes onto the running value only when the field's
+ * previous writer was an atomic op of the SAME type (a same-type atomic chain:
+ * concurrent increments sum, maxes take the max, appends accumulate); any other
+ * write, including the first atomic write after a plain set, resolves by
+ * last-write-wins on the resolved value. Because operations are folded in HLC order,
+ * the current op always wins that last-write-wins comparison, so the result is
+ * deterministic and identical on every replica that folds the same operation set.
+ *
+ * This is the single definition of atomic materialization shared by the client
+ * (`@korajs/store` apply pipeline) and the server (`@korajs/server` materialization),
+ * so both converge to the same value for any number of concurrent atomic writers.
+ *
+ * Returns the record field data (without `id`) or null if the record was deleted
+ * or never inserted.
+ */
+declare function replayOperationsForRecord(ops: ReplayOperation[]): Record<string, unknown> | null;
+
 /**
  * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
  * `op.previousData` (currently richtext field values). A raw Uint8Array
@@ -474,6 +653,38 @@ declare function generateSQL(collectionName: string, collection: CollectionDefin
  */
 declare function generateFullDDL(schema: SchemaDefinition): string[];
 
+/**
+ * Quote a SQL identifier (table or column name) for safe interpolation into
+ * generated SQL.
+ *
+ * Uses standard double-quote quoting, which both SQLite and PostgreSQL honor,
+ * and doubles any embedded double-quote per the SQL standard. Quoting is what
+ * lets a valid JavaScript identifier — camelCase (`formResponses`), PascalCase
+ * (`UserProfiles`), or a word that happens to be a SQL keyword (`order`,
+ * `select`) — round-trip through generated DDL and queries without ever
+ * producing invalid or ambiguous SQL.
+ *
+ * Schema validation (see `validateCollectionName` / `validateFieldName`)
+ * already restricts identifiers to `[A-Za-z][A-Za-z0-9_]*`, so the escape here
+ * never actually fires in practice; it is defense in depth so this helper is
+ * correct for any input rather than only for pre-validated names.
+ *
+ * Consistency is the contract: every path that emits an identifier for a
+ * user-defined collection or field MUST go through this helper, because a
+ * quoted `CREATE TABLE "order"` paired with an unquoted `SELECT ... FROM order`
+ * would reintroduce the exact keyword-collision bug this guards against.
+ *
+ * @param name - The raw identifier (collection name, field/column name).
+ * @returns The identifier wrapped in double quotes, ready to splice into SQL.
+ *
+ * @example
+ * ```typescript
+ * quoteIdent('formResponses') // => '"formResponses"'
+ * quoteIdent('order')         // => '"order"'
+ * ```
+ */
+declare function quoteIdent(name: string): string;
+
 /**
  * Validates a record's data against a collection's field definitions.
  * Applies defaults, rejects auto fields, and type-checks each value.
@@ -508,12 +719,16 @@ interface FieldKindToType {
     richtext: string;
     enum: string;
     array: unknown[];
+    object: Record<string, unknown>;
+    json: unknown;
+    blob: BlobRef;
+    secret: string;
 }
 /**
  * Infers the TypeScript type for a single field descriptor or builder.
  * Supports both FieldBuilder (class instances) and FieldDescriptor (compiled objects).
  */
-type InferFieldType<F> = F extends EnumFieldBuilder<infer V, any, any> ? V[number] : F extends ArrayFieldBuilder<infer K, any, any> ? FieldKindToType[K][] : F extends FieldBuilder<infer K, any, any> ? K extends keyof FieldKindToType ? FieldKindToType[K] : unknown : F extends {
+type InferFieldType<F> = F extends EnumFieldBuilder<infer V, any, any> ? V[number] : F extends JsonFieldBuilder<infer T, any, any> ? T : F extends ArrayFieldBuilder<infer K, any, any> ? FieldKindToType[K][] : F extends FieldBuilder<infer K, any, any> ? K extends keyof FieldKindToType ? FieldKindToType[K] : unknown : F extends {
     kind: 'enum';
     enumValues: infer V;
 } ? V extends readonly (infer S)[] ? S : string : F extends {
@@ -719,7 +934,7 @@ declare function migrationStepsToSQL(steps: readonly MigrationStep[]): string[];
  *
  * const rollbackSQL = rollbackStepsToSQL(migration)
  * // ['DROP INDEX IF EXISTS idx_todos_priority',
- * //  'ALTER TABLE todos DROP COLUMN priority']
+ * //  'ALTER TABLE "todos" DROP COLUMN "priority"']
  * ```
  */
 declare function rollbackStepsToSQL(migration: MigrationDefinition): string[];
@@ -910,4 +1125,4 @@ interface ProtoOutput {
  */
 declare function generateProtoDefinitions(schema: SchemaDefinition): ProtoOutput;
 
-export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createReversibleMigration, createVersionVector, decodeBytesFromOpData, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, isApplyFailure, isAtomicOp, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, resolveAtomicOp, rollbackStepsToSQL, serializeVector, toAtomicOp, validateRecord, validateTransition, vectorsEqual };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReplayOperation, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyAtomicOp, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, quoteIdent, replayOperationsForRecord, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { R as RandomSource, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, C as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, b as CollectionDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-BynBOsO3.js';
-export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, B as SequenceConfig, D as StateMachineDefinition, G as SyncDiagnosticsSnapshot, I as SyncRuleDefinition, J as TimeSource, L as migrate, N as t } from './events-BynBOsO3.js';
-export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-D5WOZYvy.js';
-export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-DOf4JLTh.js';
+import { R as RandomSource, B as BlobRef, C as CollectionDefinition, A as AtomicOpType, a as AtomicOp, F as FieldBuilder, b as CustomResolver, M as MigrationDefinition, S as SchemaDefinition, c as RelationDefinition, O as OperationType, E as EnumFieldBuilder, J as JsonFieldBuilder, d as ArrayFieldBuilder, e as FieldKind, f as Operation, V as VersionVector, g as MigrationStep, h as StateMachineConstraint, T as TransitionMap, i as TransitionValidationResult } from './events-3z0Tema3.js';
+export { j as CONNECTION_QUALITIES, k as ConnectionQuality, l as Constraint, m as FieldDescriptor, n as FieldMergeStrategy, H as HLCTimestamp, K as KoraEvent, o as KoraEventByType, p as KoraEventEmitter, q as KoraEventListener, r as KoraEventType, s as MERGE_STRATEGIES, t as MergeStrategy, u as MergeTrace, v as MigrationBuilder, w as OnDeleteAction, x as OperationInput, y as RelationType, z as RollbackBuilder, D as SecretMode, G as SequenceConfig, I as StateMachineDefinition, L as SyncDiagnosticsSnapshot, N as SyncRuleDefinition, P as TimeSource, Q as migrate, U as t } from './events-3z0Tema3.js';
+export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-ClhEbhoV.js';
+export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-CDpIGOsf.js';
 
 /**
  * Base error class for all Kora errors.
@@ -161,6 +161,137 @@ declare function extractTimestamp(uuid: string): number;
  */
 declare function isValidUUIDv7(uuid: string): boolean;
 
+/**
+ * Compute the hex-encoded SHA-256 content hash of a byte buffer.
+ *
+ * This is the content address of a blob: identical bytes always hash to the same
+ * value, which is what lets the blob store deduplicate content and lets a peer
+ * skip transferring bytes it already holds.
+ *
+ * @param bytes - The binary content to hash
+ * @returns The hex-encoded SHA-256 hash
+ */
+declare function hashBlob(bytes: Uint8Array): Promise<string>;
+/** Optional metadata carried alongside a blob reference. */
+interface BlobRefMetadata {
+    mimeType?: string;
+    filename?: string;
+}
+/**
+ * Create a content-addressed {@link BlobRef} for a byte buffer.
+ *
+ * @param bytes - The binary content
+ * @param metadata - Optional MIME type and filename
+ * @returns A reference carrying the content hash, size, and metadata
+ */
+declare function createBlobRef(bytes: Uint8Array, metadata?: BlobRefMetadata): Promise<BlobRef>;
+/**
+ * Type guard: whether a value is a structurally valid {@link BlobRef}.
+ *
+ * Validates the shape only (a non-empty hex hash and a non-negative size); it
+ * does not verify that the bytes behind the hash exist or match. Integrity
+ * verification against the actual bytes happens in the blob store on read.
+ */
+declare function isBlobRef(value: unknown): value is BlobRef;
+
+/**
+ * Field-level cryptography for `secret` fields.
+ *
+ * Two protection modes, matching the two ways secrets are used:
+ * - `encrypted`: reversible AES-256-GCM (tokens, API keys — decrypt to use).
+ * - `hashed`: one-way PBKDF2-SHA-256 with a random salt (passwords — verify only).
+ *
+ * These primitives use only the standard WebCrypto API so they live in
+ * `@korajs/core` with no dependency on `@korajs/auth`; a `secret` field is
+ * therefore self-contained. Higher-level key management composes on top.
+ */
+/**
+ * Encrypt a secret's plaintext with AES-256-GCM under a key derived from
+ * `secretKey`. The returned string bundles the salt, IV, and ciphertext (all hex,
+ * dot-separated) so it is self-describing and safe to store and sync.
+ *
+ * @param plaintext - The secret value to protect
+ * @param secretKey - The key material (from a key provider), never stored
+ * @returns An opaque `v1.salt.iv.ciphertext` string
+ */
+declare function encryptSecret(plaintext: string, secretKey: string): Promise<string>;
+/**
+ * Decrypt a value produced by {@link encryptSecret} with the same key.
+ *
+ * @param encrypted - The `v1.salt.iv.ciphertext` string
+ * @param secretKey - The key material used to encrypt
+ * @returns The original plaintext
+ * @throws If the format is invalid or the key is wrong (GCM auth failure)
+ */
+declare function decryptSecret(encrypted: string, secretKey: string): Promise<string>;
+/**
+ * One-way hash a secret (a password) with PBKDF2-SHA-256 and a random salt.
+ * The result bundles the salt and hash so {@link verifySecret} needs nothing
+ * else. There is no way to recover the plaintext from the result.
+ *
+ * @param plaintext - The secret value to hash
+ * @returns An opaque `v1.salt.hash` string
+ */
+declare function hashSecret(plaintext: string): Promise<string>;
+/**
+ * Verify a plaintext against a value produced by {@link hashSecret}, in constant
+ * time with respect to the stored hash.
+ *
+ * @param plaintext - The candidate secret
+ * @param stored - The `v1.salt.hash` string
+ * @returns Whether the plaintext matches
+ */
+declare function verifySecret(plaintext: string, stored: string): Promise<boolean>;
+
+/**
+ * Provider of the key material used to encrypt reversible (`encrypted`) secret
+ * fields. Called at write and reveal time so the key can be loaded lazily (for
+ * example derived from a user passphrase after unlock). Returns undefined when
+ * no key is available.
+ */
+type SecretKeyProvider = () => string | undefined | Promise<string | undefined>;
+/** Thrown when an `encrypted` secret field is written or read without a key. */
+declare class MissingSecretKeyError extends Error {
+    readonly field: string;
+    constructor(field: string);
+}
+/**
+ * Transform the secret fields of a record's write payload into their at-rest
+ * form BEFORE the operation is created, so plaintext never enters the operation
+ * log, the store, or the sync stream.
+ *
+ * - `hashed` fields become a one-way salted hash.
+ * - `encrypted` fields become ciphertext (requires a key).
+ *
+ * Non-secret fields, and secret fields not present in `data`, are passed through
+ * untouched. Null/undefined secret values are left as-is (nothing to protect).
+ *
+ * @param data - The validated write payload (plaintext secret values)
+ * @param collectionDef - The collection definition (for field kinds/modes)
+ * @param keyProvider - Supplies the encryption key for `encrypted` fields
+ * @returns A new payload with secret fields replaced by their at-rest form
+ */
+declare function transformSecretFieldsForWrite(data: Record<string, unknown>, collectionDef: CollectionDefinition, keyProvider?: SecretKeyProvider): Promise<Record<string, unknown>>;
+/**
+ * Reveal the plaintext of an `encrypted` secret field's stored value. Throws for
+ * `hashed` fields, which are one-way and cannot be revealed.
+ *
+ * @param storedValue - The at-rest value (ciphertext)
+ * @param mode - The field's secret mode
+ * @param keyProvider - Supplies the decryption key
+ * @param field - Field name (for error messages)
+ * @returns The decrypted plaintext
+ */
+declare function revealSecret(storedValue: string, mode: 'hashed' | 'encrypted', keyProvider: SecretKeyProvider | undefined, field?: string): Promise<string>;
+/**
+ * Verify a plaintext candidate against a `hashed` secret field's stored value.
+ *
+ * @param candidate - The plaintext to check (for example a login password)
+ * @param storedValue - The stored one-way hash
+ * @returns Whether the candidate matches
+ */
+declare function verifySecretValue(candidate: string, storedValue: string): Promise<boolean>;
+
 /**
  * Outcome of applying a single operation to materialized storage (local or remote).
  */
@@ -228,6 +359,20 @@ interface AtomicOpSentinel {
  * @returns true if the value is an AtomicOpSentinel
  */
 declare function isAtomicOp(value: unknown): value is AtomicOpSentinel;
+/**
+ * Apply a plain atomic op (`{ type, value }`) to a current value, producing the
+ * concrete result. This is the single source of truth for atomic-op semantics:
+ * {@link resolveAtomicOp} (sentinel form, used on the write path) delegates here,
+ * and the server's materialization replays stored atomic ops through it, so the
+ * server's materialized view composes concurrent atomic writes identically to the
+ * client. Folding this over a field's writes in HLC order yields, for a same-type
+ * atomic chain, exactly the composed intent (sum of increments, max of maxes, ...).
+ *
+ * @param currentValue - The current value of the field
+ * @param atomicOp - The atomic op to apply (type + operand)
+ * @returns The resulting concrete value
+ */
+declare function applyAtomicOp(currentValue: unknown, atomicOp: AtomicOp): unknown;
 /**
  * Resolve an atomic op sentinel against a current value to produce a concrete result.
  *
@@ -306,6 +451,40 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/** One operation's contribution to a record's materialized state. */
+interface ReplayOperation {
+    type: string;
+    data: Record<string, unknown> | null;
+    /**
+     * Atomic-op intents carried by this operation, per field. When present, a field
+     * is composed (rather than overwritten) if the previous writer on that field was
+     * an atomic op of the same type. Absent means every field resolves by
+     * last-write-wins.
+     */
+    atomicOps?: Record<string, AtomicOp> | null;
+}
+/**
+ * Replay a list of operations (MUST be pre-sorted in HLC total order —
+ * wallTime, then logical, then nodeId) to produce the current state of a single
+ * record, composing atomic-op intents.
+ *
+ * Per field, an atomic op composes onto the running value only when the field's
+ * previous writer was an atomic op of the SAME type (a same-type atomic chain:
+ * concurrent increments sum, maxes take the max, appends accumulate); any other
+ * write, including the first atomic write after a plain set, resolves by
+ * last-write-wins on the resolved value. Because operations are folded in HLC order,
+ * the current op always wins that last-write-wins comparison, so the result is
+ * deterministic and identical on every replica that folds the same operation set.
+ *
+ * This is the single definition of atomic materialization shared by the client
+ * (`@korajs/store` apply pipeline) and the server (`@korajs/server` materialization),
+ * so both converge to the same value for any number of concurrent atomic writers.
+ *
+ * Returns the record field data (without `id`) or null if the record was deleted
+ * or never inserted.
+ */
+declare function replayOperationsForRecord(ops: ReplayOperation[]): Record<string, unknown> | null;
+
 /**
  * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
  * `op.previousData` (currently richtext field values). A raw Uint8Array
@@ -474,6 +653,38 @@ declare function generateSQL(collectionName: string, collection: CollectionDefin
  */
 declare function generateFullDDL(schema: SchemaDefinition): string[];
 
+/**
+ * Quote a SQL identifier (table or column name) for safe interpolation into
+ * generated SQL.
+ *
+ * Uses standard double-quote quoting, which both SQLite and PostgreSQL honor,
+ * and doubles any embedded double-quote per the SQL standard. Quoting is what
+ * lets a valid JavaScript identifier — camelCase (`formResponses`), PascalCase
+ * (`UserProfiles`), or a word that happens to be a SQL keyword (`order`,
+ * `select`) — round-trip through generated DDL and queries without ever
+ * producing invalid or ambiguous SQL.
+ *
+ * Schema validation (see `validateCollectionName` / `validateFieldName`)
+ * already restricts identifiers to `[A-Za-z][A-Za-z0-9_]*`, so the escape here
+ * never actually fires in practice; it is defense in depth so this helper is
+ * correct for any input rather than only for pre-validated names.
+ *
+ * Consistency is the contract: every path that emits an identifier for a
+ * user-defined collection or field MUST go through this helper, because a
+ * quoted `CREATE TABLE "order"` paired with an unquoted `SELECT ... FROM order`
+ * would reintroduce the exact keyword-collision bug this guards against.
+ *
+ * @param name - The raw identifier (collection name, field/column name).
+ * @returns The identifier wrapped in double quotes, ready to splice into SQL.
+ *
+ * @example
+ * ```typescript
+ * quoteIdent('formResponses') // => '"formResponses"'
+ * quoteIdent('order')         // => '"order"'
+ * ```
+ */
+declare function quoteIdent(name: string): string;
+
 /**
  * Validates a record's data against a collection's field definitions.
  * Applies defaults, rejects auto fields, and type-checks each value.
@@ -508,12 +719,16 @@ interface FieldKindToType {
     richtext: string;
     enum: string;
     array: unknown[];
+    object: Record<string, unknown>;
+    json: unknown;
+    blob: BlobRef;
+    secret: string;
 }
 /**
  * Infers the TypeScript type for a single field descriptor or builder.
  * Supports both FieldBuilder (class instances) and FieldDescriptor (compiled objects).
  */
-type InferFieldType<F> = F extends EnumFieldBuilder<infer V, any, any> ? V[number] : F extends ArrayFieldBuilder<infer K, any, any> ? FieldKindToType[K][] : F extends FieldBuilder<infer K, any, any> ? K extends keyof FieldKindToType ? FieldKindToType[K] : unknown : F extends {
+type InferFieldType<F> = F extends EnumFieldBuilder<infer V, any, any> ? V[number] : F extends JsonFieldBuilder<infer T, any, any> ? T : F extends ArrayFieldBuilder<infer K, any, any> ? FieldKindToType[K][] : F extends FieldBuilder<infer K, any, any> ? K extends keyof FieldKindToType ? FieldKindToType[K] : unknown : F extends {
     kind: 'enum';
     enumValues: infer V;
 } ? V extends readonly (infer S)[] ? S : string : F extends {
@@ -719,7 +934,7 @@ declare function migrationStepsToSQL(steps: readonly MigrationStep[]): string[];
  *
  * const rollbackSQL = rollbackStepsToSQL(migration)
  * // ['DROP INDEX IF EXISTS idx_todos_priority',
- * //  'ALTER TABLE todos DROP COLUMN priority']
+ * //  'ALTER TABLE "todos" DROP COLUMN "priority"']
  * ```
  */
 declare function rollbackStepsToSQL(migration: MigrationDefinition): string[];
@@ -910,4 +1125,4 @@ interface ProtoOutput {
  */
 declare function generateProtoDefinitions(schema: SchemaDefinition): ProtoOutput;
 
-export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createReversibleMigration, createVersionVector, decodeBytesFromOpData, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, isApplyFailure, isAtomicOp, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, resolveAtomicOp, rollbackStepsToSQL, serializeVector, toAtomicOp, validateRecord, validateTransition, vectorsEqual };
+export { APPLY_FAILURE_CODES, APPLY_RESULTS, AppNotReadyError, type ApplyFailureReason, type ApplyResult, ArrayFieldBuilder, AtomicOp, type AtomicOpSentinel, AtomicOpType, BlobRef, type BlobRefMetadata, CausalTracker, ClockDriftError, CollectionDefinition, type CollectionInput, type ConstraintInput, CustomResolver, EnumFieldBuilder, FieldBuilder, FieldKind, type FieldKindToType, type InferFieldType, type InferInsertInput, type InferRecord, type InferUpdateInput, InvalidTimestampError, KORA_ERROR_FIX_SUGGESTIONS, type KoraBytesValue, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, MissingSecretKeyError, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, RemoteClockDriftError, type ReplayOperation, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyAtomicOp, applyOperationTransforms, base64ToBytes, buildStateMachineConstraints, bytesToBase64, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createBlobRef, createReversibleMigration, createVersionVector, decodeBytesFromOpData, decryptSecret, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, encodeBytesForOpData, encryptSecret, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, hashBlob, hashSecret, isApplyFailure, isAtomicOp, isBlobRef, isCollectionSyncScoped, isKoraBytesValue, isLegacyNumericByteObject, isValidUUIDv7, mergeVectors, migrationStepsToSQL, op, quoteIdent, replayOperationsForRecord, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };