@korajs/core 0.6.0 → 1.0.0-beta.1

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-D-FWfFg8.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-D-FWfFg8.cjs';
-export { H as HybridLogicalClock, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-3-ZJJf3w.cjs';
-export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-B1CcncZN.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-CqDkr1LN.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-CqDkr1LN.cjs';
+export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-CFoY-ZmB.cjs';
+export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-DtTr9C7A.cjs';
 
 /**
  * Base error class for all Kora errors.
@@ -71,6 +71,23 @@ declare class AppNotReadyError extends KoraError {
  * Thrown when the HLC detects excessive clock drift.
  * Drift > 60s: warning. Drift > 5min: this error is thrown, refusing to generate timestamps.
  */
+declare class RemoteClockDriftError extends KoraError {
+    readonly remoteWallTime: number;
+    readonly localReferenceTime: number;
+    constructor(remoteWallTime: number, localReferenceTime: number);
+}
+/**
+ * Thrown when an HLC timestamp has structurally invalid fields: non-integer or
+ * negative wallTime/logical, or a logical counter beyond the serializable cap.
+ * Rejected BEFORE any clock state changes, so a malformed remote timestamp can
+ * never corrupt a replica's clock or break the lexicographic ordering of the
+ * serialized form.
+ */
+declare class InvalidTimestampError extends KoraError {
+    readonly wallTime: number;
+    readonly logical: number;
+    constructor(message: string, wallTime: number, logical: number);
+}
 declare class ClockDriftError extends KoraError {
     readonly currentHlcTime: number;
     readonly physicalTime: number;
@@ -144,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).
  */
@@ -289,6 +437,57 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/**
+ * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
+ * `op.previousData` (currently richtext field values). A raw Uint8Array
+ * JSON-serializes to a numeric-key object and an ArrayBuffer to `{}` (silent
+ * data loss), which breaks content-hash stability, persistence round-trips,
+ * remote application, and merge. Tagging the bytes as base64 at
+ * operation-creation time makes the hashed value, the persisted JSON, the wire
+ * payload, and the value the merge engine sees the identical canonical value.
+ *
+ * This convention lives in `@korajs/core` because `op.data` is a core concept:
+ * both `@korajs/store` (persistence, creation) and `@korajs/merge` (CRDT merge)
+ * must agree on it, and neither may depend on the other.
+ */
+interface KoraBytesValue {
+    $koraBytes: string;
+}
+/**
+ * Type guard for the tagged binary form. Requires exactly the single
+ * `$koraBytes` key so arbitrary user objects that happen to contain the key
+ * are never silently reinterpreted as bytes.
+ */
+declare function isKoraBytesValue(value: unknown): value is KoraBytesValue;
+/**
+ * Detects the numeric-key object shape a raw Uint8Array produced when
+ * JSON-serialized before the tagged encoding existed ({"0":1,"1":2,...}).
+ */
+declare function isLegacyNumericByteObject(value: unknown): value is Record<string, number>;
+/**
+ * Dependency-free base64 encoder. btoa is unavailable for bytes in Node and
+ * Buffer is unavailable in browsers, so a manual implementation is the only
+ * deterministic option that works in every runtime Kora targets.
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Inverse of {@link bytesToBase64}.
+ */
+declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Normalize a validated binary-or-string value into the canonical form stored
+ * in `op.data`: strings pass through unchanged (backward compatible with every
+ * existing operation), binary values become the tagged base64 form.
+ */
+declare function encodeBytesForOpData(value: string | Uint8Array | ArrayBuffer): string | KoraBytesValue;
+/**
+ * Reverse of {@link encodeBytesForOpData}, tolerant of every shape a binary
+ * op-data value has ever taken: canonical strings and tagged bytes, in-memory
+ * Uint8Array/ArrayBuffer (ops that never round-tripped through JSON), and
+ * pre-fix numeric-key objects.
+ */
+declare function decodeBytesFromOpData(value: unknown): string | Uint8Array;
+
 /**
  * Input shape for defineSchema() — what the developer writes.
  */
@@ -440,12 +639,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 {
@@ -842,4 +1045,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, KORA_ERROR_FIX_SUGGESTIONS, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, buildStateMachineConstraints, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createReversibleMigration, createVersionVector, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, isApplyFailure, isAtomicOp, isCollectionSyncScoped, 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 ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, 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, 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-D-FWfFg8.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-D-FWfFg8.js';
-export { H as HybridLogicalClock, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-CygOwIjZ.js';
-export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-BmgAT82h.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-CqDkr1LN.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-CqDkr1LN.js';
+export { H as HybridLogicalClock, M as MAX_LOGICAL, c as createOperation, i as isValidOperation, v as verifyOperationIntegrity } from './operation-BJtu18Fi.js';
+export { S as ScopeMap, b as buildScopeMap } from './build-scope-map-DvOHbYjn.js';
 
 /**
  * Base error class for all Kora errors.
@@ -71,6 +71,23 @@ declare class AppNotReadyError extends KoraError {
  * Thrown when the HLC detects excessive clock drift.
  * Drift > 60s: warning. Drift > 5min: this error is thrown, refusing to generate timestamps.
  */
+declare class RemoteClockDriftError extends KoraError {
+    readonly remoteWallTime: number;
+    readonly localReferenceTime: number;
+    constructor(remoteWallTime: number, localReferenceTime: number);
+}
+/**
+ * Thrown when an HLC timestamp has structurally invalid fields: non-integer or
+ * negative wallTime/logical, or a logical counter beyond the serializable cap.
+ * Rejected BEFORE any clock state changes, so a malformed remote timestamp can
+ * never corrupt a replica's clock or break the lexicographic ordering of the
+ * serialized form.
+ */
+declare class InvalidTimestampError extends KoraError {
+    readonly wallTime: number;
+    readonly logical: number;
+    constructor(message: string, wallTime: number, logical: number);
+}
 declare class ClockDriftError extends KoraError {
     readonly currentHlcTime: number;
     readonly physicalTime: number;
@@ -144,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).
  */
@@ -289,6 +437,57 @@ declare const op: {
  */
 declare function toAtomicOp(sentinel: AtomicOpSentinel): AtomicOp;
 
+/**
+ * Canonical JSON-safe encoding of binary bytes stored inside `op.data` /
+ * `op.previousData` (currently richtext field values). A raw Uint8Array
+ * JSON-serializes to a numeric-key object and an ArrayBuffer to `{}` (silent
+ * data loss), which breaks content-hash stability, persistence round-trips,
+ * remote application, and merge. Tagging the bytes as base64 at
+ * operation-creation time makes the hashed value, the persisted JSON, the wire
+ * payload, and the value the merge engine sees the identical canonical value.
+ *
+ * This convention lives in `@korajs/core` because `op.data` is a core concept:
+ * both `@korajs/store` (persistence, creation) and `@korajs/merge` (CRDT merge)
+ * must agree on it, and neither may depend on the other.
+ */
+interface KoraBytesValue {
+    $koraBytes: string;
+}
+/**
+ * Type guard for the tagged binary form. Requires exactly the single
+ * `$koraBytes` key so arbitrary user objects that happen to contain the key
+ * are never silently reinterpreted as bytes.
+ */
+declare function isKoraBytesValue(value: unknown): value is KoraBytesValue;
+/**
+ * Detects the numeric-key object shape a raw Uint8Array produced when
+ * JSON-serialized before the tagged encoding existed ({"0":1,"1":2,...}).
+ */
+declare function isLegacyNumericByteObject(value: unknown): value is Record<string, number>;
+/**
+ * Dependency-free base64 encoder. btoa is unavailable for bytes in Node and
+ * Buffer is unavailable in browsers, so a manual implementation is the only
+ * deterministic option that works in every runtime Kora targets.
+ */
+declare function bytesToBase64(bytes: Uint8Array): string;
+/**
+ * Inverse of {@link bytesToBase64}.
+ */
+declare function base64ToBytes(base64: string): Uint8Array;
+/**
+ * Normalize a validated binary-or-string value into the canonical form stored
+ * in `op.data`: strings pass through unchanged (backward compatible with every
+ * existing operation), binary values become the tagged base64 form.
+ */
+declare function encodeBytesForOpData(value: string | Uint8Array | ArrayBuffer): string | KoraBytesValue;
+/**
+ * Reverse of {@link encodeBytesForOpData}, tolerant of every shape a binary
+ * op-data value has ever taken: canonical strings and tagged bytes, in-memory
+ * Uint8Array/ArrayBuffer (ops that never round-tripped through JSON), and
+ * pre-fix numeric-key objects.
+ */
+declare function decodeBytesFromOpData(value: unknown): string | Uint8Array;
+
 /**
  * Input shape for defineSchema() — what the developer writes.
  */
@@ -440,12 +639,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 {
@@ -842,4 +1045,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, KORA_ERROR_FIX_SUGGESTIONS, KoraError, MergeConflictError, MigrationDefinition, MigrationRollbackError, MigrationStep, Operation, OperationError, type OperationLog, type OperationTransform, OperationType, type ProtoOutput, RandomSource, RelationDefinition, type RelationInput, type ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, applyOperationTransforms, buildStateMachineConstraints, canAutoRollback, collectSchemaScopeFields, collectSchemaScopeValueKeys, computeDelta, createReversibleMigration, createVersionVector, defaultApplyFailureReason, defaultSequenceFormat, defineSchema, deserializeVector, dominates, extractScopeValuesFromClaims, extractTimestamp, formatSequenceValue, generateFullDDL, generateProtoDefinitions, generateRollbackSteps, generateSQL, generateUUIDv7, getCollectionScopeBindings, getKoraErrorFix, getTransitionMap, hasSchemaSyncRules, isApplyFailure, isAtomicOp, isCollectionSyncScoped, 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 ReversibleMigration, SchemaDefinition, type SchemaInput, SchemaValidationError, type SecretKeyProvider, StateMachineConstraint, type StateMachineInput, StorageError, SyncError, TransitionMap, TransitionValidationResult, type TypedSchemaDefinition, VersionVector, advanceVector, 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, resolveAtomicOp, revealSecret, rollbackStepsToSQL, serializeVector, toAtomicOp, transformSecretFieldsForWrite, validateRecord, validateTransition, vectorsEqual, verifySecret, verifySecretValue };