mindoodb 0.0.9 → 0.0.11

package/dist/node/server/MindooDBServer.js

@@ -51,21 +51,33 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MindooDBServer = void 0;
 const express_1 = __importStar(require("express"));
-const https_1 = __importDefault(require("https"));
+const http2_1 = __importDefault(require("http2"));
 const path_1 = __importDefault(require("path"));
 const fs_1 = require("fs");
 const helmet_1 = __importDefault(require("helmet"));
 const cors_1 = __importDefault(require("cors"));
 const express_rate_limit_1 = __importDefault(require("express-rate-limit"));
-const types_1 = require("../../core/appendonlystores/network/types");
+const types_1 = require("../../core/appendonlystores/types");
+const types_2 = require("../../core/appendonlystores/network/types");
 const TenantManager_1 = require("./TenantManager");
 const CapabilityMatcher_1 = require("./CapabilityMatcher");
 const SystemAdminAuth_1 = require("./SystemAdminAuth");
 const config_1 = require("./config");
 const SystemIpAllowlist_1 = require("./SystemIpAllowlist");
 const validation_1 = require("./validation");
+/**
+ * Rate-limit defaults. Auth and sync have separate tiers because a single
+ * challenge/authenticate handshake is two requests; with multiple tenants,
+ * store kinds, and token renewals the auth budget exhausts quickly if set
+ * too low. These can be overridden in config.json under `rateLimits.auth`
+ * and `rateLimits.sync`.
+ */
+const DEFAULT_AUTH_RATE_LIMIT_WINDOW_MS = 60000;
+const DEFAULT_AUTH_RATE_LIMIT_MAX = 120;
 const DEFAULT_SYNC_RATE_LIMIT_WINDOW_MS = 60000;
 const DEFAULT_SYNC_RATE_LIMIT_MAX = 1000;
+const DEFAULT_SERVER_SOCKET_TIMEOUT_MS = 120000;
+/** Parse a human-readable size string ("5mb", "1024", "100kb") into bytes. */
 function parseBodySizeLimitToBytes(limit) {
     const normalized = limit.trim().toLowerCase();
     if (!normalized) {
@@ -90,6 +102,15 @@ function parseBodySizeLimitToBytes(limit) {
     return Math.round(value * multiplier);
 }
 class MindooDBServer {
+    /**
+     * @param dataDir      Root directory for on-disk tenant data and server identity
+     * @param serverPassword  Password used to decrypt the server identity private keys
+     *                        and per-tenant key bags at startup
+     * @param staticDir    Optional directory served at /statics/ (e.g. the Haven web UI)
+     * @param config       Pre-loaded ServerConfig; when omitted, an empty config
+     *                     is used (all /system/* endpoints locked down)
+     * @param configPath   Explicit path to config.json; defaults to `<dataDir>/config.json`
+     */
     constructor(dataDir, serverPassword, staticDir, config, configPath) {
         this.app = (0, express_1.default)();
         this.tenantManager = new TenantManager_1.TenantManager(dataDir, serverPassword);
@@ -99,6 +120,8 @@ class MindooDBServer {
         this.jsonBodyLimitBytes = parseBodySizeLimitToBytes(this.jsonBodyLimit);
         this.serverConfig = config ?? { capabilities: {} };
         this.capabilityMatcher = new CapabilityMatcher_1.CapabilityMatcher(this.serverConfig);
+        // SystemAdminAuthService generates a random HMAC-SHA256 secret for JWTs
+        // on each server start — existing tokens become invalid after restart.
         const cryptoAdapter = this.tenantManager.getCryptoAdapter();
         this.systemAdminAuth = new SystemAdminAuth_1.SystemAdminAuthService(cryptoAdapter, this.serverConfig);
         const principalCount = Object.values(this.serverConfig.capabilities).reduce((sum, arr) => sum + arr.length, 0);
@@ -126,6 +149,11 @@ class MindooDBServer {
     getConfigPath() {
         return this.configPath;
     }
+    /**
+     * Hot-swap the server config without restarting. In-flight JWTs remain
+     * valid (same HMAC secret), but removed principals will fail the
+     * CapabilityMatcher check on their next request.
+     */
     reloadConfig(newConfig) {
         this.serverConfig = newConfig;
         this.capabilityMatcher.reload(newConfig);
@@ -135,19 +163,37 @@ class MindooDBServer {
         const server = this.app.listen(port, () => {
             console.log(`[MindooDBServer] Listening on port ${port}`);
         });
-        server.setTimeout(30000);
+        server.setTimeout(DEFAULT_SERVER_SOCKET_TIMEOUT_MS);
     }
+    /**
+     * Start the server with TLS using HTTP/2 (with automatic HTTP/1.1 ALPN
+     * fallback for clients that don't support h2). Express is mounted as the
+     * raw handler because http2.createSecureServer doesn't natively integrate
+     * with Express; the `as unknown` casts bridge the type gap.
+     */
     listenTls(port, certPath, keyPath) {
         const tlsOptions = {
+            allowHTTP1: true,
             cert: (0, fs_1.readFileSync)(certPath),
             key: (0, fs_1.readFileSync)(keyPath),
         };
-        const server = https_1.default.createServer(tlsOptions, this.app);
+        const server = http2_1.default.createSecureServer(tlsOptions, (req, res) => {
+            this.app(req, res);
+        });
         server.listen(port, () => {
-            console.log(`[MindooDBServer] Listening on HTTPS port ${port}`);
+            console.log(`[MindooDBServer] Listening on HTTPS port ${port} with HTTP/2 enabled (HTTP/1 fallback active)`);
         });
-        server.setTimeout(30000);
+        server.setTimeout(DEFAULT_SERVER_SOCKET_TIMEOUT_MS);
     }
+    /**
+     * Global middleware stack applied to every request, in order:
+     * 1. helmet — security headers (CSP, X-Frame-Options, etc.)
+     * 2. cors — controlled cross-origin access for web clients (e.g. Haven)
+     * 3. global rate limit — coarse IP-based throttle as a safety net;
+     *    individual route tiers (auth, sync, system) provide finer control
+     * 4. JSON body parser — captures raw byte size for diagnostics
+     * 5. request logger
+     */
     setupMiddleware() {
         this.app.use((0, helmet_1.default)());
         const corsOrigin = this.readCorsOriginsFromEnv();
@@ -172,10 +218,11 @@ class MindooDBServer {
         this.app.use((req, res, next) => {
             const contentType = req.headers["content-type"] ?? "-";
             const contentLength = req.headers["content-length"] ?? "-";
-            console.log(`[${new Date().toISOString()}] ${req.method} ${req.path} content-type=${contentType} content-length=${contentLength}`);
+            console.log(`[${new Date().toISOString()}] HTTP/${req.httpVersion} ${req.method} ${req.path} content-type=${contentType} content-length=${contentLength}`);
             next();
         });
     }
+    /** Parse MINDOODB_CORS_ORIGIN env var; supports comma-separated multiple origins. */
     readCorsOriginsFromEnv() {
         const raw = process.env.MINDOODB_CORS_ORIGIN?.trim();
         if (!raw) {
@@ -190,8 +237,16 @@ class MindooDBServer {
         }
         return origins;
     }
+    /**
+     * Route hierarchy:
+     *  /                         — redirect to static UI (if present)
+     *  /health                   — unauthenticated health probe
+     *  /.well-known/*            — public discovery endpoints (server info, tenant fingerprints)
+     *  /statics/*                — optional static file serving (Haven web UI)
+     *  /system/*                 — admin API: IP-allowlisted, JWT-authenticated, capability-checked
+     *  /:tenantId/*              — per-tenant sync & auth API
+     */
     setupRoutes() {
-        // Root redirect
         this.app.get("/", (req, res) => {
             if (this.staticDir && (0, fs_1.existsSync)(path_1.default.join(this.staticDir, "index.html"))) {
                 res.redirect(302, "/statics/index.html");
@@ -203,6 +258,8 @@ class MindooDBServer {
         this.app.get("/health", (req, res) => {
             res.json({ status: "ok", timestamp: Date.now() });
         });
+        // .well-known endpoints are unauthenticated so clients can discover
+        // server identity and tenant availability before attempting to authenticate.
         this.app.get("/.well-known/mindoodb-server-info", (req, res) => {
             const info = this.tenantManager.getServerPublicInfo();
             if (!info) {
@@ -255,7 +312,10 @@ class MindooDBServer {
             }, express_1.default.static(resolvedStaticDir, { dotfiles: "deny", etag: true }));
             console.log(`[MindooDBServer] Serving static files from ${resolvedStaticDir} at /statics/`);
         }
-        // System admin routes (replaces former /admin/*)
+        // /system/* admin routes are protected by three layers (applied in order):
+        //  1. IP allowlist — optional whitelist via MINDOODB_ADMIN_ALLOWED_IPS env var
+        //  2. Rate limit  — aggressive per-IP throttle (30 req/min)
+        //  3. JWT auth    — applied per-route (auth endpoints exempt; they *produce* JWTs)
         const systemIpRaw = (0, SystemIpAllowlist_1.readSystemIpAllowListFromEnv)();
         if (!(0, SystemIpAllowlist_1.isSystemIpAllowListDisabled)(systemIpRaw)) {
             console.log(`[MindooDBServer] MINDOODB_ADMIN_ALLOWED_IPS is set — /system/* limited to: ${systemIpRaw}`);
@@ -270,8 +330,10 @@ class MindooDBServer {
         const systemRouter = (0, express_1.Router)();
         this.setupSystemRoutes(systemRouter);
         this.app.use("/system", SystemIpAllowlist_1.systemIpAllowlistMiddleware, systemRateLimit, systemRouter);
-        // Tenant-scoped routes
+        // Tenant-scoped routes: tenantMiddleware validates the :tenantId param
+        // and rejects unknown tenants before any handler runs.
         this.app.use("/:tenantId", this.tenantMiddleware.bind(this), this.createTenantRouter());
+        // Express error handler — must be registered last and have the 4-arg signature
         this.app.use(this.errorHandler.bind(this));
     }
     // ==================== System Admin Auth Middleware ====================
@@ -328,18 +390,17 @@ class MindooDBServer {
         next();
     }
     // ==================== System Routes ====================
+    /**
+     * Wire up all /system/* routes. Auth endpoints sit outside the JWT
+     * middleware because they implement the challenge-response handshake
+     * that *produces* the JWT. Every other route requires a valid JWT and
+     * passes through the CapabilityMatcher for fine-grained authorization.
+     */
     setupSystemRoutes(router) {
-        // Auth endpoints — no JWT required (these *produce* JWTs)
-        const authRateLimit = (0, express_rate_limit_1.default)({
-            windowMs: 60000,
-            max: 20,
-            standardHeaders: true,
-            legacyHeaders: false,
-            message: { error: "Too many authentication attempts, please try again later" },
-        });
-        router.post("/auth/challenge", authRateLimit, this.handleSystemChallenge.bind(this));
-        router.post("/auth/authenticate", authRateLimit, this.handleSystemAuthenticate.bind(this));
-        // All other /system/* routes require JWT + capability check
+        const challengeRateLimit = this.createAuthRateLimit("system", "challenge");
+        const authenticateRateLimit = this.createAuthRateLimit("system", "authenticate");
+        router.post("/auth/challenge", challengeRateLimit, this.handleSystemChallenge.bind(this));
+        router.post("/auth/authenticate", authenticateRateLimit, this.handleSystemAuthenticate.bind(this));
         const authMiddleware = this.systemAdminMiddleware.bind(this);
         // Tenant CRUD
         router.get("/tenants", authMiddleware, (req, res) => {
@@ -353,6 +414,8 @@ class MindooDBServer {
                 res.status(500).json({ error: "Failed to list tenants" });
             }
         });
+        // Tenant registration is idempotent: re-POSTing with the same tenantId
+        // and matching $publicinfos key returns 200 instead of 409.
         router.post("/tenants/:tenantId", authMiddleware, async (req, res) => {
             try {
                 const tenantId = req.params.tenantId.toLowerCase();
@@ -724,7 +787,8 @@ class MindooDBServer {
                 });
                 return;
             }
-            // Self-lockout protection: verify the calling admin retains PUT /system/config access
+            // 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)) {
@@ -756,18 +820,20 @@ class MindooDBServer {
         }
     }
     // ==================== Tenant Routes ====================
+    /**
+     * Build the per-tenant router. Rate limiters are scoped: auth endpoints
+     * use a per-user composite key (see createAuthRateLimit) while sync
+     * endpoints use a plain IP-based bucket with a higher ceiling.
+     *
+     * Both "docs" and "attachments" store kinds expose the same set of sync
+     * operations, mounted at /sync/docs/* and /sync/attachments/*.
+     */
     createTenantRouter() {
         const router = (0, express_1.Router)({ mergeParams: true });
+        const authRateLimitConfig = this.getAuthRateLimitConfig();
         const syncRateLimitConfig = this.getSyncRateLimitConfig();
-        // Auth endpoints get stricter rate limiting
-        const authRateLimit = (0, express_rate_limit_1.default)({
-            windowMs: 60000,
-            max: 20,
-            standardHeaders: true,
-            legacyHeaders: false,
-            message: { error: "Too many authentication attempts, please try again later" },
-        });
-        // Sync endpoints get a higher limit
+        const challengeRateLimit = this.createAuthRateLimit("tenant", "challenge");
+        const authenticateRateLimit = this.createAuthRateLimit("tenant", "authenticate");
         const syncRateLimit = (0, express_rate_limit_1.default)({
             windowMs: syncRateLimitConfig.windowMs,
             max: syncRateLimitConfig.max,
@@ -775,32 +841,107 @@ class MindooDBServer {
             legacyHeaders: false,
             message: { error: "Too many sync requests, please try again later" },
         });
-        router.post("/auth/challenge", authRateLimit, this.handleChallenge.bind(this));
-        router.post("/auth/authenticate", authRateLimit, this.handleAuthenticate.bind(this));
-        router.post("/sync/findNewEntries", syncRateLimit, this.handleFindNewEntries.bind(this));
-        router.post("/sync/findNewEntriesForDoc", syncRateLimit, this.handleFindNewEntriesForDoc.bind(this));
-        router.post("/sync/findEntries", syncRateLimit, this.handleFindEntries.bind(this));
-        router.post("/sync/scanEntriesSince", syncRateLimit, this.handleScanEntriesSince.bind(this));
-        router.post("/sync/getIdBloomSummary", syncRateLimit, this.handleGetIdBloomSummary.bind(this));
-        router.post("/sync/getCompactionStatus", syncRateLimit, this.handleGetCompactionStatus.bind(this));
-        router.get("/sync/capabilities", syncRateLimit, this.handleGetCapabilities.bind(this));
-        router.post("/sync/getEntries", syncRateLimit, this.handleGetEntries.bind(this));
-        router.post("/sync/getEntryMetadata", syncRateLimit, this.handleGetEntryMetadata.bind(this));
-        router.post("/sync/putEntries", syncRateLimit, this.handlePutEntries.bind(this));
-        router.post("/sync/hasEntries", syncRateLimit, this.handleHasEntries.bind(this));
-        router.get("/sync/getAllIds", syncRateLimit, this.handleGetAllIds.bind(this));
-        router.post("/sync/resolveDependencies", syncRateLimit, this.handleResolveDependencies.bind(this));
-        router.post("/sync/planDocumentMaterialization", syncRateLimit, this.handlePlanDocumentMaterialization.bind(this));
-        router.post("/sync/planDocumentMaterializationBatch", syncRateLimit, this.handlePlanDocumentMaterializationBatch.bind(this));
-        router.post("/sync/planAttachmentReadByWalkingMetadata", syncRateLimit, this.handlePlanAttachmentReadByWalkingMetadata.bind(this));
+        console.log(`[MindooDBServer] Tenant auth rate limit configured windowMs=${authRateLimitConfig.windowMs} max=${authRateLimitConfig.max}`);
+        router.post("/auth/challenge", challengeRateLimit, this.handleChallenge.bind(this));
+        router.post("/auth/authenticate", authenticateRateLimit, this.handleAuthenticate.bind(this));
+        for (const storeKind of ["docs", "attachments"]) {
+            const syncBase = `/sync/${storeKind}`;
+            router.post(`${syncBase}/findNewEntries`, syncRateLimit, this.handleFindNewEntries.bind(this));
+            router.post(`${syncBase}/findNewEntriesForDoc`, syncRateLimit, this.handleFindNewEntriesForDoc.bind(this));
+            router.post(`${syncBase}/findEntries`, syncRateLimit, this.handleFindEntries.bind(this));
+            router.post(`${syncBase}/scanEntriesSince`, syncRateLimit, this.handleScanEntriesSince.bind(this));
+            router.post(`${syncBase}/getIdBloomSummary`, syncRateLimit, this.handleGetIdBloomSummary.bind(this));
+            router.post(`${syncBase}/getCompactionStatus`, syncRateLimit, this.handleGetCompactionStatus.bind(this));
+            router.get(`${syncBase}/capabilities`, syncRateLimit, this.handleGetCapabilities.bind(this));
+            router.post(`${syncBase}/getEntries`, syncRateLimit, this.handleGetEntries.bind(this));
+            router.post(`${syncBase}/getEntryMetadata`, syncRateLimit, this.handleGetEntryMetadata.bind(this));
+            router.post(`${syncBase}/putEntries`, syncRateLimit, this.handlePutEntries.bind(this));
+            router.post(`${syncBase}/hasEntries`, syncRateLimit, this.handleHasEntries.bind(this));
+            router.get(`${syncBase}/getAllIds`, syncRateLimit, this.handleGetAllIds.bind(this));
+            router.post(`${syncBase}/resolveDependencies`, syncRateLimit, this.handleResolveDependencies.bind(this));
+            router.post(`${syncBase}/planDocumentMaterialization`, syncRateLimit, this.handlePlanDocumentMaterialization.bind(this));
+            router.post(`${syncBase}/planDocumentMaterializationBatch`, syncRateLimit, this.handlePlanDocumentMaterializationBatch.bind(this));
+            router.post(`${syncBase}/planAttachmentReadByWalkingMetadata`, syncRateLimit, this.handlePlanAttachmentReadByWalkingMetadata.bind(this));
+        }
         return router;
     }
+    /** Resolved auth rate-limit config; falls back to defaults when not set in config.json. */
+    getAuthRateLimitConfig() {
+        return {
+            windowMs: this.serverConfig.rateLimits?.auth?.windowMs ?? DEFAULT_AUTH_RATE_LIMIT_WINDOW_MS,
+            max: this.serverConfig.rateLimits?.auth?.max ?? DEFAULT_AUTH_RATE_LIMIT_MAX,
+        };
+    }
+    /** Resolved sync rate-limit config; falls back to defaults when not set in config.json. */
     getSyncRateLimitConfig() {
         return {
             windowMs: this.serverConfig.rateLimits?.sync?.windowMs ?? DEFAULT_SYNC_RATE_LIMIT_WINDOW_MS,
             max: this.serverConfig.rateLimits?.sync?.max ?? DEFAULT_SYNC_RATE_LIMIT_MAX,
         };
     }
+    /**
+     * Create a rate-limiter for authentication endpoints. Challenge and
+     * authenticate get separate limiters so that one phase can't starve the
+     * other. The custom keyGenerator buckets by (scope, tenant, phase, IP,
+     * username) — this prevents users behind a shared IP (NAT / reverse
+     * proxy) from exhausting each other's budgets.
+     */
+    createAuthRateLimit(scope, phase) {
+        const authRateLimitConfig = this.getAuthRateLimitConfig();
+        return (0, express_rate_limit_1.default)({
+            windowMs: authRateLimitConfig.windowMs,
+            max: authRateLimitConfig.max,
+            standardHeaders: true,
+            legacyHeaders: false,
+            keyGenerator: (req) => this.getAuthRateLimitKey(req, scope, phase),
+            handler: (req, res, _next, options) => {
+                this.logAuthRateLimitHit(req, scope, phase);
+                res.status(options.statusCode).json(options.message);
+            },
+            message: { error: "Too many authentication attempts, please try again later" },
+        });
+    }
+    /**
+     * Composite rate-limit key. Challenge requests include the username so
+     * that brute-forcing one account doesn't block legitimate users on the
+     * same IP. Authenticate requests omit username because the challenge
+     * token is already scoped to a single principal.
+     */
+    getAuthRateLimitKey(req, scope, phase) {
+        const tenantId = scope === "tenant"
+            ? req.tenantId ?? req.params.tenantId?.toLowerCase() ?? "-"
+            : "system";
+        const clientIp = this.getClientIpForRateLimit(req);
+        if (phase === "challenge") {
+            const username = typeof req.body?.username === "string"
+                ? req.body.username.trim().toLowerCase()
+                : "-";
+            return `${scope}:${tenantId}:${phase}:${clientIp}:${username}`;
+        }
+        return `${scope}:${tenantId}:${phase}:${clientIp}`;
+    }
+    /**
+     * Emit a structured warning when an auth rate limit is triggered.
+     * The forwarded-for header is logged to help diagnose situations where
+     * a reverse proxy collapses many clients onto a single visible IP.
+     */
+    logAuthRateLimitHit(req, scope, phase) {
+        const forwardedForHeader = req.headers["x-forwarded-for"];
+        const forwardedFor = Array.isArray(forwardedForHeader)
+            ? forwardedForHeader.join(", ")
+            : forwardedForHeader;
+        const username = typeof req.body?.username === "string" ? req.body.username : "-";
+        console.warn(`[MindooDBServer] Auth rate limit exceeded scope=${scope} phase=${phase} tenant=${req.tenantId ?? req.params.tenantId?.toLowerCase() ?? "-"} ip=${this.getClientIpForRateLimit(req)} forwarded-for=${forwardedFor ?? "-"} username=${username} path=${req.path}`);
+    }
+    /**
+     * Best-effort client IP. Express populates `req.ip` from the trust-proxy
+     * setting; fall back to the raw socket address when it's unavailable.
+     */
+    getClientIpForRateLimit(req) {
+        return ((typeof req.ip === "string" && req.ip.length > 0
+            ? req.ip
+            : req.socket?.remoteAddress) ?? "unknown");
+    }
     // ==================== Validation Helpers ====================
     validateDbId(dbId) {
         return (0, validation_1.validateIdentifier)(dbId, "dbId");
@@ -810,6 +951,10 @@ class MindooDBServer {
         return `Tenant ${tenantId} not found on server ${serverName}`;
     }
     // ==================== Tenant Auth Handlers ====================
+    // 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 handleChallenge(req, res) {
         try {
             const { username } = req.body;
@@ -847,7 +992,7 @@ class MindooDBServer {
             const { dbId, haveIds } = req.body;
             const validDbId = this.validateDbId(dbId);
             (0, validation_1.validateArraySize)(haveIds, validation_1.MAX_HAVE_IDS, "haveIds");
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const entries = await serverStore.handleFindNewEntries(token, haveIds || []);
             res.json({
                 entries: entries.map((e) => this.serializeEntryMetadata(e)),
@@ -867,7 +1012,7 @@ class MindooDBServer {
                 return;
             }
             (0, validation_1.validateArraySize)(haveIds, validation_1.MAX_HAVE_IDS, "haveIds");
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const entries = await serverStore.handleFindNewEntriesForDoc(token, haveIds || [], docId);
             res.json({
                 entries: entries.map((e) => this.serializeEntryMetadata(e)),
@@ -882,7 +1027,7 @@ class MindooDBServer {
             const token = this.extractToken(req);
             const { dbId, type, creationDateFrom, creationDateUntil } = req.body;
             const validDbId = this.validateDbId(dbId);
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const entries = await serverStore.handleFindEntries(token, type, creationDateFrom ?? null, creationDateUntil ?? null);
             res.json({
                 entries: entries.map((e) => this.serializeEntryMetadata(e)),
@@ -897,7 +1042,7 @@ class MindooDBServer {
             const token = this.extractToken(req);
             const { dbId, cursor, limit, filters } = req.body;
             const validDbId = this.validateDbId(dbId);
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const result = await serverStore.handleScanEntriesSince(token, cursor ?? null, limit, filters);
             res.json({
                 entries: result.entries.map((e) => this.serializeEntryMetadata(e)),
@@ -914,7 +1059,7 @@ class MindooDBServer {
             const token = this.extractToken(req);
             const { dbId } = req.body;
             const validDbId = this.validateDbId(dbId);
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const summary = await serverStore.handleGetIdBloomSummary(token);
             res.json({ summary: summary });
         }
@@ -927,7 +1072,7 @@ class MindooDBServer {
             const token = this.extractToken(req);
             const rawDbId = req.query.dbId || "directory";
             const validDbId = this.validateDbId(rawDbId);
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const capabilities = await serverStore.handleGetCapabilities(token);
             res.json({ capabilities: capabilities });
         }
@@ -940,7 +1085,7 @@ class MindooDBServer {
             const token = this.extractToken(req);
             const { dbId } = req.body;
             const validDbId = this.validateDbId(dbId);
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const status = await serverStore.handleGetCompactionStatus(token);
             res.json({ status: status });
         }
@@ -954,7 +1099,7 @@ class MindooDBServer {
             const { dbId, ids } = req.body;
             const validDbId = this.validateDbId(dbId);
             (0, validation_1.validateArraySize)(ids, validation_1.MAX_ENTRY_IDS, "ids");
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const entries = await serverStore.handleGetEntries(token, ids || []);
             res.json({
                 entries: entries.map((e) => ({
@@ -976,7 +1121,7 @@ class MindooDBServer {
                 res.status(400).json({ error: "id is required" });
                 return;
             }
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const entry = await serverStore.handleGetEntryMetadata(token, id);
             res.json({
                 entry: entry ? this.serializeEntryMetadata(entry) : null,
@@ -986,6 +1131,11 @@ class MindooDBServer {
             this.handleRequestError(error, res);
         }
     }
+    /**
+     * 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 handlePutEntries(req, res) {
         let stage = "extract-token";
         try {
@@ -1002,7 +1152,7 @@ class MindooDBServer {
             }, {});
             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.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             stage = "deserialize-entries";
             const deserializedEntries = serializedEntries.map((entry, index) => {
                 try {
@@ -1050,7 +1200,7 @@ class MindooDBServer {
             const { dbId, ids } = req.body;
             const validDbId = this.validateDbId(dbId);
             (0, validation_1.validateArraySize)(ids, validation_1.MAX_ENTRY_IDS, "ids");
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const existingIds = await serverStore.handleHasEntries(token, ids || []);
             res.json({ ids: existingIds });
         }
@@ -1063,7 +1213,7 @@ class MindooDBServer {
             const token = this.extractToken(req);
             const rawDbId = req.query.dbId || "directory";
             const validDbId = this.validateDbId(rawDbId);
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const ids = await serverStore.handleGetAllIds(token);
             res.json({ ids });
         }
@@ -1080,7 +1230,7 @@ class MindooDBServer {
                 res.status(400).json({ error: "startId is required" });
                 return;
             }
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const ids = await serverStore.handleResolveDependencies(token, startId, options);
             res.json({ ids });
         }
@@ -1097,7 +1247,7 @@ class MindooDBServer {
                 res.status(400).json({ error: "docId is required" });
                 return;
             }
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const plan = await serverStore.handlePlanDocumentMaterialization(token, docId, options);
             res.json({ plan: plan });
         }
@@ -1111,7 +1261,7 @@ class MindooDBServer {
             const { dbId, docIds, options } = req.body;
             const validDbId = this.validateDbId(dbId);
             (0, validation_1.validateArraySize)(docIds, validation_1.MAX_HAVE_IDS, "docIds");
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const batchPlan = await serverStore.handlePlanDocumentMaterializationBatch(token, docIds || [], options);
             res.json({ batchPlan: batchPlan });
         }
@@ -1136,7 +1286,7 @@ class MindooDBServer {
                 res.status(400).json({ error: "options.startByte is required" });
                 return;
             }
-            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId);
+            const serverStore = await this.tenantManager.getServerStore(req.tenantId, validDbId, this.getStoreKindFromRequest(req));
             const plan = await serverStore.handlePlanAttachmentReadByWalkingMetadata(token, lastChunkId, attachmentSize, options);
             res.json({ plan: plan });
         }
@@ -1149,13 +1299,29 @@ class MindooDBServer {
         res.json({ success: true, message: "Sync triggered (not yet implemented)" });
     }
     // ==================== Helper Methods ====================
+    /**
+     * Derive the StoreKind from the request path. Both "docs" and
+     * "attachments" share the same handler implementations; the store kind
+     * selects which on-disk append-only store to operate against.
+     */
+    getStoreKindFromRequest(req) {
+        const trimmedPath = req.path.replace(/\/$/, "");
+        if (trimmedPath.startsWith("/sync/docs/") || trimmedPath === "/sync/docs/capabilities" || trimmedPath === "/sync/docs/getAllIds") {
+            return types_1.StoreKind.docs;
+        }
+        if (trimmedPath.startsWith("/sync/attachments/") || trimmedPath === "/sync/attachments/capabilities" || trimmedPath === "/sync/attachments/getAllIds") {
+            return types_1.StoreKind.attachments;
+        }
+        throw new Error(`Unsupported sync store kind for path: ${req.path}`);
+    }
     extractToken(req) {
         const auth = req.headers.authorization;
         if (!auth || !auth.startsWith("Bearer ")) {
-            throw new types_1.NetworkError("INVALID_TOKEN", "Missing or invalid Authorization header");
+            throw new types_2.NetworkError("INVALID_TOKEN", "Missing or invalid Authorization header");
         }
         return auth.substring(7);
     }
+    /** Map domain errors to HTTP status codes; unknown errors become 500. */
     handleRequestError(error, res) {
         if (error instanceof validation_1.ValidationError) {
             res.status(400).json({ error: error.message });
@@ -1186,6 +1352,11 @@ class MindooDBServer {
                 return 500;
         }
     }
+    /**
+     * Express error handler (4-arg signature). Handles body-parser errors
+     * (413 entity too large, 400 parse failed) with structured JSON responses;
+     * everything else is logged and returned as a generic 500.
+     */
     errorHandler(err, req, res, next) {
         const parserError = err;
         const status = parserError.statusCode ?? parserError.status;
@@ -1221,6 +1392,9 @@ class MindooDBServer {
         res.status(500).json({ error: "Internal server error" });
     }
     // ==================== Serialization ====================
+    // Entries are stored with binary fields (Uint8Array) internally but
+    // transmitted as base64 strings over JSON. These methods handle the
+    // conversion in both directions.
     serializeEntryMetadata(metadata) {
         return {
             entryType: metadata.entryType,