mindoodb 0.0.10 → 0.0.12

package/dist/node/server/MindooDBServer.js

@@ -51,7 +51,7 @@ 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"));
@@ -65,8 +65,19 @@ 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) {
@@ -91,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);
@@ -100,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);
@@ -127,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);
@@ -136,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();
@@ -173,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) {
@@ -191,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");
@@ -204,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) {
@@ -256,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}`);
@@ -271,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 ====================
@@ -329,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) => {
@@ -354,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();
@@ -725,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)) {
@@ -757,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,
@@ -776,8 +841,9 @@ 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));
+        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));
@@ -799,12 +865,83 @@ class MindooDBServer {
         }
         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");
@@ -814,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;
@@ -990,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 {
@@ -1153,6 +1299,11 @@ 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") {
@@ -1170,6 +1321,7 @@ class MindooDBServer {
         }
         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 });
@@ -1200,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;
@@ -1235,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,