@korajs/server 0.6.1 → 1.0.0-beta.1

package/dist/index.cjs

@@ -250,10 +250,11 @@ function createDefaultLogger() {
 
 // src/store/memory-server-store.ts
 init_cjs_shims();
-var import_core = require("@korajs/core");
+var import_core2 = require("@korajs/core");
 
 // src/store/materialization.ts
 init_cjs_shims();
+var import_core = require("@korajs/core");
 function fieldTypeToSql(descriptor, dialect) {
   switch (descriptor.kind) {
     case "string":
@@ -349,6 +350,52 @@ function replayOperationsForRecord(ops) {
   }
   return deleted ? null : record;
 }
+var BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+var BASE64_REVERSE = new Map(
+  Array.from(BASE64_ALPHABET, (char, index3) => [char, index3])
+);
+function base64ToBytes(base64) {
+  const cleaned = base64.replace(/=+$/, "");
+  const out = new Uint8Array(Math.floor(cleaned.length * 6 / 8));
+  let buffer = 0;
+  let bits = 0;
+  let index3 = 0;
+  for (const char of cleaned) {
+    const value = BASE64_REVERSE.get(char);
+    if (value === void 0) {
+      throw new import_core.StorageError(`Invalid base64 character "${char}" in tagged richtext value`, {
+        char
+      });
+    }
+    buffer = buffer << 6 | value;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[index3] = buffer >> bits & 255;
+      index3 += 1;
+    }
+  }
+  return out;
+}
+function decodeRichtextColumnValue(value) {
+  if (typeof value !== "object" || value === null || ArrayBuffer.isView(value)) {
+    return value;
+  }
+  const record = value;
+  if (Object.keys(record).length === 1 && typeof record.$koraBytes === "string") {
+    return base64ToBytes(record.$koraBytes);
+  }
+  const keys = Object.keys(record);
+  if (keys.length > 0 && keys.every((k, i) => k === String(i) && typeof record[k] === "number")) {
+    const bytes = new Uint8Array(keys.length);
+    for (let i = 0; i < keys.length; i++) {
+      const byte = record[String(i)];
+      bytes[i] = typeof byte === "number" ? byte & 255 : 0;
+    }
+    return bytes;
+  }
+  return value;
+}
 function serializeFieldValue(value, descriptor) {
   if (value === null || value === void 0) return null;
   switch (descriptor.kind) {
@@ -356,6 +403,8 @@ function serializeFieldValue(value, descriptor) {
       return typeof value === "string" ? value : JSON.stringify(value);
     case "boolean":
       return value ? 1 : 0;
+    case "richtext":
+      return decodeRichtextColumnValue(value);
     default:
       return value;
   }
@@ -401,7 +450,7 @@ var MemoryServerStore = class {
   materializedRecords = /* @__PURE__ */ new Map();
   closed = false;
   constructor(nodeId) {
-    this.nodeId = nodeId ?? (0, import_core.generateUUIDv7)();
+    this.nodeId = nodeId ?? (0, import_core2.generateUUIDv7)();
   }
   getVersionVector() {
     return new Map(this.versionVector);
@@ -738,7 +787,7 @@ var MemoryServerStore = class {
 
 // src/store/postgres-server-store.ts
 init_cjs_shims();
-var import_core2 = require("@korajs/core");
+var import_core3 = require("@korajs/core");
 var import_drizzle_orm = require("drizzle-orm");
 
 // src/store/drizzle-pg-schema.ts
@@ -787,7 +836,7 @@ var PostgresServerStore = class {
   closed = false;
   constructor(db, nodeId) {
     this.db = db;
-    this.nodeId = nodeId ?? (0, import_core2.generateUUIDv7)();
+    this.nodeId = nodeId ?? (0, import_core3.generateUUIDv7)();
     this.ready = this.initialize();
   }
   getVersionVector() {
@@ -1323,7 +1372,7 @@ async function loadPostgresDeps() {
 // src/store/sqlite-server-store.ts
 init_cjs_shims();
 var import_node_module = require("module");
-var import_core3 = require("@korajs/core");
+var import_core4 = require("@korajs/core");
 var import_drizzle_orm2 = require("drizzle-orm");
 
 // src/store/drizzle-schema.ts
@@ -1371,7 +1420,7 @@ var SqliteServerStore = class {
   closed = false;
   constructor(db, nodeId) {
     this.db = db;
-    this.nodeId = nodeId ?? (0, import_core3.generateUUIDv7)();
+    this.nodeId = nodeId ?? (0, import_core4.generateUUIDv7)();
     this.ensureTables();
   }
   getVersionVector() {
@@ -1869,7 +1918,7 @@ function createSqliteServerStore(options) {
 
 // src/transport/http-server-transport.ts
 init_cjs_shims();
-var import_core4 = require("@korajs/core");
+var import_core5 = require("@korajs/core");
 var HttpServerTransport = class {
   serializer;
   messageHandler = null;
@@ -1911,7 +1960,7 @@ var HttpServerTransport = class {
   }
   receive(payload) {
     if (!this.connected) {
-      throw new import_core4.SyncError("HTTP server transport is closed");
+      throw new import_core5.SyncError("HTTP server transport is closed");
     }
     try {
       const message = this.serializer.decode(payload);
@@ -1951,7 +2000,7 @@ var HttpServerTransport = class {
 
 // src/transport/ws-server-transport.ts
 init_cjs_shims();
-var import_core5 = require("@korajs/core");
+var import_core6 = require("@korajs/core");
 var import_sync = require("@korajs/sync");
 var WS_OPEN = 1;
 var WsServerTransport = class {
@@ -1967,7 +2016,7 @@ var WsServerTransport = class {
   }
   send(message) {
     if (this.ws.readyState !== WS_OPEN) {
-      throw new import_core5.SyncError("Cannot send message: WebSocket is not open", {
+      throw new import_core6.SyncError("Cannot send message: WebSocket is not open", {
         readyState: this.ws.readyState,
         messageType: message.type
       });
@@ -1994,7 +2043,7 @@ var WsServerTransport = class {
     this.ws.on("message", (data) => {
       try {
         if (typeof data !== "string" && !(data instanceof Uint8Array) && !(data instanceof ArrayBuffer)) {
-          throw new import_core5.SyncError("Unsupported WebSocket payload type", {
+          throw new import_core6.SyncError("Unsupported WebSocket payload type", {
             payloadType: typeof data
           });
         }
@@ -2015,9 +2064,10 @@ var WsServerTransport = class {
 
 // src/session/client-session.ts
 init_cjs_shims();
-var import_core8 = require("@korajs/core");
+var import_core10 = require("@korajs/core");
 var import_internal = require("@korajs/core/internal");
 var import_sync2 = require("@korajs/sync");
+var import_sync3 = require("@korajs/sync");
 
 // src/apply/apply-server-operation.ts
 init_cjs_shims();
@@ -2107,12 +2157,12 @@ function createServerReferentialContext(store) {
 
 // src/apply/server-side-effect-operation.ts
 init_cjs_shims();
-var import_core6 = require("@korajs/core");
+var import_core7 = require("@korajs/core");
 async function createServerSideEffectOperation(store, parentOp, effect, schemaVersion, sequenceNumber) {
   const nodeId = store.getNodeId();
-  const clock = new import_core6.HybridLogicalClock(nodeId);
+  const clock = new import_core7.HybridLogicalClock(nodeId);
   clock.receive(parentOp.timestamp);
-  return (0, import_core6.createOperation)(
+  return (0, import_core7.createOperation)(
     {
       nodeId,
       type: effect.type === "delete" ? "delete" : "update",
@@ -2190,21 +2240,29 @@ async function applyServerOperation(store, op, relationLookup) {
   };
 }
 
+// src/auth/no-auth.ts
+init_cjs_shims();
+var NoAuthProvider = class {
+  async authenticate(_token) {
+    return { userId: "anonymous" };
+  }
+};
+
 // src/scopes/resolve-session-scopes.ts
 init_cjs_shims();
-var import_core7 = require("@korajs/core");
+var import_core8 = require("@korajs/core");
 function resolveSessionScopes(schema, options) {
   const { handshakeScope, authScopes, scopeValues } = options;
   let resolved;
   if (schema && scopeValues && Object.keys(scopeValues).length > 0) {
-    resolved = (0, import_core7.buildScopeMap)(schema, scopeValues);
+    resolved = (0, import_core8.buildScopeMap)(schema, scopeValues);
   } else if (handshakeScope) {
     resolved = { ...handshakeScope };
   } else if (authScopes) {
     resolved = { ...authScopes };
   }
   if (schema && !resolved && scopeValues) {
-    resolved = (0, import_core7.buildScopeMap)(schema, scopeValues);
+    resolved = (0, import_core8.buildScopeMap)(schema, scopeValues);
   }
   if (authScopes) {
     resolved = mergeScopeMaps(resolved, authScopes, "auth");
@@ -2259,9 +2317,17 @@ function asRecord(value) {
 
 // src/session/operation-validation.ts
 init_cjs_shims();
+var import_core9 = require("@korajs/core");
 var SERVER_MAX_TIMESTAMP_FUTURE_MS = 6e4;
 function isOperationTimestampValid(op, now = Date.now()) {
-  return op.timestamp.wallTime <= now + SERVER_MAX_TIMESTAMP_FUTURE_MS;
+  const { wallTime, logical } = op.timestamp;
+  if (!Number.isInteger(wallTime) || wallTime < 0) {
+    return false;
+  }
+  if (!Number.isInteger(logical) || logical < 0 || logical > import_core9.MAX_LOGICAL) {
+    return false;
+  }
+  return wallTime <= now + SERVER_MAX_TIMESTAMP_FUTURE_MS;
 }
 
 // src/session/session-operation-limits.ts
@@ -2311,6 +2377,25 @@ var SessionRateLimiter = class {
 // src/session/client-session.ts
 var DEFAULT_BATCH_SIZE = 100;
 var DEFAULT_SCHEMA_VERSION = 1;
+var warnedUnscopedProviders = /* @__PURE__ */ new WeakSet();
+function warnIfMultiTenantWithoutScopes(auth, resolvedScopes, schema) {
+  if (!auth || auth instanceof NoAuthProvider) {
+    return;
+  }
+  if (resolvedScopes) {
+    return;
+  }
+  if (!schema || Object.keys(schema.collections).length === 0) {
+    return;
+  }
+  if (warnedUnscopedProviders.has(auth)) {
+    return;
+  }
+  warnedUnscopedProviders.add(auth);
+  console.warn(
+    "[kora] An authenticated session resolved to no sync scopes, so every user will sync every other user's data. Return per-user sync scopes from your auth provider (for example KoraAuthProvider's resolveScopes) to isolate tenants. Note: declaring sync rules in your schema is not enough on its own \u2014 the per-user values come from the auth provider. (This warning is expected for single-tenant apps where all authenticated users are meant to share the same data.)"
+  );
+}
 var ClientSession = class {
   state = "connected";
   clientNodeId = null;
@@ -2329,6 +2414,9 @@ var ClientSession = class {
   onRelay;
   onAwarenessUpdate;
   onYjsDocUpdate;
+  onBlobChunkRequest;
+  onBlobChunkResponse;
+  persistBlobChunk;
   onClose;
   maxOperationBytes;
   maxOpsPerMinute;
@@ -2338,7 +2426,7 @@ var ClientSession = class {
     this.transport = options.transport;
     this.store = options.store;
     this.auth = options.auth ?? null;
-    this.serializer = options.serializer ?? new import_sync2.NegotiatedMessageSerializer("json");
+    this.serializer = options.serializer ?? new import_sync3.NegotiatedMessageSerializer("json");
     this.emitter = options.emitter ?? null;
     this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
     this.schemaVersion = options.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
@@ -2350,6 +2438,9 @@ var ClientSession = class {
     this.onRelay = options.onRelay ?? null;
     this.onAwarenessUpdate = options.onAwarenessUpdate ?? null;
     this.onYjsDocUpdate = options.onYjsDocUpdate ?? null;
+    this.onBlobChunkRequest = options.onBlobChunkRequest ?? null;
+    this.onBlobChunkResponse = options.onBlobChunkResponse ?? null;
+    this.persistBlobChunk = options.persistBlobChunk ?? null;
     this.onClose = options.onClose ?? null;
     this.maxOperationBytes = options.maxOperationBytes ?? DEFAULT_MAX_OPERATION_BYTES;
     this.maxOpsPerMinute = options.maxOpsPerMinute ?? DEFAULT_MAX_OPS_PER_MINUTE;
@@ -2379,7 +2470,7 @@ var ClientSession = class {
     const serializedOps = visibleOperations.map((op) => this.serializer.encodeOperation(op));
     const msg = {
       type: "operation-batch",
-      messageId: (0, import_core8.generateUUIDv7)(),
+      messageId: (0, import_core10.generateUUIDv7)(),
       operations: serializedOps,
       isFinal: true,
       batchIndex: 0
@@ -2455,7 +2546,32 @@ var ClientSession = class {
       case "yjs-doc-update":
         this.handleYjsDocUpdate(message);
         break;
+      case "blob-chunk-request":
+        this.onBlobChunkRequest?.(this.sessionId, message);
+        break;
+      case "blob-chunk-response":
+        this.onBlobChunkResponse?.(this.sessionId, message);
+        break;
+      case "blob-chunk-push":
+        await this.handleBlobChunkPush(message);
+        break;
+    }
+  }
+  /**
+   * Persist a client-uploaded blob chunk (or manifest) centrally. The bytes are
+   * verified to hash to the declared hash before storing, so a corrupt or
+   * mislabeled upload is rejected rather than served later as trusted content.
+   */
+  async handleBlobChunkPush(message) {
+    if (!this.persistBlobChunk) {
+      return;
+    }
+    const bytes = (0, import_sync2.decodeBlobChunkBytes)(message.bytes);
+    const actual = await (0, import_core10.hashBlob)(bytes);
+    if (actual !== message.hash) {
+      return;
     }
+    await this.persistBlobChunk(message.hash, bytes);
   }
   handleMessageFailure(error) {
     const reason = error instanceof Error ? error.message : "Message handling failed";
@@ -2490,27 +2606,29 @@ var ClientSession = class {
         this.authContext = { userId: msg.nodeId, scopes: resolvedScopes };
       }
     }
+    warnIfMultiTenantWithoutScopes(this.auth, resolvedScopes, this.store.getSchema());
     if (msg.syncQueries && msg.syncQueries.length > 0) {
-      this.syncQuerySubsets = (0, import_sync2.dedupeQuerySubsets)(msg.syncQueries);
+      this.syncQuerySubsets = (0, import_sync3.dedupeQuerySubsets)(msg.syncQueries);
     } else {
       this.syncQuerySubsets = [];
     }
-    this.resumeDeltaCursor = msg.deltaCursor ? (0, import_sync2.decodeDeltaCursor)(msg.deltaCursor) : null;
+    this.resumeDeltaCursor = msg.deltaCursor ? (0, import_sync3.decodeDeltaCursor)(msg.deltaCursor) : null;
     const serverVector = this.store.getVersionVector();
     const selectedWireFormat = selectWireFormat(msg.supportedWireFormats);
     this.setSerializerWireFormat(selectedWireFormat);
-    if (!(0, import_sync2.isClientSchemaVersionSupported)(msg.schemaVersion, this.supportedSchemaVersions)) {
+    if (!(0, import_sync3.isClientSchemaVersionSupported)(msg.schemaVersion, this.supportedSchemaVersions)) {
       const { min, max } = this.supportedSchemaVersions;
       const response2 = {
         type: "handshake-response",
-        messageId: (0, import_core8.generateUUIDv7)(),
+        messageId: (0, import_core10.generateUUIDv7)(),
         nodeId: this.store.getNodeId(),
-        versionVector: (0, import_sync2.versionVectorToWire)(serverVector),
+        versionVector: (0, import_sync3.versionVectorToWire)(serverVector),
         schemaVersion: this.schemaVersion,
         accepted: false,
-        rejectReason: `${import_sync2.SCHEMA_MISMATCH_PREFIX}: client schema version ${msg.schemaVersion} not in supported range [${min}, ${max}]`,
+        rejectReason: `${import_sync3.SCHEMA_MISMATCH_PREFIX}: client schema version ${msg.schemaVersion} not in supported range [${min}, ${max}]`,
         supportedSchemaMin: min,
-        supportedSchemaMax: max
+        supportedSchemaMax: max,
+        serverTime: Date.now()
       };
       this.sendToClient(response2);
       this.close("schema version mismatch");
@@ -2518,12 +2636,16 @@ var ClientSession = class {
     }
     const response = {
       type: "handshake-response",
-      messageId: (0, import_core8.generateUUIDv7)(),
+      messageId: (0, import_core10.generateUUIDv7)(),
       nodeId: this.store.getNodeId(),
-      versionVector: (0, import_sync2.versionVectorToWire)(serverVector),
+      versionVector: (0, import_sync3.versionVectorToWire)(serverVector),
       schemaVersion: this.schemaVersion,
       accepted: true,
       selectedWireFormat,
+      serverTime: Date.now(),
+      // Advertise central blob storage so the client uploads the bytes behind
+      // its blob fields, keeping them available after the author goes offline.
+      ...this.persistBlobChunk ? { blobStorageEnabled: true } : {},
       // Confirm the accepted scope so the client knows what data will be synced.
       // This may differ from what the client requested if auth scopes are narrower.
       ...this.authContext?.scopes ? { acceptedScope: this.authContext.scopes } : {}
@@ -2531,7 +2653,7 @@ var ClientSession = class {
     this.sendToClient(response);
     this.emitter?.emit({ type: "sync:connected", nodeId: msg.nodeId });
     this.state = "syncing";
-    const clientVector = (0, import_sync2.wireToVersionVector)(msg.versionVector);
+    const clientVector = (0, import_sync3.wireToVersionVector)(msg.versionVector);
     await this.sendDelta(clientVector);
     this.state = "streaming";
   }
@@ -2600,7 +2722,7 @@ var ClientSession = class {
     const lastOp = operations2[operations2.length - 1];
     const ack = {
       type: "acknowledgment",
-      messageId: (0, import_core8.generateUUIDv7)(),
+      messageId: (0, import_core10.generateUUIDv7)(),
       acknowledgedMessageId: msg.messageId,
       lastSequenceNumber: lastOp ? lastOp.sequenceNumber : 0
     };
@@ -2623,7 +2745,7 @@ var ClientSession = class {
     if (missing.length === 0) {
       const emptyBatch = {
         type: "operation-batch",
-        messageId: (0, import_core8.generateUUIDv7)(),
+        messageId: (0, import_core10.generateUUIDv7)(),
         operations: [],
         isFinal: true,
         batchIndex: 0,
@@ -2633,12 +2755,12 @@ var ClientSession = class {
       return;
     }
     const sorted = (0, import_internal.topologicalSort)(missing);
-    const afterCursor = (0, import_sync2.sliceOperationsAfterCursor)(sorted, this.resumeDeltaCursor);
+    const afterCursor = (0, import_sync3.sliceOperationsAfterCursor)(sorted, this.resumeDeltaCursor);
     const totalBatches = Math.ceil(afterCursor.length / this.batchSize);
     if (afterCursor.length === 0) {
       const emptyBatch = {
         type: "operation-batch",
-        messageId: (0, import_core8.generateUUIDv7)(),
+        messageId: (0, import_core10.generateUUIDv7)(),
         operations: [],
         isFinal: true,
         batchIndex: this.resumeDeltaCursor?.batchIndex ?? 0,
@@ -2651,15 +2773,15 @@ var ClientSession = class {
       const start = i * this.batchSize;
       const batchOps = afterCursor.slice(start, start + this.batchSize);
       const serializedOps = batchOps.map((op) => this.serializer.encodeOperation(op));
-      const batchCursor = (0, import_sync2.createDeltaCursorFromBatch)(batchOps, i);
+      const batchCursor = (0, import_sync3.createDeltaCursorFromBatch)(batchOps, i);
       const batchMsg = {
         type: "operation-batch",
-        messageId: (0, import_core8.generateUUIDv7)(),
+        messageId: (0, import_core10.generateUUIDv7)(),
         operations: serializedOps,
         isFinal: i === totalBatches - 1,
         batchIndex: i,
         totalBatches,
-        ...batchCursor ? { cursor: (0, import_sync2.encodeDeltaCursor)(batchCursor) } : {}
+        ...batchCursor ? { cursor: (0, import_sync3.encodeDeltaCursor)(batchCursor) } : {}
       };
       this.sendToClient(batchMsg);
       this.emitter?.emit({
@@ -2673,7 +2795,7 @@ var ClientSession = class {
     if (!operationMatchesScopes(op, this.authContext?.scopes)) {
       return false;
     }
-    return (0, import_sync2.operationMatchesQuerySubsets)(op, this.syncQuerySubsets);
+    return (0, import_sync3.operationMatchesQuerySubsets)(op, this.syncQuerySubsets);
   }
   handleAwarenessUpdate(msg) {
     this.onAwarenessUpdate?.(this.sessionId, msg);
@@ -2684,7 +2806,7 @@ var ClientSession = class {
   sendError(code, message, retriable) {
     const errorMsg = {
       type: "error",
-      messageId: (0, import_core8.generateUUIDv7)(),
+      messageId: (0, import_core10.generateUUIDv7)(),
       code,
       message,
       retriable
@@ -2712,13 +2834,13 @@ function selectWireFormat(supportedWireFormats) {
 
 // src/server/kora-sync-server.ts
 init_cjs_shims();
-var import_core10 = require("@korajs/core");
+var import_core12 = require("@korajs/core");
 var import_internal2 = require("@korajs/core/internal");
-var import_sync3 = require("@korajs/sync");
+var import_sync5 = require("@korajs/sync");
 
 // src/awareness/awareness-relay.ts
 init_cjs_shims();
-var import_core9 = require("@korajs/core");
+var import_core11 = require("@korajs/core");
 var AwarenessRelay = class {
   clients = /* @__PURE__ */ new Map();
   /**
@@ -2747,7 +2869,7 @@ var AwarenessRelay = class {
     if (hasStates) {
       const catchUpMsg = {
         type: "awareness-update",
-        messageId: (0, import_core9.generateUUIDv7)(),
+        messageId: (0, import_core11.generateUUIDv7)(),
         clientId: 0,
         // Server-sourced
         states: existingStates
@@ -2770,7 +2892,7 @@ var AwarenessRelay = class {
     };
     const msg = {
       type: "awareness-update",
-      messageId: (0, import_core9.generateUUIDv7)(),
+      messageId: (0, import_core11.generateUUIDv7)(),
       clientId: client.clientId,
       states: removalStates
     };
@@ -2931,6 +3053,114 @@ var ServerMetricsCollector = class {
   }
 };
 
+// src/richtext/blob-chunk-relay.ts
+init_cjs_shims();
+var import_sync4 = require("@korajs/sync");
+var BlobChunkRelay = class {
+  clients = /* @__PURE__ */ new Map();
+  /** requestId -> the session that originated the request (to route the answer back). */
+  pending = /* @__PURE__ */ new Map();
+  resolveBlobChunk;
+  constructor(resolveBlobChunk) {
+    this.resolveBlobChunk = resolveBlobChunk ?? null;
+  }
+  addClient(sessionId, transport) {
+    this.clients.set(sessionId, { sessionId, transport });
+  }
+  removeClient(sessionId) {
+    this.clients.delete(sessionId);
+    for (const [requestId, originSessionId] of this.pending) {
+      if (originSessionId === sessionId) {
+        this.pending.delete(requestId);
+      }
+    }
+  }
+  getClientCount() {
+    return this.clients.size;
+  }
+  getPendingCount() {
+    return this.pending.size;
+  }
+  clear() {
+    this.clients.clear();
+    this.pending.clear();
+  }
+  /**
+   * Handle an inbound chunk request from a session. Tries the server's own
+   * store first (if configured), otherwise forwards the request to peer
+   * sessions and remembers who to route the answer back to.
+   */
+  handleRequest(sourceSessionId, message) {
+    if (!this.clients.has(sourceSessionId)) {
+      return;
+    }
+    if (this.resolveBlobChunk) {
+      void this.resolveBlobChunk(message.hash).then(
+        (bytes) => {
+          if (bytes !== null) {
+            this.sendResponseTo(sourceSessionId, message.requestId, (0, import_sync4.encodeBlobChunkBytes)(bytes));
+            return;
+          }
+          this.forwardRequestToPeers(sourceSessionId, message);
+        },
+        () => {
+          this.forwardRequestToPeers(sourceSessionId, message);
+        }
+      );
+      return;
+    }
+    this.forwardRequestToPeers(sourceSessionId, message);
+  }
+  /**
+   * Handle an inbound chunk response from a peer. Routes it back to the session
+   * that originally requested it. A "not held" answer (bytes === null) is
+   * ignored so a peer without the chunk does not preempt one that has it; the
+   * requester's own per-request timeout bounds the wait.
+   */
+  handleResponse(sourceSessionId, message) {
+    if (!this.clients.has(sourceSessionId)) {
+      return;
+    }
+    if (message.bytes === null) {
+      return;
+    }
+    const originSessionId = this.pending.get(message.requestId);
+    if (!originSessionId) {
+      return;
+    }
+    this.pending.delete(message.requestId);
+    this.sendResponseTo(originSessionId, message.requestId, message.bytes);
+  }
+  forwardRequestToPeers(sourceSessionId, message) {
+    this.pending.set(message.requestId, sourceSessionId);
+    for (const [, client] of this.clients) {
+      if (client.sessionId === sourceSessionId) {
+        continue;
+      }
+      if (!client.transport.isConnected()) {
+        continue;
+      }
+      client.transport.send(message);
+    }
+  }
+  sendResponseTo(sessionId, requestId, bytes) {
+    const client = this.clients.get(sessionId);
+    if (!client || !client.transport.isConnected()) {
+      return;
+    }
+    const response = {
+      type: "blob-chunk-response",
+      messageId: generateResponseId(requestId),
+      requestId,
+      bytes
+    };
+    client.transport.send(response);
+  }
+};
+function generateResponseId(requestId) {
+  return `blob-resp-${requestId}`;
+}
+
 // src/richtext/yjs-doc-relay.ts
 init_cjs_shims();
 var YjsDocRelay = class {
@@ -2988,6 +3218,8 @@ var KoraSyncServer = class {
   metrics;
   awarenessRelay = new AwarenessRelay();
   yjsDocRelay = new YjsDocRelay();
+  blobChunkRelay;
+  persistBlobChunk;
   sessions = /* @__PURE__ */ new Map();
   httpClients = /* @__PURE__ */ new Map();
   httpSessionToClient = /* @__PURE__ */ new Map();
@@ -2997,7 +3229,7 @@ var KoraSyncServer = class {
   constructor(config) {
     this.store = config.store;
     this.auth = config.auth ?? null;
-    this.serializer = config.serializer ?? new import_sync3.JsonMessageSerializer();
+    this.serializer = config.serializer ?? new import_sync5.JsonMessageSerializer();
     this.emitter = config.emitter ?? null;
     this.maxConnections = config.maxConnections ?? DEFAULT_MAX_CONNECTIONS;
     this.batchSize = config.batchSize ?? DEFAULT_BATCH_SIZE2;
@@ -3012,6 +3244,8 @@ var KoraSyncServer = class {
     this.logger = config.logger ?? createDefaultLogger();
     this.metrics = config.metricsCollector ?? new ServerMetricsCollector();
     this.metrics.setSchemaVersion(this.schemaVersion);
+    this.blobChunkRelay = new BlobChunkRelay(config.resolveBlobChunk);
+    this.persistBlobChunk = config.persistBlobChunk ?? null;
     if (!this.emitter) {
       this.emitter = new import_internal2.SimpleEventEmitter();
     }
@@ -3084,10 +3318,10 @@ var KoraSyncServer = class {
    */
   async start(wsServerImpl) {
     if (this.running) {
-      throw new import_core10.SyncError("Server is already running", { port: this.port });
+      throw new import_core12.SyncError("Server is already running", { port: this.port });
     }
     if (!wsServerImpl && this.port === void 0) {
-      throw new import_core10.SyncError(
+      throw new import_core12.SyncError(
         "Port is required for standalone mode. Provide port in config or use handleConnection() for attach mode.",
         {}
       );
@@ -3135,6 +3369,7 @@ var KoraSyncServer = class {
     });
     this.awarenessRelay.clear();
     this.yjsDocRelay.clear();
+    this.blobChunkRelay.clear();
     for (const session of this.sessions.values()) {
       session.close("server shutting down");
     }
@@ -3196,7 +3431,7 @@ var KoraSyncServer = class {
     if (this.maxConnections > 0 && this.sessions.size >= this.maxConnections) {
       transport.send({
         type: "error",
-        messageId: (0, import_core10.generateUUIDv7)(),
+        messageId: (0, import_core12.generateUUIDv7)(),
         code: "MAX_CONNECTIONS",
         message: `Server has reached maximum connections (${this.maxConnections})`,
         retriable: true
@@ -3209,12 +3444,12 @@ var KoraSyncServer = class {
         event: "connection.rejected",
         details: { reason: "max_connections", max: this.maxConnections }
       });
-      throw new import_core10.SyncError("Maximum connections reached", {
+      throw new import_core12.SyncError("Maximum connections reached", {
         current: this.sessions.size,
         max: this.maxConnections
       });
     }
-    const sessionId = (0, import_core10.generateUUIDv7)();
+    const sessionId = (0, import_core12.generateUUIDv7)();
     this.metrics.recordConnection(sessionId);
     const sessionEmitter = new import_internal2.SimpleEventEmitter();
     sessionEmitter.on("sync:connected", (event) => {
@@ -3279,12 +3514,20 @@ var KoraSyncServer = class {
       onYjsDocUpdate: (sourceSessionId, message) => {
         this.handleYjsDocRelay(sourceSessionId, message);
       },
+      onBlobChunkRequest: (sourceSessionId, message) => {
+        this.blobChunkRelay.handleRequest(sourceSessionId, message);
+      },
+      onBlobChunkResponse: (sourceSessionId, message) => {
+        this.blobChunkRelay.handleResponse(sourceSessionId, message);
+      },
+      ...this.persistBlobChunk ? { persistBlobChunk: this.persistBlobChunk } : {},
       onClose: (sid) => {
         this.handleSessionClose(sid);
       }
     });
     this.sessions.set(sessionId, session);
     this.yjsDocRelay.addClient(sessionId, transport);
+    this.blobChunkRelay.addClient(sessionId, transport);
     session.start();
     this.logger.log({
       timestamp: Date.now(),
@@ -3317,6 +3560,61 @@ var KoraSyncServer = class {
       errorCount: snapshot.errorCount
     };
   }
+  /**
+   * Apply a server-originated operation (for example one created by a custom
+   * HTTP route) through the same validated pipeline that incoming client
+   * operations use — Tier 2 constraints, referential integrity, and cascade
+   * side effects — then relay every applied operation to connected clients.
+   *
+   * Because the operation did not come from a client session, it is relayed to
+   * ALL sessions (there is no source session to exclude). Each session still
+   * applies its own per-scope visibility filter in `relayOperations`, so a
+   * client only receives the operation if it falls within that client's scope.
+   *
+   * @param op - A fully-formed, server-originated operation to apply
+   * @returns The apply result, including any server-generated side-effect ops
+   */
+  async applyLocalOperation(op) {
+    const result = await applyServerOperation(this.store, op);
+    if (result.result === "applied" && result.appliedOperations.length > 0) {
+      for (const session of this.sessions.values()) {
+        session.relayOperations(result.appliedOperations);
+      }
+    }
+    return result;
+  }
+  /**
+   * Collect every blob reference still reachable from live records on the server.
+   *
+   * This is the live set for garbage-collecting the server's central blob store:
+   * pass the result to `collectBlobGarbage(blobStore, liveRefs)` from
+   * `@korajs/store` to reclaim bytes no record references any more. Only
+   * collections that declare a `blob` field are scanned.
+   *
+   * @returns Every live blob reference across all collections
+   */
+  async getLiveBlobRefs() {
+    const schema = this.store.getSchema();
+    if (!schema) {
+      return [];
+    }
+    const refs = [];
+    for (const [name, collection] of Object.entries(schema.collections)) {
+      const hasBlobField = Object.values(collection.fields).some((field) => field.kind === "blob");
+      if (!hasBlobField) {
+        continue;
+      }
+      const records = await this.store.materializeCollection(name);
+      for (const record of records) {
+        for (const value of Object.values(record)) {
+          if ((0, import_core12.isBlobRef)(value)) {
+            refs.push(value);
+          }
+        }
+      }
+    }
+    return refs;
+  }
   /**
    * Get the number of currently connected clients.
    */
@@ -3350,6 +3648,7 @@ var KoraSyncServer = class {
     this.metrics.recordDisconnection(sessionId);
     this.awarenessRelay.removeClient(sessionId);
     this.yjsDocRelay.removeClient(sessionId);
+    this.blobChunkRelay.removeClient(sessionId);
     this.sessions.delete(sessionId);
     const clientId = this.httpSessionToClient.get(sessionId);
     if (clientId) {
@@ -3402,14 +3701,6 @@ function normalizeHttpBody(body, contentType) {
   return body;
 }
 
-// src/auth/no-auth.ts
-init_cjs_shims();
-var NoAuthProvider = class {
-  async authenticate(_token) {
-    return { userId: "anonymous" };
-  }
-};
-
 // src/auth/token-auth.ts
 init_cjs_shims();
 var TokenAuthProvider = class {
@@ -3496,6 +3787,162 @@ function createKoraServer(config) {
 
 // src/server/production-server.ts
 init_cjs_shims();
+
+// src/server/route-context.ts
+init_cjs_shims();
+var import_core13 = require("@korajs/core");
+function recordMatchesScope(collection, record, scope) {
+  const collectionScope = scope[collection];
+  if (!collectionScope) {
+    return false;
+  }
+  for (const [field, expected] of Object.entries(collectionScope)) {
+    if (record[field] !== expected) {
+      return false;
+    }
+  }
+  return true;
+}
+function pickFields(record, keys) {
+  const picked = {};
+  for (const key of keys) {
+    if (key in record) {
+      picked[key] = record[key];
+    }
+  }
+  return picked;
+}
+async function buildRouteOperation(store, mutation) {
+  const nodeId = store.getNodeId();
+  const clock = new import_core13.HybridLogicalClock(nodeId);
+  const schemaVersion = store.getSchema()?.version ?? 1;
+  const sequenceNumber = nextServerSequenceNumber(store);
+  if (mutation.type === "insert") {
+    return (0, import_core13.createOperation)(
+      {
+        nodeId,
+        type: "insert",
+        collection: mutation.collection,
+        recordId: mutation.recordId ?? (0, import_core13.generateUUIDv7)(),
+        data: mutation.data ?? {},
+        previousData: null,
+        sequenceNumber,
+        causalDeps: [],
+        schemaVersion
+      },
+      clock
+    );
+  }
+  if (!mutation.recordId) {
+    throw new RouteMutationError(
+      "MISSING_RECORD_ID",
+      `A ${mutation.type} mutation on "${mutation.collection}" requires a recordId.`
+    );
+  }
+  const current = await store.findRecord(mutation.collection, mutation.recordId);
+  if (mutation.type === "update") {
+    const data = mutation.data ?? {};
+    return (0, import_core13.createOperation)(
+      {
+        nodeId,
+        type: "update",
+        collection: mutation.collection,
+        recordId: mutation.recordId,
+        data,
+        previousData: current ? pickFields(current, Object.keys(data)) : {},
+        sequenceNumber,
+        causalDeps: [],
+        schemaVersion
+      },
+      clock
+    );
+  }
+  return (0, import_core13.createOperation)(
+    {
+      nodeId,
+      type: "delete",
+      collection: mutation.collection,
+      recordId: mutation.recordId,
+      data: null,
+      previousData: current ? { ...current } : null,
+      sequenceNumber,
+      causalDeps: [],
+      schemaVersion
+    },
+    clock
+  );
+}
+var RouteMutationError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "RouteMutationError";
+  }
+  code;
+};
+function createRouteContext(server, store) {
+  let mutationTail = Promise.resolve();
+  function serialize(work) {
+    const run = mutationTail.then(work, work);
+    mutationTail = run.then(
+      () => void 0,
+      () => void 0
+    );
+    return run;
+  }
+  return {
+    apply(mutation, options) {
+      return serialize(async () => {
+        let op;
+        try {
+          op = await buildRouteOperation(store, mutation);
+        } catch (error) {
+          if (error instanceof RouteMutationError) {
+            return { ok: false, code: error.code, message: error.message };
+          }
+          throw error;
+        }
+        if (options?.scope && !operationMatchesScopes(op, options.scope)) {
+          return {
+            ok: false,
+            code: "SCOPE_VIOLATION",
+            message: `Mutation on "${mutation.collection}" is outside the provided scope.`
+          };
+        }
+        const result = await server.applyLocalOperation(op);
+        if (result.result !== "applied") {
+          return {
+            ok: false,
+            code: result.rejection?.code ?? "NOT_APPLIED",
+            message: result.rejection?.message ?? `Operation on "${mutation.collection}" was not applied (${result.result}).`
+          };
+        }
+        const record = await store.findRecord(mutation.collection, op.recordId);
+        return { ok: true, operation: op, record };
+      });
+    },
+    async query(collection, options) {
+      const { scope, ...queryOptions } = options ?? {};
+      const records = await store.queryCollection(collection, queryOptions);
+      if (!scope) {
+        return records;
+      }
+      return records.filter((record) => recordMatchesScope(collection, record, scope));
+    },
+    async findById(collection, id, options) {
+      const record = await store.findRecord(collection, id);
+      if (!record) {
+        return null;
+      }
+      if (options?.scope && !recordMatchesScope(collection, record, options.scope)) {
+        return null;
+      }
+      return record;
+    }
+  };
+}
+
+// src/server/production-server.ts
 var MIME_TYPES = {
   ".html": "text/html",
   ".js": "text/javascript",
@@ -3519,6 +3966,7 @@ function createProductionServer(config) {
     enableDashboard: true,
     ...config.syncOptions
   });
+  const routeContext = createRouteContext(syncServer, config.store);
   let httpServer = null;
   function getOperationalToken(kind) {
     const auth = config.operationalAuth;
@@ -3605,6 +4053,10 @@ function createProductionServer(config) {
       const chunks = [];
       req.on("data", (chunk) => chunks.push(chunk));
       req.on("end", () => resolve(Buffer.concat(chunks)));
+      if (!req.readableFlowing) {
+        req.resume();
+      }
+      req.on("error", () => resolve(Buffer.concat(chunks)));
     });
   }
   async function readJsonBody(req) {
@@ -3661,6 +4113,19 @@ function createProductionServer(config) {
       const { WebSocketServer } = await import("ws");
       const distDir = resolve(staticDir);
       httpServer = createServer(async (req, res) => {
+        try {
+          await handleRequest(req, res);
+        } catch (error) {
+          console.error("[kora] Unhandled error in HTTP request handler:", error);
+          if (!res.headersSent) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Internal server error" }));
+          } else if (!res.writableEnded) {
+            res.end();
+          }
+        }
+      });
+      async function handleRequest(req, res) {
         res.setHeader("Cross-Origin-Opener-Policy", "same-origin");
         res.setHeader("Cross-Origin-Embedder-Policy", "require-corp");
         const url = new URL(req.url || "/", `http://${req.headers.host}`);
@@ -3788,7 +4253,8 @@ data: ${JSON.stringify(s)}
             body: await readJsonBody(req),
             headers: req.headers,
             query: getQuery(url),
-            ip: getClientIp(req)
+            ip: getClientIp(req),
+            kora: routeContext
           });
           writeJsonResponse(res, result);
           return;
@@ -3822,7 +4288,7 @@ data: ${JSON.stringify(s)}
         const contentType = MIME_TYPES[ext] || "application/octet-stream";
         res.writeHead(200, { "Content-Type": contentType });
         createReadStream(filePath).pipe(res);
-      });
+      }
       const wss = new WebSocketServer({ noServer: true });
       httpServer.on("upgrade", (req, socket, head) => {
         const url = new URL(req.url || "/", `http://${req.headers.host}`);