@korajs/core 1.0.0-beta.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-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-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.
@@ -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).
  */
@@ -508,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 {
@@ -910,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, 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 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-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-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.
@@ -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).
  */
@@ -508,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 {
@@ -910,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, 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 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 };