mindoodb 0.0.84 → 0.0.86

package/dist/server/http/MindooDBServerCore.js

@@ -0,0 +1,1403 @@
+"use strict";
+/**
+ * Platform-neutral route handlers of the MindooDB server.
+ *
+ * Every endpoint of the HTTP API that does not depend on the host runtime —
+ * discovery, device discovery, system administration, tenant auth, the sync
+ * protocol and the RFC 3161 proxy — is implemented here against
+ * {@link ServerRequest}/{@link ServerResponse}. Hosts own the transport: the
+ * Node server mounts these handlers on Express with its middleware stack, a
+ * serverless host calls them from its `fetch` handler.
+ *
+ * This module must stay free of Node built-ins; a test bundles it for a
+ * neutral platform to keep it that way.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MindooDBServerCore = exports.SYNC_STORE_KINDS = exports.SYNC_ROUTES = exports.SYNC_EVENT_HEARTBEAT_MS = void 0;
+exports.parseBodySizeLimitToBytes = parseBodySizeLimitToBytes;
+exports.errorResponse = errorResponse;
+exports.formatSyncHelloEvent = formatSyncHelloEvent;
+exports.formatSyncChangeEvent = formatSyncChangeEvent;
+exports.formatSyncHeartbeat = formatSyncHeartbeat;
+const errors_1 = require("../../core/errors");
+const binaryEntryFraming_1 = require("../../core/appendonlystores/network/binaryEntryFraming");
+const entryWireCodec_1 = require("../../core/appendonlystores/network/entryWireCodec");
+const types_1 = require("../../core/appendonlystores/types");
+const types_2 = require("../../core/appendonlystores/network/types");
+const urlSafety_1 = require("../../core/utils/urlSafety");
+const base64_1 = require("../../core/utils/base64");
+const CapabilityMatcher_1 = require("../CapabilityMatcher");
+const DeviceDiscoveryService_1 = require("../DeviceDiscoveryService");
+const serverConfig_1 = require("../serverConfig");
+const types_3 = require("../peer/types");
+const validation_1 = require("../validation");
+const timestampProxy_1 = require("../timestampProxy");
+const types_4 = require("./types");
+/** Parse a human-readable size string ("5mb", "1024", "100kb") into bytes. */
+function parseBodySizeLimitToBytes(limit) {
+    const normalized = limit.trim().toLowerCase();
+    if (!normalized) {
+        return null;
+    }
+    if (/^\d+$/.test(normalized)) {
+        return Number(normalized);
+    }
+    const match = normalized.match(/^(\d+(?:\.\d+)?)\s*(b|kb|mb|gb)$/);
+    if (!match) {
+        return null;
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    const multiplier = unit === "b"
+        ? 1
+        : unit === "kb"
+            ? 1024
+            : unit === "mb"
+                ? 1024 * 1024
+                : 1024 * 1024 * 1024;
+    return Math.round(value * multiplier);
+}
+/** HTTP status of each {@link NetworkError} type. */
+function getStatusForErrorType(type) {
+    switch (type) {
+        case "INVALID_TOKEN":
+            return 401;
+        case "USER_REVOKED":
+            return 403;
+        case "USER_NOT_FOUND":
+            return 404;
+        case "INVALID_SIGNATURE":
+            return 403;
+        case "CHALLENGE_EXPIRED":
+            return 401;
+        case "ACCESS_DENIED":
+            return 403;
+        default:
+            return 500;
+    }
+}
+/** Map domain errors to HTTP responses; unknown errors become 500. */
+function errorResponse(error) {
+    if (error instanceof validation_1.ValidationError) {
+        return (0, types_4.jsonResponse)(400, { error: error.message });
+    }
+    if (error instanceof Error && error.name === "NetworkError") {
+        const networkError = error;
+        const status = getStatusForErrorType(networkError.type);
+        // The status alone loses the distinction the client needs: several
+        // NetworkErrorTypes map onto the same code (USER_REVOKED and
+        // ACCESS_DENIED both become 403), and a client that has to guess falls
+        // back to matching on the message text. Carry the type so it does not
+        // have to.
+        return (0, types_4.jsonResponse)(status, { error: networkError.message, type: networkError.type });
+    }
+    if ((0, errors_1.isMissingDependencyError)(error)) {
+        // Not a server fault: the requested chain is incomplete in this store.
+        // Pass the details on so the caller can tell what is missing.
+        return (0, types_4.jsonResponse)(409, { error: error.message, type: "MISSING_DEPENDENCY" });
+    }
+    console.error("[MindooDBServer] Request error:", error);
+    return (0, types_4.jsonResponse)(500, { error: "Internal server error" });
+}
+function extractToken(req) {
+    const auth = req.headers.authorization;
+    if (!auth || !auth.startsWith("Bearer ")) {
+        throw new types_2.NetworkError("INVALID_TOKEN", "Missing or invalid Authorization header");
+    }
+    return auth.substring(7);
+}
+function validateDbId(dbId) {
+    return (0, validation_1.validateIdentifier)(dbId, "dbId");
+}
+/** `event: hello` frame that opens every sync event stream. */
+function formatSyncHelloEvent() {
+    return `event: hello\ndata: ${JSON.stringify({ protocolVersion: "sync-v5" })}\n\n`;
+}
+/**
+ * `event: change` frame for a subscriber of `tenantId`/`storeKind`, or null
+ * when the event belongs to someone else. Events carry only metadata.
+ */
+function formatSyncChangeEvent(subscription, event) {
+    if (event.tenantId !== subscription.tenantId || event.storeKind !== subscription.storeKind) {
+        return null;
+    }
+    return `event: change\ndata: ${JSON.stringify({
+        dbId: event.dbId,
+        storeKind: event.storeKind,
+        epoch: event.epoch,
+        maxReceiptOrder: event.maxReceiptOrder,
+    })}\n\n`;
+}
+/** Comment frame that keeps proxies from closing an idle stream. */
+function formatSyncHeartbeat(now) {
+    return `: heartbeat ${now}\n\n`;
+}
+/** Interval of {@link formatSyncHeartbeat} frames. */
+exports.SYNC_EVENT_HEARTBEAT_MS = 30000;
+/** Sync endpoints mounted under `/:tenantId/sync/{docs,attachments}/`. */
+exports.SYNC_ROUTES = [
+    { method: "POST", name: "findNewEntries" },
+    { method: "POST", name: "findNewEntriesForDoc" },
+    { method: "POST", name: "findEntries" },
+    { method: "POST", name: "scanEntriesSince" },
+    { method: "POST", name: "getStoreHead" },
+    { method: "POST", name: "getIdBloomSummary" },
+    { method: "POST", name: "getCompactionStatus" },
+    { method: "GET", name: "capabilities" },
+    // SSE live change feed (sync-v5, phase 5): one long-lived GET per
+    // subscriber; putEntries publishes into the event bus.
+    { method: "GET", name: "events" },
+    { method: "POST", name: "getEntries" },
+    // Binary wire format v2 (sync-v5, phase 3): octet-stream framing for the
+    // two payload-heavy endpoints. putEntriesBinary takes a raw body.
+    { method: "POST", name: "getEntriesBinary" },
+    { method: "POST", name: "putEntriesBinary", rawBodyType: binaryEntryFraming_1.BINARY_ENTRIES_CONTENT_TYPE },
+    { method: "POST", name: "getEntryMetadata" },
+    { method: "POST", name: "putEntries" },
+    { method: "POST", name: "hasEntries" },
+    { method: "GET", name: "getAllIds" },
+    { method: "POST", name: "resolveDependencies" },
+    { method: "POST", name: "planDocumentMaterialization" },
+    { method: "POST", name: "planDocumentMaterializationBatch" },
+    { method: "POST", name: "planAttachmentReadByWalkingMetadata" },
+];
+exports.SYNC_STORE_KINDS = [types_1.StoreKind.docs, types_1.StoreKind.attachments];
+class MindooDBServerCore {
+    constructor(options) {
+        this.options = options;
+        this.jsonBodyLimitBytes = parseBodySizeLimitToBytes(options.jsonBodyLimit);
+    }
+    get tenantManager() {
+        return this.options.tenantManager;
+    }
+    runInBackground(task) {
+        if (this.options.runInBackground) {
+            this.options.runInBackground(task);
+        }
+        else {
+            void task;
+        }
+    }
+    getJsonBodyLimit() {
+        return { limit: this.options.jsonBodyLimit, bytes: this.jsonBodyLimitBytes };
+    }
+    // ==================== Discovery ====================
+    health() {
+        return (0, types_4.jsonResponse)(200, { status: "ok", timestamp: Date.now() });
+    }
+    serverInfo() {
+        const info = this.tenantManager.getServerPublicInfo();
+        if (!info) {
+            return (0, types_4.jsonResponse)(503, { error: "Server identity not initialized" });
+        }
+        return (0, types_4.jsonResponse)(200, {
+            ...info,
+            // Its own mesh role, so `add-to-network` can propagate it into the
+            // other side's trusted-servers entry instead of asking the operator to
+            // repeat it on every node.
+            clusterRole: this.options.getServerConfig().cluster?.role ?? "peer",
+            maxJsonRequestBodyLimit: this.options.jsonBodyLimit,
+            maxJsonRequestBodyBytes: this.jsonBodyLimitBytes ?? undefined,
+            // Lets a client decide between calling a browser-reachable TSA directly
+            // and routing through this server, per tenant and without a probe.
+            timestamping: {
+                enabled: this.options.tsaProviders.length > 0,
+                providers: (0, timestampProxy_1.toPublicTsaProviders)(this.options.tsaProviders),
+            },
+        });
+    }
+    /**
+     * Mirrors of one tenant, for client failover.
+     *
+     * Scoped to the tenant in the query on purpose: a client asking about
+     * tenant A must not learn which other tenants this server replicates, or
+     * to whom. Unauthenticated like the other discovery endpoints — a client
+     * needs it precisely when it cannot reach a server to authenticate with.
+     */
+    clusterMirrors(req) {
+        const tenantId = typeof req.query.tenantId === "string" ? req.query.tenantId.toLowerCase() : "";
+        if (!tenantId) {
+            return (0, types_4.jsonResponse)(400, { error: "tenantId query parameter is required" });
+        }
+        try {
+            (0, validation_1.validateTenantId)(tenantId);
+        }
+        catch {
+            return (0, types_4.jsonResponse)(400, { error: "Invalid tenantId format" });
+        }
+        if (!this.tenantManager.tenantExists(tenantId)) {
+            return (0, types_4.jsonResponse)(404, { error: "Tenant not found on server" });
+        }
+        return (0, types_4.jsonResponse)(200, {
+            tenantId,
+            mirrors: this.options.cluster?.mirrorsForTenant(tenantId) ?? [],
+        });
+    }
+    async publicInfosFingerprints(req) {
+        const tenantId = (req.params.tenantId ?? "").toLowerCase();
+        try {
+            (0, validation_1.validateTenantId)(tenantId);
+            const fingerprints = await this.tenantManager.listTenantPublicInfosFingerprints(tenantId);
+            if (fingerprints.length === 0) {
+                return (0, types_4.jsonResponse)(404, { error: "Tenant not found on server" });
+            }
+            const response = {
+                tenantId,
+                fingerprints,
+            };
+            return (0, types_4.jsonResponse)(200, response);
+        }
+        catch (error) {
+            if (error instanceof validation_1.ValidationError) {
+                return (0, types_4.jsonResponse)(400, { error: error.message });
+            }
+            if (error instanceof Error && error.message.includes("not found")) {
+                return (0, types_4.jsonResponse)(404, { error: "Tenant not found on server" });
+            }
+            console.error("[MindooDBServer] Error reading tenant publicInfos fingerprints:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to read tenant publicInfos fingerprints" });
+        }
+    }
+    // ==================== Device Discovery (server-wide) ====================
+    async deviceChallenge(req) {
+        try {
+            const { signingPublicKey } = req.body ?? {};
+            if (typeof signingPublicKey !== "string" || !signingPublicKey.trim()) {
+                return (0, types_4.jsonResponse)(400, { error: "signingPublicKey is required" });
+            }
+            (0, validation_1.validateStringLength)(signingPublicKey, validation_1.MAX_PEM_KEY_LENGTH, "signingPublicKey");
+            const challenge = this.options.deviceDiscovery.createChallenge(signingPublicKey);
+            return (0, types_4.jsonResponse)(200, { challenge });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async deviceDiscover(req) {
+        try {
+            const { challenge, signature } = req.body ?? {};
+            if (typeof challenge !== "string" || !challenge.trim()) {
+                return (0, types_4.jsonResponse)(400, { error: "challenge is required" });
+            }
+            if (typeof signature !== "string" || !signature.trim()) {
+                return (0, types_4.jsonResponse)(400, { error: "signature is required" });
+            }
+            (0, validation_1.validateStringLength)(challenge, validation_1.MAX_CHALLENGE_LENGTH, "challenge");
+            (0, validation_1.validateStringLength)(signature, validation_1.MAX_SIGNATURE_LENGTH, "signature");
+            const result = await this.options.deviceDiscovery.discover(challenge, (0, base64_1.base64ToBytes)(signature));
+            return (0, types_4.jsonResponse)(200, result);
+        }
+        catch (error) {
+            if (error instanceof DeviceDiscoveryService_1.DeviceDiscoveryAuthError) {
+                return (0, types_4.jsonResponse)(401, { error: error.message });
+            }
+            return errorResponse(error);
+        }
+    }
+    // ==================== System Admin Auth ====================
+    /**
+     * JWT check for /system/* routes (excluding /system/auth/*). Validates the
+     * bearer token, then checks capabilities for (method, fullPath, username,
+     * publicsignkey). Returns the rejection, or null and sets `req.systemAdmin`.
+     *
+     * `DELETE /system/tenants/:tenantId` is also allowed when the JWT signing
+     * key is that tenant's registered `adminSigningPublicKey` (own-tenant
+     * delete). Sub-resources and other tenants stay capability-gated.
+     */
+    async systemAdminGuard(req, fullPath) {
+        const auth = req.headers.authorization;
+        if (!auth || !auth.startsWith("Bearer ")) {
+            return (0, types_4.jsonResponse)(401, { error: "Missing or invalid Authorization header" });
+        }
+        const token = auth.substring(7);
+        const payload = await this.options.systemAdminAuth.validateToken(token);
+        if (!payload) {
+            return (0, types_4.jsonResponse)(401, { error: "Invalid or expired token" });
+        }
+        const method = req.method.toUpperCase();
+        const capabilityAuthorized = this.options.capabilityMatcher.isAuthorized(method, fullPath, payload.sub, payload.publicsignkey);
+        const ownerDeleteAuthorized = !capabilityAuthorized &&
+            this.isOwnTenantDeleteAuthorized(method, fullPath, payload.publicsignkey);
+        if (!capabilityAuthorized && !ownerDeleteAuthorized) {
+            return (0, types_4.jsonResponse)(403, { error: "Forbidden: insufficient capabilities" });
+        }
+        req.systemAdmin = {
+            username: payload.sub,
+            publicsignkey: payload.publicsignkey,
+        };
+        return null;
+    }
+    /**
+     * Owner bypass for deleting the caller's own tenant. Matches only
+     * `DELETE /system/tenants/:tenantId` (no sub-resource) and requires the
+     * JWT public key to equal that tenant's stored admin signing key.
+     */
+    isOwnTenantDeleteAuthorized(method, fullPath, publicsignkey) {
+        if (method !== "DELETE") {
+            return false;
+        }
+        const tenantId = (0, CapabilityMatcher_1.parseSystemTenantItemPath)(fullPath);
+        if (!tenantId) {
+            return false;
+        }
+        try {
+            (0, validation_1.validateTenantIdFormat)(tenantId);
+        }
+        catch {
+            return false;
+        }
+        return this.tenantManager.isTenantAdminSigningKeyFor(tenantId, publicsignkey);
+    }
+    async systemChallenge(req) {
+        try {
+            const { username, publicsignkey } = req.body;
+            if (!username || typeof username !== "string") {
+                return (0, types_4.jsonResponse)(400, { error: "username is required" });
+            }
+            if (!publicsignkey || typeof publicsignkey !== "string") {
+                return (0, types_4.jsonResponse)(400, { error: "publicsignkey is required" });
+            }
+            (0, validation_1.validateUsername)(username);
+            (0, validation_1.validateStringLength)(publicsignkey, validation_1.MAX_PEM_KEY_LENGTH, "publicsignkey");
+            const challenge = await this.options.systemAdminAuth.generateChallenge(username, publicsignkey);
+            return (0, types_4.jsonResponse)(200, { challenge });
+        }
+        catch (error) {
+            if (error instanceof Error && error.message === "Unknown system admin principal") {
+                return (0, types_4.jsonResponse)(404, { error: "System admin principal not found" });
+            }
+            if (error instanceof validation_1.ValidationError) {
+                return (0, types_4.jsonResponse)(400, { error: error.message });
+            }
+            console.error("[MindooDBServer] System challenge error:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Internal server error" });
+        }
+    }
+    async systemAuthenticate(req) {
+        try {
+            const { challenge, signature } = req.body;
+            if (!challenge || !signature) {
+                return (0, types_4.jsonResponse)(400, { error: "challenge and signature are required" });
+            }
+            (0, validation_1.validateStringLength)(challenge, validation_1.MAX_CHALLENGE_LENGTH, "challenge");
+            (0, validation_1.validateStringLength)(signature, validation_1.MAX_SIGNATURE_LENGTH, "signature");
+            const result = await this.options.systemAdminAuth.authenticate(challenge, (0, base64_1.base64ToBytes)(signature));
+            // Return 401 on a failed authentication instead of 200 (audit, Low).
+            return (0, types_4.jsonResponse)(result.success ? 200 : 401, result);
+        }
+        catch (error) {
+            if (error instanceof validation_1.ValidationError) {
+                return (0, types_4.jsonResponse)(400, { error: error.message });
+            }
+            console.error("[MindooDBServer] System authenticate error:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Internal server error" });
+        }
+    }
+    // ==================== System: Tenants ====================
+    listTenants() {
+        try {
+            const tenants = this.tenantManager.listTenants();
+            const response = { tenants };
+            return (0, types_4.jsonResponse)(200, response);
+        }
+        catch (error) {
+            console.error("[MindooDBServer] Error listing tenants:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to list tenants" });
+        }
+    }
+    /**
+     * Tenant registration is idempotent: re-POSTing with the same tenantId
+     * and matching $publicinfos key returns 200 instead of 409.
+     */
+    async registerTenant(req) {
+        try {
+            const tenantId = (req.params.tenantId ?? "").toLowerCase();
+            try {
+                (0, validation_1.validateTenantId)(tenantId);
+            }
+            catch (validationError) {
+                return (0, types_4.jsonResponse)(400, {
+                    error: validationError instanceof validation_1.ValidationError
+                        ? validationError.message
+                        : "Invalid tenantId format",
+                });
+            }
+            const request = {
+                ...req.body,
+                tenantId,
+            };
+            if (!request.adminSigningPublicKey) {
+                return (0, types_4.jsonResponse)(400, { error: "adminSigningPublicKey is required" });
+            }
+            if (!request.adminEncryptionPublicKey) {
+                return (0, types_4.jsonResponse)(400, { error: "adminEncryptionPublicKey is required" });
+            }
+            if (request.adminUsername !== undefined) {
+                (0, validation_1.validateUsername)(request.adminUsername);
+            }
+            (0, validation_1.validateStringLength)(request.adminSigningPublicKey, validation_1.MAX_PEM_KEY_LENGTH, "adminSigningPublicKey");
+            (0, validation_1.validateStringLength)(request.adminEncryptionPublicKey, validation_1.MAX_PEM_KEY_LENGTH, "adminEncryptionPublicKey");
+            if (!request.encryptedPublicInfosKey && !request.publicInfosKey) {
+                return (0, types_4.jsonResponse)(400, { error: "encryptedPublicInfosKey or publicInfosKey is required" });
+            }
+            if (request.publicInfosKey !== undefined) {
+                (0, validation_1.validateStringLength)(request.publicInfosKey, validation_1.MAX_PEM_KEY_LENGTH, "publicInfosKey");
+            }
+            if (request.encryptedPublicInfosKey !== undefined) {
+                (0, validation_1.validateStringLength)(request.encryptedPublicInfosKey, validation_1.MAX_PEM_KEY_LENGTH, "encryptedPublicInfosKey");
+            }
+            const result = await this.tenantManager.registerTenant(request);
+            const response = {
+                success: true,
+                tenantId: result.context.tenantId,
+                created: result.created,
+                message: result.created
+                    ? `Tenant ${result.context.tenantId} registered successfully`
+                    : `Tenant ${result.context.tenantId} already exists with matching $publicinfos key`,
+            };
+            return (0, types_4.jsonResponse)(result.created ? 201 : 200, response);
+        }
+        catch (error) {
+            if (error instanceof validation_1.ValidationError) {
+                return (0, types_4.jsonResponse)(400, { error: error.message });
+            }
+            if (error instanceof Error && error.message.includes("different $publicinfos key")) {
+                return (0, types_4.jsonResponse)(409, { error: error.message });
+            }
+            console.error("[MindooDBServer] Error registering tenant:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to register tenant" });
+        }
+    }
+    updateTenant(req) {
+        try {
+            const tenantId = (req.params.tenantId ?? "").toLowerCase();
+            try {
+                (0, validation_1.validateTenantId)(tenantId);
+            }
+            catch {
+                return (0, types_4.jsonResponse)(400, { error: "Invalid tenantId format" });
+            }
+            if (!this.tenantManager.tenantExists(tenantId)) {
+                return (0, types_4.jsonResponse)(404, { error: "Tenant not found" });
+            }
+            this.tenantManager.updateTenantConfig(tenantId, req.body);
+            return (0, types_4.jsonResponse)(200, { success: true, message: `Tenant ${tenantId} updated` });
+        }
+        catch (error) {
+            if (error instanceof validation_1.ValidationError) {
+                return (0, types_4.jsonResponse)(400, { error: error.message });
+            }
+            console.error("[MindooDBServer] Error updating tenant:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to update tenant" });
+        }
+    }
+    async deleteTenant(req) {
+        try {
+            const tenantId = (req.params.tenantId ?? "").toLowerCase();
+            try {
+                (0, validation_1.validateTenantId)(tenantId);
+            }
+            catch {
+                return (0, types_4.jsonResponse)(400, { error: "Invalid tenantId format" });
+            }
+            if (!this.tenantManager.tenantExists(tenantId)) {
+                return (0, types_4.jsonResponse)(404, { error: "Tenant not found" });
+            }
+            await this.tenantManager.removeTenant(tenantId);
+            return (0, types_4.jsonResponse)(200, { success: true, message: `Tenant ${tenantId} removed` });
+        }
+        catch (error) {
+            console.error("[MindooDBServer] Error removing tenant:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to remove tenant" });
+        }
+    }
+    // ==================== System: Trusted Servers ====================
+    listTrustedServers() {
+        try {
+            return (0, types_4.jsonResponse)(200, { servers: this.tenantManager.listTrustedServers() });
+        }
+        catch (error) {
+            console.error("[MindooDBServer] Error listing trusted servers:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to list trusted servers" });
+        }
+    }
+    addTrustedServer(req) {
+        try {
+            const { name, signingPublicKey, encryptionPublicKey, url, direction, role, attachments } = req.body;
+            if (!name || !signingPublicKey || !encryptionPublicKey) {
+                return (0, types_4.jsonResponse)(400, { error: "name, signingPublicKey, and encryptionPublicKey are required" });
+            }
+            (0, validation_1.validateStringLength)(name, 256, "name");
+            (0, validation_1.validateStringLength)(signingPublicKey, validation_1.MAX_PEM_KEY_LENGTH, "signingPublicKey");
+            (0, validation_1.validateStringLength)(encryptionPublicKey, validation_1.MAX_PEM_KEY_LENGTH, "encryptionPublicKey");
+            const server = { name, signingPublicKey, encryptionPublicKey };
+            // Replication settings are optional: an entry without a url is a trust
+            // relationship only (inbound peers may authenticate, we never dial).
+            if (url !== undefined) {
+                (0, validation_1.validateStringLength)(url, 2048, "url");
+                const allowInsecure = this.options.allowInsecureSyncUrls;
+                try {
+                    (0, urlSafety_1.assertSafeSyncUrl)(url, {
+                        requireHttps: !allowInsecure,
+                        allowPrivate: allowInsecure,
+                    });
+                }
+                catch (e) {
+                    if (e instanceof urlSafety_1.UnsafeUrlError) {
+                        return (0, types_4.jsonResponse)(400, { error: e.message });
+                    }
+                    throw e;
+                }
+                server.url = url;
+            }
+            for (const [field, value, guard] of [
+                ["direction", direction, types_3.isPeerSyncDirection],
+                ["role", role, types_3.isPeerRole],
+                ["attachments", attachments, types_3.isPeerAttachmentMode],
+            ]) {
+                if (value === undefined)
+                    continue;
+                if (!guard(value)) {
+                    return (0, types_4.jsonResponse)(400, { error: `Invalid ${field}: ${String(value)}` });
+                }
+                Object.assign(server, { [field]: value });
+            }
+            this.tenantManager.addTrustedServer(server);
+            this.options.cluster?.syncReplicators();
+            return (0, types_4.jsonResponse)(201, { success: true, message: `Trusted server "${name}" added` });
+        }
+        catch (error) {
+            if (error instanceof validation_1.ValidationError) {
+                return (0, types_4.jsonResponse)(400, { error: error.message });
+            }
+            if (error instanceof Error && error.message.includes("already exists")) {
+                return (0, types_4.jsonResponse)(409, { error: error.message });
+            }
+            console.error("[MindooDBServer] Error adding trusted server:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to add trusted server" });
+        }
+    }
+    removeTrustedServer(req) {
+        try {
+            const serverName = req.params.serverName;
+            (0, validation_1.validateStringLength)(serverName, 256, "serverName");
+            const removed = this.tenantManager.removeTrustedServer(serverName);
+            if (!removed) {
+                return (0, types_4.jsonResponse)(404, { error: "Trusted server not found" });
+            }
+            // Revoking trust must also stop replicating with that server.
+            this.options.cluster?.syncReplicators();
+            return (0, types_4.jsonResponse)(200, { success: true, message: `Trusted server "${serverName}" removed` });
+        }
+        catch (error) {
+            if (error instanceof validation_1.ValidationError) {
+                return (0, types_4.jsonResponse)(400, { error: error.message });
+            }
+            console.error("[MindooDBServer] Error removing trusted server:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to remove trusted server" });
+        }
+    }
+    // ==================== System: Runtime Config ====================
+    listConfigBackups() {
+        try {
+            return (0, types_4.jsonResponse)(200, { backups: this.options.configRepository.listBackups() });
+        }
+        catch (error) {
+            console.error("[MindooDBServer] Error listing config backups:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to list config backups" });
+        }
+    }
+    /**
+     * `req.params.backupFile` as the host's router decoded it; it is decoded
+     * once more here, as the Express server always did.
+     */
+    getConfigBackup(req) {
+        try {
+            const backupFile = decodeURIComponent(req.params.backupFile ?? "");
+            if (!(0, serverConfig_1.isConfigBackupFilename)(backupFile)) {
+                return (0, types_4.jsonResponse)(400, { error: "Invalid config backup filename" });
+            }
+            const config = this.options.configRepository.loadBackup(backupFile);
+            return (0, types_4.jsonResponse)(200, { file: backupFile, config });
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith("Config backup not found:")) {
+                return (0, types_4.jsonResponse)(404, { error: "Config backup not found" });
+            }
+            if (error instanceof Error && error.message.startsWith("Invalid config backup filename:")) {
+                return (0, types_4.jsonResponse)(400, { error: "Invalid config backup filename" });
+            }
+            console.error("[MindooDBServer] Error reading config backup:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to read config backup" });
+        }
+    }
+    getConfig() {
+        return (0, types_4.jsonResponse)(200, this.options.getServerConfig());
+    }
+    async updateConfig(req) {
+        try {
+            let newConfig;
+            try {
+                newConfig = (0, serverConfig_1.validateServerConfig)(req.body, "request body");
+            }
+            catch (err) {
+                return (0, types_4.jsonResponse)(400, {
+                    error: err instanceof Error ? err.message : "Invalid config format",
+                });
+            }
+            // Self-lockout protection: simulate the proposed config against the calling
+            // admin's identity — reject if they would lose their own config access.
+            const callingAdmin = req.systemAdmin;
+            const proposedMatcher = new CapabilityMatcher_1.CapabilityMatcher(newConfig);
+            if (!proposedMatcher.isAuthorized("PUT", "/system/config", callingAdmin.username, callingAdmin.publicsignkey)) {
+                return (0, types_4.jsonResponse)(400, {
+                    error: "This change would remove your own access to PUT /system/config",
+                });
+            }
+            // Back up the current config, then persist the new one.
+            const backupFile = this.options.configRepository.replace(newConfig);
+            // Hot-swap in-memory state
+            this.options.reloadConfig(newConfig);
+            console.log(`[MindooDBServer] Config updated by ${callingAdmin.username}` +
+                (backupFile ? ` (backup: ${backupFile})` : ""));
+            return (0, types_4.jsonResponse)(200, {
+                success: true,
+                ...(backupFile ? { backupFile } : {}),
+            });
+        }
+        catch (error) {
+            console.error("[MindooDBServer] Error updating config:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to update config" });
+        }
+    }
+    // ==================== Tenant Guards ====================
+    /** Validate the `:tenantId` parameter and reject unknown tenants; sets `req.tenantId`. */
+    tenantGuard(req) {
+        const rawTenantId = req.params.tenantId?.toLowerCase();
+        if (!rawTenantId) {
+            return (0, types_4.jsonResponse)(400, { error: "Tenant ID required" });
+        }
+        try {
+            (0, validation_1.validateTenantIdFormat)(rawTenantId);
+        }
+        catch {
+            return (0, types_4.jsonResponse)(400, { error: "Invalid tenant ID format" });
+        }
+        if (!this.tenantManager.tenantExists(rawTenantId)) {
+            return (0, types_4.jsonResponse)(404, { error: this.formatTenantNotFoundOnServerError(rawTenantId) });
+        }
+        req.tenantId = rawTenantId;
+        return null;
+    }
+    formatTenantNotFoundOnServerError(tenantId) {
+        const serverName = this.tenantManager.getServerPublicInfo()?.name ?? "unknown";
+        return `Tenant ${tenantId} not found on server ${serverName}`;
+    }
+    /**
+     * Resolve the caller of a sync request so the sync limiter can bucket per
+     * identity instead of per address.
+     *
+     * Unlike {@link timestampAuthGuard} this never rejects: the route handlers
+     * do their own token validation and own the 401, and this pass only needs
+     * to know whose budget to spend. An unverifiable token simply falls back to
+     * address-only bucketing — a forged one must not be able to conjure a fresh
+     * budget, which is why the token is verified rather than decoded.
+     */
+    async resolveSyncPrincipal(req) {
+        try {
+            const token = extractToken(req);
+            const authService = await this.tenantManager.getAuthService(req.tenantId);
+            // Signature and expiry are enough to name the caller; the handler runs
+            // the full check (revocation, wipe) right after, so the directory is
+            // evaluated once per request rather than twice.
+            const payload = await authService.readIssuedToken(token);
+            if (payload && payload.tenantId === req.tenantId) {
+                req.syncPrincipal = payload.deviceSigningKey ?? payload.sub;
+            }
+        }
+        catch {
+            // No usable token; fall through to address-only bucketing.
+        }
+    }
+    /**
+     * Authenticate a timestamp request with the tenant's existing bearer token
+     * and record the principal for rate-limit bucketing.
+     *
+     * The proxy makes outbound requests on the caller's behalf, so it must never
+     * be open: unauthenticated it would be a free relay to third-party services.
+     */
+    async timestampAuthGuard(req) {
+        try {
+            const token = extractToken(req);
+            const authService = await this.tenantManager.getAuthService(req.tenantId);
+            const payload = await authService.validateToken(token);
+            if (!payload || payload.tenantId !== req.tenantId) {
+                return (0, types_4.jsonResponse)(401, { error: "Invalid or expired token" });
+            }
+            req.timestampPrincipal = payload.deviceSigningKey ?? payload.sub;
+            return null;
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    /**
+     * Forward a DER TimeStampReq to a configured TSA and return the DER
+     * TimeStampResp verbatim.
+     *
+     * The server neither parses nor validates the ASN.1: the client checks that
+     * the returned token's `messageImprint` matches the digest it sent and that
+     * the token chains to a trusted root. That is what reduces a hostile proxy —
+     * ours or anyone's — from a forgery risk to a denial-of-service risk.
+     */
+    async timestampRequest(req) {
+        const providers = this.options.tsaProviders;
+        if (providers.length === 0) {
+            return (0, types_4.jsonResponse)(503, { error: "Timestamping is not enabled on this server" });
+        }
+        const body = req.rawBody;
+        if (!body) {
+            return (0, types_4.jsonResponse)(415, {
+                error: `Timestamp requests must be sent as ${timestampProxy_1.TIMESTAMP_QUERY_CONTENT_TYPE}`,
+            });
+        }
+        // The provider is named by id and resolved against the env allowlist; a
+        // client-supplied URL would make this an SSRF gadget.
+        const requestedProvider = req.query.provider;
+        let preferredProviderId;
+        if (typeof requestedProvider === "string" && requestedProvider.length > 0) {
+            preferredProviderId = requestedProvider.toLowerCase();
+        }
+        else if (requestedProvider !== undefined) {
+            return (0, types_4.jsonResponse)(400, { error: "provider must be a single string value" });
+        }
+        try {
+            const result = await (0, timestampProxy_1.requestTimestampToken)({
+                providers,
+                request: body,
+                preferredProviderId,
+            });
+            return {
+                status: 200,
+                bytes: result.response,
+                headers: {
+                    "content-type": timestampProxy_1.TIMESTAMP_REPLY_CONTENT_TYPE,
+                    "x-mindoodb-tsa-provider": result.providerId,
+                },
+            };
+        }
+        catch (error) {
+            if (error instanceof timestampProxy_1.TimestampProxyError) {
+                if (error.attempts.length > 0) {
+                    console.warn(`[MindooDBServer] Timestamp request failed for tenant ${req.tenantId}: ${error.attempts
+                        .map((attempt) => `${attempt.providerId}=${attempt.error ?? "ok"}`)
+                        .join("; ")}`);
+                }
+                return (0, types_4.jsonResponse)(error.status, { error: error.message });
+            }
+            console.error("[MindooDBServer] Unexpected timestamp proxy error:", error);
+            return (0, types_4.jsonResponse)(500, { error: "Failed to obtain a timestamp" });
+        }
+    }
+    // ==================== Tenant Auth ====================
+    // Two-step challenge-response flow:
+    //  1. POST /auth/challenge  → client sends username, server returns a random nonce
+    //  2. POST /auth/authenticate → client signs the nonce with its Ed25519 private key,
+    //     server verifies the signature and returns a JWT for subsequent sync calls
+    async challenge(req) {
+        try {
+            const { username, signingPublicKey } = req.body;
+            // The username is optional: a client may identify itself by its device
+            // signing public key instead, so the server never needs the cleartext
+            // name. Validate whichever was supplied.
+            if (username !== undefined && username !== null) {
+                (0, validation_1.validateUsername)(username);
+            }
+            if (signingPublicKey !== undefined && signingPublicKey !== null) {
+                (0, validation_1.validateStringLength)(signingPublicKey, validation_1.MAX_SIGNATURE_LENGTH, "signingPublicKey");
+            }
+            const authService = await this.tenantManager.getAuthService(req.tenantId);
+            const challenge = await authService.generateChallenge(typeof username === "string" ? username : undefined, typeof signingPublicKey === "string" ? { signingPublicKey } : undefined);
+            return (0, types_4.jsonResponse)(200, { challenge });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async authenticate(req) {
+        try {
+            const { challenge, signature } = req.body;
+            if (!challenge || !signature) {
+                return (0, types_4.jsonResponse)(400, { error: "challenge and signature are required" });
+            }
+            (0, validation_1.validateStringLength)(challenge, validation_1.MAX_CHALLENGE_LENGTH, "challenge");
+            (0, validation_1.validateStringLength)(signature, validation_1.MAX_SIGNATURE_LENGTH, "signature");
+            const authService = await this.tenantManager.getAuthService(req.tenantId);
+            const result = await authService.authenticate(challenge, (0, base64_1.base64ToBytes)(signature));
+            // Return 401 on a failed authentication instead of 200 (audit, Low): a
+            // failed credential check must not look like a success at the HTTP layer.
+            return (0, types_4.jsonResponse)(result.success ? 200 : 401, result);
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    // ==================== Sync ====================
+    /** Dispatch one of {@link SYNC_ROUTES} for a store kind. */
+    sync(name, req, storeKind) {
+        switch (name) {
+            case "findNewEntries": return this.findNewEntries(req, storeKind);
+            case "findNewEntriesForDoc": return this.findNewEntriesForDoc(req, storeKind);
+            case "findEntries": return this.findEntries(req, storeKind);
+            case "scanEntriesSince": return this.scanEntriesSince(req, storeKind);
+            case "getStoreHead": return this.getStoreHead(req, storeKind);
+            case "getIdBloomSummary": return this.getIdBloomSummary(req, storeKind);
+            case "getCompactionStatus": return this.getCompactionStatus(req, storeKind);
+            case "capabilities": return this.getCapabilities(req, storeKind);
+            case "events": return this.syncEvents(req, storeKind);
+            case "getEntries": return this.getEntries(req, storeKind);
+            case "getEntriesBinary": return this.getEntriesBinary(req, storeKind);
+            case "putEntriesBinary": return this.putEntriesBinary(req, storeKind);
+            case "getEntryMetadata": return this.getEntryMetadata(req, storeKind);
+            case "putEntries": return this.putEntries(req, storeKind);
+            case "hasEntries": return this.hasEntries(req, storeKind);
+            case "getAllIds": return this.getAllIds(req, storeKind);
+            case "resolveDependencies": return this.resolveDependencies(req, storeKind);
+            case "planDocumentMaterialization": return this.planDocumentMaterialization(req, storeKind);
+            case "planDocumentMaterializationBatch": return this.planDocumentMaterializationBatch(req, storeKind);
+            case "planAttachmentReadByWalkingMetadata": return this.planAttachmentReadByWalkingMetadata(req, storeKind);
+        }
+    }
+    serverStore(req, dbId, storeKind) {
+        return this.tenantManager.getServerStore(req.tenantId, dbId, storeKind);
+    }
+    async findNewEntries(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, haveIds } = req.body;
+            const validDbId = validateDbId(dbId);
+            (0, validation_1.validateArraySize)(haveIds, validation_1.MAX_HAVE_IDS, "haveIds");
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const entries = await serverStore.handleFindNewEntries(token, haveIds || []);
+            return (0, types_4.jsonResponse)(200, {
+                entries: entries.map((e) => (0, entryWireCodec_1.serializeEntryMetadata)(e)),
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async findNewEntriesForDoc(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, haveIds, docId } = req.body;
+            const validDbId = validateDbId(dbId);
+            if (!docId) {
+                return (0, types_4.jsonResponse)(400, { error: "docId is required" });
+            }
+            (0, validation_1.validateArraySize)(haveIds, validation_1.MAX_HAVE_IDS, "haveIds");
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const entries = await serverStore.handleFindNewEntriesForDoc(token, haveIds || [], docId);
+            return (0, types_4.jsonResponse)(200, {
+                entries: entries.map((e) => (0, entryWireCodec_1.serializeEntryMetadata)(e)),
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async findEntries(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, type, creationDateFrom, creationDateUntil } = req.body;
+            const validDbId = validateDbId(dbId);
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const entries = await serverStore.handleFindEntries(token, type, creationDateFrom ?? null, creationDateUntil ?? null);
+            return (0, types_4.jsonResponse)(200, {
+                entries: entries.map((e) => (0, entryWireCodec_1.serializeEntryMetadata)(e)),
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async scanEntriesSince(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, cursor, limit, filters } = req.body;
+            const validDbId = validateDbId(dbId);
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const result = await serverStore.handleScanEntriesSince(token, cursor ?? null, limit, filters);
+            return (0, types_4.jsonResponse)(200, {
+                entries: result.entries.map((e) => (0, entryWireCodec_1.serializeEntryMetadata)(e)),
+                nextCursor: result.nextCursor,
+                hasMore: result.hasMore,
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async getStoreHead(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId } = req.body;
+            const validDbId = validateDbId(dbId);
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const head = await serverStore.handleGetStoreHead(token);
+            return (0, types_4.jsonResponse)(200, { head });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async getIdBloomSummary(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId } = req.body;
+            const validDbId = validateDbId(dbId);
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const summary = await serverStore.handleGetIdBloomSummary(token);
+            return (0, types_4.jsonResponse)(200, { summary: summary });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async getCapabilities(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const validDbId = validateDbId(req.query.dbId);
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const capabilities = await serverStore.handleGetCapabilities(token);
+            // HTTP-layer features on top of the transport-agnostic capability set:
+            // binary octet-stream framing routes (phase 3) and the SSE change feed
+            // (phase 5) exist only over HTTP.
+            return (0, types_4.jsonResponse)(200, {
+                capabilities: {
+                    ...capabilities,
+                    supportsBinaryEntries: true,
+                    supportsPayloadOnlyEntries: true,
+                    supportsChangeEvents: true,
+                },
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    /**
+     * SSE live change feed (sync-v5, phase 5).
+     *
+     * `GET /:tenantId/sync/:storeKind/events` — Bearer-authenticated like every
+     * other sync route (fetch-streaming clients can set headers; native
+     * EventSource cannot, which is why the SDK uses a fetch reader).
+     *
+     * The subscribe-time read gate runs via `handleGetCapabilities` against the
+     * database given in `?dbId=` (default `directory`, which every tenant member
+     * can read): it validates the token and runs the database-open gate. Events
+     * carry only `{dbId, storeKind, epoch, maxReceiptOrder}` — metadata, never
+     * content. The host keeps the stream open with a heartbeat every 30 s. Token
+     * expiry does not tear down an open stream; the events are non-sensitive
+     * change hints and a reconnect re-authenticates.
+     */
+    async syncEvents(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const tenantId = req.tenantId;
+            const gateDbId = validateDbId(typeof req.query.dbId === "string" && req.query.dbId ? req.query.dbId : "directory");
+            // Validates the token and runs the database-open/read gate before any
+            // event is delivered.
+            const serverStore = await this.serverStore(req, gateDbId, storeKind);
+            await serverStore.handleGetCapabilities(token);
+            return { status: 200, events: { tenantId, storeKind } };
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    /**
+     * Publish a change event after an accepted putEntries write (sync-v5,
+     * phase 5). Fire-and-forget: head lookup failures must never affect the
+     * write path.
+     */
+    publishSyncChangeEvent(tenantId, dbId, storeKind, serverStore, token) {
+        const events = this.options.syncEvents;
+        if (events.listenerCount === 0) {
+            return;
+        }
+        // Peer replicators subscribe to this bus, so a write that arrived from a
+        // peer has to be labelled: without the label it would be pushed straight
+        // back to its origin, and two bidirectional peers would ping-pong.
+        const originPeer = this.options.cluster
+            ? this.options.cluster.resolvePeerName(token)
+            : Promise.resolve(undefined);
+        this.runInBackground(Promise.all([serverStore.handleGetStoreHead(token).catch(() => null), originPeer]).then(([head, peerName]) => {
+            events.publish({
+                tenantId,
+                dbId,
+                storeKind,
+                epoch: head?.epoch,
+                maxReceiptOrder: head?.maxReceiptOrder,
+                originPeer: peerName,
+            });
+        }));
+    }
+    /**
+     * Work that follows an accepted write: the change event, and for a
+     * directory push the purge requests it may carry (docs/accesscontrol.md
+     * §13), which physically remove purged history from this server's stores
+     * and arm the re-push denylist. Both are fire-and-forget; purge failures
+     * are logged and retried on the next directory push.
+     */
+    afterAcceptedWrite(tenantId, dbId, storeKind, serverStore, token, receiptCount) {
+        // Announce the accepted write to SSE subscribers (sync-v5, phase 5).
+        if (receiptCount > 0) {
+            this.publishSyncChangeEvent(tenantId, dbId, storeKind, serverStore, token);
+        }
+        if (dbId === "directory") {
+            const onDirectoryWrite = this.options.onDirectoryWrite ?? ((id) => this.tenantManager.executePendingPurges(id));
+            this.runInBackground(onDirectoryWrite(tenantId).catch((error) => {
+                console.error(`[MindooDBServer] executePendingPurges failed for ${tenantId}:`, error);
+            }));
+        }
+    }
+    async getCompactionStatus(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId } = req.body;
+            const validDbId = validateDbId(dbId);
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const status = await serverStore.handleGetCompactionStatus(token);
+            return (0, types_4.jsonResponse)(200, { status: status });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async getEntries(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, ids, sessionKeyWrap } = req.body;
+            const validDbId = validateDbId(dbId);
+            (0, validation_1.validateArraySize)(ids, validation_1.MAX_ENTRY_IDS, "ids");
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            // Session-key transport format (sync-v5, phase 2): one RSA-wrapped
+            // AES-256-GCM key per response instead of per-entry RSA. Negotiated via
+            // the `sessionKeyWrap` request flag; legacy clients get the old format.
+            if (sessionKeyWrap === true) {
+                const batch = await serverStore.handleGetEntriesSessionWrapped(token, ids || []);
+                return (0, types_4.jsonResponse)(200, {
+                    wrappedSessionKey: (0, base64_1.bytesToBase64)(batch.wrappedSessionKey),
+                    entries: batch.entries.map((e) => ({
+                        ...(0, entryWireCodec_1.serializeEntryMetadata)(e),
+                        iv: (0, base64_1.bytesToBase64)(e.iv),
+                        sessionEncryptedPayload: (0, base64_1.bytesToBase64)(e.sessionEncryptedPayload),
+                    })),
+                });
+            }
+            const entries = await serverStore.handleGetEntries(token, ids || []);
+            return (0, types_4.jsonResponse)(200, {
+                entries: entries.map((e) => ({
+                    ...(0, entryWireCodec_1.serializeEntryMetadata)(e),
+                    rsaEncryptedPayload: (0, base64_1.bytesToBase64)(e.rsaEncryptedPayload),
+                })),
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    /**
+     * Binary variant of getEntries (sync-v5, phase 3): always session-key
+     * encrypted, response framed as `application/octet-stream` (see
+     * binaryEntryFraming.ts). The request stays JSON (small).
+     */
+    async getEntriesBinary(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, ids, payloadOnly } = req.body;
+            const validDbId = validateDbId(dbId);
+            (0, validation_1.validateArraySize)(ids, validation_1.MAX_ENTRY_IDS, "ids");
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const batch = await serverStore.handleGetEntriesSessionWrapped(token, ids || []);
+            // `payloadOnly` (capability supportsPayloadOnlyEntries): the client
+            // already holds the metadata from its scan, so each frame carries only
+            // what it cannot have yet. Same entries, same session-key encryption.
+            const body = (0, binaryEntryFraming_1.encodeBinaryEntryMessage)({
+                header: {
+                    format: binaryEntryFraming_1.BINARY_GET_ENTRIES_FORMAT,
+                    wrappedSessionKey: (0, base64_1.bytesToBase64)(batch.wrappedSessionKey),
+                    ...(payloadOnly === true ? { payloadOnly: true } : {}),
+                },
+                entries: batch.entries.map((e) => ({
+                    meta: payloadOnly === true
+                        ? { id: e.id, iv: (0, base64_1.bytesToBase64)(e.iv) }
+                        : { ...(0, entryWireCodec_1.serializeEntryMetadata)(e), iv: (0, base64_1.bytesToBase64)(e.iv) },
+                    payload: e.sessionEncryptedPayload,
+                })),
+            });
+            const payloadBytes = batch.entries.reduce((sum, e) => sum + e.sessionEncryptedPayload.byteLength, 0);
+            return {
+                status: 200,
+                bytes: body,
+                headers: { "content-type": binaryEntryFraming_1.BINARY_ENTRIES_CONTENT_TYPE },
+                binaryEntryFrameBytes: body.byteLength - payloadBytes,
+            };
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async getEntryMetadata(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, id } = req.body;
+            const validDbId = validateDbId(dbId);
+            if (!id) {
+                return (0, types_4.jsonResponse)(400, { error: "id is required" });
+            }
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const entry = await serverStore.handleGetEntryMetadata(token, id);
+            return (0, types_4.jsonResponse)(200, {
+                entry: entry ? (0, entryWireCodec_1.serializeEntryMetadata)(entry) : null,
+            });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    /**
+     * Ingest encrypted entries from a client. The `stage` variable tracks
+     * progress through the pipeline so that error logs pinpoint the failing
+     * step (token extraction → body parsing → deserialization → storage).
+     */
+    async putEntries(req, storeKind) {
+        let stage = "extract-token";
+        try {
+            const token = extractToken(req);
+            stage = "read-body";
+            const { dbId, entries } = req.body;
+            const validDbId = validateDbId(dbId);
+            (0, validation_1.validateArraySize)(entries, validation_1.MAX_PUT_ENTRIES, "entries");
+            const serializedEntries = Array.isArray(entries) ? entries : [];
+            const serializedEntryTypeCounts = serializedEntries.reduce((acc, entry) => {
+                const key = entry?.entryType ?? "unknown";
+                acc[key] = (acc[key] ?? 0) + 1;
+                return acc;
+            }, {});
+            console.log(`[MindooDBServer] putEntries request tenant=${req.tenantId ?? "-"} db=${validDbId} entries=${serializedEntries.length} parsed-bytes=${req.jsonBodyBytes ?? "-"} content-length=${req.headers["content-length"] ?? "-"} types=${JSON.stringify(serializedEntryTypeCounts)}`);
+            stage = "load-server-store";
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            stage = "deserialize-entries";
+            const deserializedEntries = serializedEntries.map((entry, index) => {
+                try {
+                    return (0, entryWireCodec_1.deserializeStoreEntry)(entry);
+                }
+                catch (error) {
+                    console.error("[MindooDBServer] putEntries failed while deserializing entry", {
+                        index,
+                        id: entry?.id ?? "-",
+                        type: entry?.entryType ?? "-",
+                        docId: entry?.docId ?? "-",
+                        encryptedSize: entry?.encryptedSize ?? "-",
+                        originalSize: entry?.originalSize ?? "-",
+                        signatureLength: entry?.signature?.length ?? "-",
+                        encryptedDataLength: entry?.encryptedData?.length ?? "-",
+                        error,
+                    });
+                    throw error;
+                }
+            });
+            const totalEncryptedBytes = deserializedEntries.reduce((sum, entry) => sum + entry.encryptedData.byteLength, 0);
+            const totalOriginalBytes = deserializedEntries.reduce((sum, entry) => sum + entry.originalSize, 0);
+            console.log(`[MindooDBServer] putEntries deserialized tenant=${req.tenantId ?? "-"} db=${validDbId} entries=${deserializedEntries.length} totalEncryptedBytes=${totalEncryptedBytes} totalOriginalBytes=${totalOriginalBytes}`);
+            stage = "store-entries";
+            const ack = await serverStore.handlePutEntries(token, deserializedEntries);
+            stage = "respond-success";
+            this.afterAcceptedWrite(req.tenantId, validDbId, storeKind, serverStore, token, ack.receipts.length);
+            // Return witness receipts for accepted entries so the pushing client (and
+            // every replica it later syncs with) can persist the attestation
+            // (docs/accesscontrol.md §5.3), plus per-entry rejections for
+            // signature-class failures the server skipped. Older clients ignore the
+            // extra fields.
+            return (0, types_4.jsonResponse)(200, {
+                success: true,
+                receipts: ack.receipts.map((e) => (0, entryWireCodec_1.serializeEntryMetadata)(e)),
+                rejected: ack.rejected,
+            });
+        }
+        catch (error) {
+            console.error("[MindooDBServer] putEntries failed", {
+                stage,
+                tenantId: req.tenantId ?? "-",
+                dbId: req.body?.dbId ?? "-",
+                parsedBytes: req.jsonBodyBytes ?? "-",
+                contentLength: req.headers["content-length"] ?? "-",
+                entryCount: Array.isArray(req.body?.entries) ? req.body.entries.length : "-",
+                error,
+            });
+            return errorResponse(error);
+        }
+    }
+    /**
+     * Binary variant of putEntries (sync-v5, phase 3). The request body is
+     * octet-stream framing; `dbId` travels in the message header JSON because
+     * there is no JSON body. Receipts are returned as JSON like putEntries.
+     */
+    async putEntriesBinary(req, storeKind) {
+        let stage = "extract-token";
+        try {
+            const token = extractToken(req);
+            stage = "decode-body";
+            if (!req.rawBody) {
+                return (0, types_4.jsonResponse)(400, { error: `putEntriesBinary requires a ${binaryEntryFraming_1.BINARY_ENTRIES_CONTENT_TYPE} body` });
+            }
+            const message = (0, binaryEntryFraming_1.decodeBinaryEntryMessage)(req.rawBody);
+            if (message.header.format !== binaryEntryFraming_1.BINARY_PUT_ENTRIES_FORMAT) {
+                return (0, types_4.jsonResponse)(400, { error: `Unsupported binary entry format: ${String(message.header.format)}` });
+            }
+            const validDbId = validateDbId(message.header.dbId);
+            (0, validation_1.validateArraySize)(message.entries, validation_1.MAX_PUT_ENTRIES, "entries");
+            console.log(`[MindooDBServer] putEntriesBinary request tenant=${req.tenantId ?? "-"} db=${validDbId} entries=${message.entries.length} content-length=${req.headers["content-length"] ?? "-"}`);
+            stage = "load-server-store";
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            stage = "deserialize-entries";
+            const deserializedEntries = message.entries.map((frame, index) => {
+                const meta = frame.meta;
+                try {
+                    return {
+                        ...(0, entryWireCodec_1.deserializeEntryMetadata)(meta),
+                        encryptedData: frame.payload,
+                    };
+                }
+                catch (error) {
+                    console.error("[MindooDBServer] putEntriesBinary failed while deserializing entry", {
+                        index,
+                        id: meta?.id ?? "-",
+                        type: meta?.entryType ?? "-",
+                        docId: meta?.docId ?? "-",
+                        payloadLength: frame.payload?.byteLength ?? "-",
+                        error,
+                    });
+                    throw error;
+                }
+            });
+            stage = "store-entries";
+            const ack = await serverStore.handlePutEntries(token, deserializedEntries);
+            stage = "respond-success";
+            // Same post-response hooks as the JSON putEntries path.
+            this.afterAcceptedWrite(req.tenantId, validDbId, storeKind, serverStore, token, ack.receipts.length);
+            return (0, types_4.jsonResponse)(200, {
+                success: true,
+                receipts: ack.receipts.map((e) => (0, entryWireCodec_1.serializeEntryMetadata)(e)),
+                rejected: ack.rejected,
+            });
+        }
+        catch (error) {
+            console.error("[MindooDBServer] putEntriesBinary failed", {
+                stage,
+                tenantId: req.tenantId ?? "-",
+                contentLength: req.headers["content-length"] ?? "-",
+                error,
+            });
+            return errorResponse(error);
+        }
+    }
+    async hasEntries(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, ids } = req.body;
+            const validDbId = validateDbId(dbId);
+            (0, validation_1.validateArraySize)(ids, validation_1.MAX_ENTRY_IDS, "ids");
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const existingIds = await serverStore.handleHasEntries(token, ids || []);
+            return (0, types_4.jsonResponse)(200, { ids: existingIds });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async getAllIds(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const validDbId = validateDbId(req.query.dbId);
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const ids = await serverStore.handleGetAllIds(token);
+            return (0, types_4.jsonResponse)(200, { ids });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async resolveDependencies(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, startId, options } = req.body;
+            const validDbId = validateDbId(dbId);
+            if (!startId) {
+                return (0, types_4.jsonResponse)(400, { error: "startId is required" });
+            }
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const ids = await serverStore.handleResolveDependencies(token, startId, options);
+            return (0, types_4.jsonResponse)(200, { ids });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async planDocumentMaterialization(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, docId, options } = req.body;
+            const validDbId = validateDbId(dbId);
+            if (!docId) {
+                return (0, types_4.jsonResponse)(400, { error: "docId is required" });
+            }
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const plan = await serverStore.handlePlanDocumentMaterialization(token, docId, options);
+            return (0, types_4.jsonResponse)(200, { plan: plan });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async planDocumentMaterializationBatch(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, docIds, options } = req.body;
+            const validDbId = validateDbId(dbId);
+            (0, validation_1.validateArraySize)(docIds, validation_1.MAX_HAVE_IDS, "docIds");
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const batchPlan = await serverStore.handlePlanDocumentMaterializationBatch(token, docIds || [], options);
+            return (0, types_4.jsonResponse)(200, { batchPlan: batchPlan });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+    async planAttachmentReadByWalkingMetadata(req, storeKind) {
+        try {
+            const token = extractToken(req);
+            const { dbId, lastChunkId, attachmentSize, options } = req.body;
+            const validDbId = validateDbId(dbId);
+            if (!lastChunkId) {
+                return (0, types_4.jsonResponse)(400, { error: "lastChunkId is required" });
+            }
+            if (typeof attachmentSize !== "number" || !Number.isFinite(attachmentSize)) {
+                return (0, types_4.jsonResponse)(400, { error: "attachmentSize is required" });
+            }
+            if (!options || typeof options.startByte !== "number") {
+                return (0, types_4.jsonResponse)(400, { error: "options.startByte is required" });
+            }
+            const serverStore = await this.serverStore(req, validDbId, storeKind);
+            const plan = await serverStore.handlePlanAttachmentReadByWalkingMetadata(token, lastChunkId, attachmentSize, options);
+            return (0, types_4.jsonResponse)(200, { plan: plan });
+        }
+        catch (error) {
+            return errorResponse(error);
+        }
+    }
+}
+exports.MindooDBServerCore = MindooDBServerCore;
+//# sourceMappingURL=MindooDBServerCore.js.map