boltstore 0.5.1 → 0.6.0

package/dist/logger.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Structured JSON logger with levels, request ID tracing, and asynchronous batched flushing.
+ *
+ * Logs are buffered in memory and flushed asynchronously on a short interval or when the
+ * buffer reaches a size threshold. This keeps the hot path non-blocking while still ensuring
+ * logs are written in order within each flush.
+ *
+ * @module boltstore/logger
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface LogEntry {
+    level: LogLevel;
+    message: string;
+    timestamp: string;
+    request_id?: string;
+    method?: string;
+    path?: string;
+    client_ip?: string;
+    user_agent?: string;
+    status?: number;
+    duration_ms?: number;
+    error?: string;
+    [key: string]: unknown;
+}
+/**
+ * Generate a unique request ID for tracing.
+ */
+export declare function generateRequestId(): string;
+/** Force an immediate flush of all buffered logs. */
+export declare function flushLogger(): Promise<void>;
+/** Stop the background flush timer. */
+export declare function stopLogger(): void;
+export declare const logger: {
+    debug(message: string, meta?: Partial<LogEntry>): void;
+    info(message: string, meta?: Partial<LogEntry>): void;
+    warn(message: string, meta?: Partial<LogEntry>): void;
+    error(message: string, meta?: Partial<LogEntry>): void;
+};
+export default logger;
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAuB3D,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAID;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C;AAgFD,qDAAqD;AACrD,wBAAgB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAE3C;AAED,uCAAuC;AACvC,wBAAgB,UAAU,IAAI,IAAI,CAKjC;AAED,eAAO,MAAM,MAAM;mBACF,MAAM,SAAS,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI;kBAIxC,MAAM,SAAS,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI;kBAIvC,MAAM,SAAS,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI;mBAItC,MAAM,SAAS,OAAO,CAAC,QAAQ,CAAC,GAAG,IAAI;CAGvD,CAAC;AAEF,eAAe,MAAM,CAAC"}

package/dist/logger.js

@@ -0,0 +1,147 @@
+/**
+ * Structured JSON logger with levels, request ID tracing, and asynchronous batched flushing.
+ *
+ * Logs are buffered in memory and flushed asynchronously on a short interval or when the
+ * buffer reaches a size threshold. This keeps the hot path non-blocking while still ensuring
+ * logs are written in order within each flush.
+ *
+ * @module boltstore/logger
+ */
+import { openSync, writeSync, closeSync } from "node:fs";
+const LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const LOG_LEVEL = (Bun.env.LOG_LEVEL || "info").toLowerCase();
+/** Output destination: "stderr" | "stdout" | a file path. */
+const LOG_OUTPUT = Bun.env.LOG_OUTPUT || "stderr";
+/** Maximum number of entries to buffer before flushing. */
+const LOG_BUFFER_LIMIT = Math.max(1, Math.min(1000, parseInt(Bun.env.LOG_BUFFER_LIMIT || "100", 10) || 100));
+/** Flush interval in milliseconds. */
+const LOG_FLUSH_MS = Math.max(10, parseInt(Bun.env.LOG_FLUSH_MS || "100", 10) || 100);
+/** Optional sampling rate (0-1) applied to info-level logs. Error/warn are always logged. */
+const LOG_SAMPLE_RATE = Math.max(0, Math.min(1, parseFloat(Bun.env.LOG_SAMPLE_RATE || "1")));
+let requestCounter = 0;
+/**
+ * Generate a unique request ID for tracing.
+ */
+export function generateRequestId() {
+    requestCounter++;
+    const random = new Uint8Array(6);
+    crypto.getRandomValues(random);
+    const rnd = Buffer.from(random).toString("base64url").replace(/=+$/, "");
+    return `req-${Date.now()}-${requestCounter}-${rnd}`;
+}
+// ---------------------------------------------------------------------------
+// Async batched log writer
+// ---------------------------------------------------------------------------
+let logBuffer = [];
+let flushTimer = null;
+let flushPromise = null;
+function shouldDrop(level) {
+    if (level === "error" || level === "warn")
+        return false;
+    if (level === "info" && LOG_SAMPLE_RATE >= 1)
+        return false;
+    if (level === "info" && Math.random() > LOG_SAMPLE_RATE)
+        return true;
+    return false;
+}
+function writeEntries(entries) {
+    if (entries.length === 0)
+        return;
+    const chunk = entries.map((e) => JSON.stringify(e)).join("\n") + "\n";
+    try {
+        if (LOG_OUTPUT === "stdout") {
+            process.stdout.write(chunk);
+        }
+        else if (LOG_OUTPUT === "stderr") {
+            process.stderr.write(chunk);
+        }
+        else {
+            const fd = openSync(LOG_OUTPUT, "a");
+            try {
+                writeSync(fd, chunk);
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+    }
+    catch {
+        // Logging failures must not break the request.
+    }
+}
+async function flushLogs() {
+    if (flushPromise)
+        return flushPromise;
+    const batch = logBuffer;
+    logBuffer = [];
+    if (batch.length === 0)
+        return;
+    flushPromise = new Promise((resolve) => {
+        // Defer actual I/O to next tick to avoid blocking the event loop.
+        setTimeout(() => {
+            writeEntries(batch);
+            flushPromise = null;
+            resolve();
+        }, 0);
+    });
+    return flushPromise;
+}
+function scheduleFlush() {
+    if (!flushTimer) {
+        flushTimer = setInterval(() => {
+            flushLogs();
+        }, LOG_FLUSH_MS);
+        // Ensure the timer does not keep the process alive if it's the only remaining work.
+        if (typeof flushTimer.unref === "function")
+            flushTimer.unref();
+    }
+}
+/**
+ * Buffer a structured JSON log entry for asynchronous batched flushing.
+ */
+function writeLog(entry) {
+    if (LEVEL_PRIORITY[entry.level] < LEVEL_PRIORITY[LOG_LEVEL]) {
+        return;
+    }
+    if (shouldDrop(entry.level))
+        return;
+    logBuffer.push(entry);
+    if (logBuffer.length >= LOG_BUFFER_LIMIT) {
+        flushLogs();
+    }
+    else {
+        scheduleFlush();
+    }
+}
+/** Force an immediate flush of all buffered logs. */
+export function flushLogger() {
+    return flushLogs();
+}
+/** Stop the background flush timer. */
+export function stopLogger() {
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+}
+export const logger = {
+    debug(message, meta) {
+        writeLog({ level: "debug", message, timestamp: new Date().toISOString(), ...meta });
+    },
+    info(message, meta) {
+        writeLog({ level: "info", message, timestamp: new Date().toISOString(), ...meta });
+    },
+    warn(message, meta) {
+        writeLog({ level: "warn", message, timestamp: new Date().toISOString(), ...meta });
+    },
+    error(message, meta) {
+        writeLog({ level: "error", message, timestamp: new Date().toISOString(), ...meta });
+    },
+};
+export default logger;
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/middleware/auth.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Authentication/authorization middleware for Boltstore.
+ *
+ * Extracts a Bearer JWT token or an API key secret from the incoming request,
+ * verifies it against the database, and returns an auth context. Admin-only
+ * routes must additionally ensure the principal has role "admin" (or a valid
+ * API key with admin-scoped permissions).
+ *
+ * @module boltstore/middleware/auth
+ */
+import { DatabaseManager } from "../db/manager";
+import { type AuthConfig } from "../auth";
+export { type AuthConfig } from "../auth";
+import { type ApiKeyContext } from "../admin/api-keys";
+/** Authenticated principal returned by the middleware. */
+export interface AuthContext {
+    /** User ID (JWT) or API key ID (API key). */
+    principalId: string;
+    /** Email when authenticated via JWT. */
+    email?: string;
+    /** Role when authenticated via JWT. */
+    role?: "user" | "admin";
+    /** API key context when authenticated via API key. */
+    apiKey?: ApiKeyContext;
+    /** True if the principal was resolved from an API key. */
+    isApiKey: boolean;
+}
+/** Result of authentication: context on success, Response on failure. */
+export type AuthResult = AuthContext | Response;
+/**
+ * Authenticate the request against the given database.
+ *
+ * Returns an `AuthContext` on success or a 401/403 Response on failure.
+ */
+export declare function authenticateRequest(request: Request, manager: DatabaseManager, database: string, authConfig: AuthConfig): Promise<AuthResult>;
+/**
+ * Require an authenticated admin principal.
+ *
+ * JWT users must have role "admin". API keys are not allowed for admin
+ * routes unless the key explicitly includes the "admin" operation.
+ */
+export declare function requireAdmin(auth: AuthContext): Response | null;
+//# sourceMappingURL=auth.d.ts.map

package/dist/middleware/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAEL,KAAK,UAAU,EAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,EAAgB,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAErE,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,sDAAsD;IACtD,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,QAAQ,CAAC;AAoBhD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,eAAe,EACxB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,UAAU,GACrB,OAAO,CAAC,UAAU,CAAC,CA4CrB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,QAAQ,GAAG,IAAI,CAoB/D"}

package/dist/middleware/auth.js

@@ -0,0 +1,87 @@
+/**
+ * Authentication/authorization middleware for Boltstore.
+ *
+ * Extracts a Bearer JWT token or an API key secret from the incoming request,
+ * verifies it against the database, and returns an auth context. Admin-only
+ * routes must additionally ensure the principal has role "admin" (or a valid
+ * API key with admin-scoped permissions).
+ *
+ * @module boltstore/middleware/auth
+ */
+import { verifyAccessToken, } from "../auth";
+import { verifyApiKey } from "../admin/api-keys";
+/** Extract a Bearer token or API key secret from request headers. */
+function extractCredentials(request) {
+    const auth = request.headers.get("Authorization");
+    if (auth?.startsWith("Bearer ")) {
+        const value = auth.slice(7).trim();
+        // API keys always start with "blt_"
+        if (value.startsWith("blt_")) {
+            return { apiKey: value };
+        }
+        return { token: value };
+    }
+    const apiKey = request.headers.get("X-API-Key") || request.headers.get("x-api-key");
+    if (apiKey)
+        return { apiKey: apiKey.trim() };
+    return {};
+}
+/**
+ * Authenticate the request against the given database.
+ *
+ * Returns an `AuthContext` on success or a 401/403 Response on failure.
+ */
+export async function authenticateRequest(request, manager, database, authConfig) {
+    const { token, apiKey } = extractCredentials(request);
+    if (!token && !apiKey) {
+        return new Response(JSON.stringify({ error: { code: "UNAUTHORIZED", message: "Authentication required." } }), { status: 401, headers: { "Content-Type": "application/json" } });
+    }
+    const pool = database === "_system" ? manager.getMetaPool() : manager.get(database);
+    if (apiKey) {
+        try {
+            const ctx = await verifyApiKey(pool, apiKey);
+            return {
+                principalId: ctx.keyId,
+                apiKey: ctx,
+                isApiKey: true,
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : "Invalid API key";
+            return new Response(JSON.stringify({ error: { code: "UNAUTHORIZED", message } }), { status: 401, headers: { "Content-Type": "application/json" } });
+        }
+    }
+    try {
+        const ctx = verifyAccessToken(pool, token, authConfig);
+        return {
+            principalId: ctx.userId,
+            email: ctx.email,
+            role: ctx.role,
+            isApiKey: false,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : "Invalid token";
+        return new Response(JSON.stringify({ error: { code: "UNAUTHORIZED", message } }), { status: 401, headers: { "Content-Type": "application/json" } });
+    }
+}
+/**
+ * Require an authenticated admin principal.
+ *
+ * JWT users must have role "admin". API keys are not allowed for admin
+ * routes unless the key explicitly includes the "admin" operation.
+ */
+export function requireAdmin(auth) {
+    if (auth.isApiKey) {
+        const ops = auth.apiKey?.permissions.operations ?? [];
+        if (!ops.includes("admin")) {
+            return new Response(JSON.stringify({ error: { code: "FORBIDDEN", message: "Admin access required." } }), { status: 403, headers: { "Content-Type": "application/json" } });
+        }
+        return null;
+    }
+    if (auth.role !== "admin") {
+        return new Response(JSON.stringify({ error: { code: "FORBIDDEN", message: "Admin access required." } }), { status: 403, headers: { "Content-Type": "application/json" } });
+    }
+    return null;
+}
+//# sourceMappingURL=auth.js.map

package/dist/middleware/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"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"}

package/dist/middleware/cors.d.ts

@@ -0,0 +1,28 @@
+/**
+ * CORS middleware — handles cross-origin requests.
+ *
+ * Configurable via environment variables:
+ * - CORS_ORIGINS: comma-separated list of allowed origins (default: "*")
+ * - CORS_METHODS: comma-separated list of allowed methods (default: "GET,POST,PATCH,DELETE,OPTIONS")
+ * - CORS_HEADERS: comma-separated list of allowed headers (default: "Content-Type,Authorization")
+ *
+ * @module boltstore/middleware/cors
+ */
+export interface CorsConfig {
+    origins: string[];
+    methods: string[];
+    headers: string[];
+}
+declare const defaultConfig: CorsConfig;
+/**
+ * Apply CORS headers to a Response object.
+ * Returns the response with CORS headers set, or a 204 for preflight requests.
+ */
+export declare function applyCors(response: Response, requestOrigin: string | null, config?: CorsConfig): Response;
+/**
+ * Handle an OPTIONS preflight request.
+ * Returns a 204 No Content response with appropriate CORS headers.
+ */
+export declare function handlePreflight(requestOrigin: string | null, config?: CorsConfig): Response;
+export { defaultConfig };
+//# sourceMappingURL=cors.d.ts.map

package/dist/middleware/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/middleware/cors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,QAAA,MAAM,aAAa,EAAE,UAMpB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,SAAS,CACvB,QAAQ,EAAE,QAAQ,EAClB,aAAa,EAAE,MAAM,GAAG,IAAI,EAC5B,MAAM,GAAE,UAA0B,GACjC,QAAQ,CAwBV;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,EAAE,MAAM,GAAE,UAA0B,GAAG,QAAQ,CAsB1G;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/middleware/cors.js

@@ -0,0 +1,71 @@
+/**
+ * CORS middleware — handles cross-origin requests.
+ *
+ * Configurable via environment variables:
+ * - CORS_ORIGINS: comma-separated list of allowed origins (default: "*")
+ * - CORS_METHODS: comma-separated list of allowed methods (default: "GET,POST,PATCH,DELETE,OPTIONS")
+ * - CORS_HEADERS: comma-separated list of allowed headers (default: "Content-Type,Authorization")
+ *
+ * @module boltstore/middleware/cors
+ */
+const defaultConfig = {
+    origins: Bun.env.CORS_ORIGINS
+        ? Bun.env.CORS_ORIGINS.split(",").map((s) => s.trim()).filter(Boolean)
+        : ["*"],
+    methods: (Bun.env.CORS_METHODS || "GET,POST,PATCH,DELETE,OPTIONS").split(",").map((s) => s.trim()),
+    headers: (Bun.env.CORS_HEADERS || "Content-Type,Authorization").split(",").map((s) => s.trim()),
+};
+/**
+ * Apply CORS headers to a Response object.
+ * Returns the response with CORS headers set, or a 204 for preflight requests.
+ */
+export function applyCors(response, requestOrigin, config = defaultConfig) {
+    let origin = null;
+    if (config.origins.includes("*")) {
+        // When wildcard is explicitly configured, send wildcard (do not echo).
+        origin = "*";
+    }
+    else if (requestOrigin && config.origins.includes(requestOrigin)) {
+        origin = requestOrigin;
+    }
+    // No matching origin — return response unchanged.
+    if (!origin)
+        return response;
+    const headers = new Headers(response.headers);
+    headers.set("Access-Control-Allow-Origin", origin);
+    headers.set("Access-Control-Allow-Methods", config.methods.join(", "));
+    headers.set("Access-Control-Allow-Headers", config.headers.join(", "));
+    headers.set("Access-Control-Max-Age", "86400");
+    return new Response(response.body, {
+        status: response.status,
+        statusText: response.statusText,
+        headers,
+    });
+}
+/**
+ * Handle an OPTIONS preflight request.
+ * Returns a 204 No Content response with appropriate CORS headers.
+ */
+export function handlePreflight(requestOrigin, config = defaultConfig) {
+    let origin = null;
+    if (config.origins.includes("*")) {
+        origin = "*";
+    }
+    else if (requestOrigin && config.origins.includes(requestOrigin)) {
+        origin = requestOrigin;
+    }
+    if (!origin) {
+        return new Response(null, { status: 204 });
+    }
+    return new Response(null, {
+        status: 204,
+        headers: {
+            "Access-Control-Allow-Origin": origin,
+            "Access-Control-Allow-Methods": config.methods.join(", "),
+            "Access-Control-Allow-Headers": config.headers.join(", "),
+            "Access-Control-Max-Age": "86400",
+        },
+    });
+}
+export { defaultConfig };
+//# sourceMappingURL=cors.js.map

package/dist/middleware/cors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.js","sourceRoot":"","sources":["../../src/middleware/cors.ts"],"names":[],"mappings":"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"}

package/dist/middleware/proxy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Trusted proxy helper for Boltstore.
+ *
+ * @module boltstore/middleware/proxy
+ */
+/** Check whether the immediate connection IP is a trusted proxy. */
+export declare function isTrustedProxy(remoteAddress: string, trusted: string[]): boolean;
+/** Resolve the client IP from request headers, respecting trusted proxies. */
+export declare function resolveClientIp(request: Request, trustedProxies: string[], remoteAddress?: string): string;
+//# sourceMappingURL=proxy.d.ts.map

package/dist/middleware/proxy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../src/middleware/proxy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oEAAoE;AACpE,wBAAgB,cAAc,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAIhF;AAED,8EAA8E;AAC9E,wBAAgB,eAAe,CAC7B,OAAO,EAAE,OAAO,EAChB,cAAc,EAAE,MAAM,EAAE,EACxB,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CAgBR"}

package/dist/middleware/proxy.js

@@ -0,0 +1,31 @@
+/**
+ * Trusted proxy helper for Boltstore.
+ *
+ * @module boltstore/middleware/proxy
+ */
+/** Check whether the immediate connection IP is a trusted proxy. */
+export function isTrustedProxy(remoteAddress, trusted) {
+    if (trusted.length === 0)
+        return false;
+    if (trusted.includes("*"))
+        return true;
+    return trusted.includes(remoteAddress) || trusted.includes("127.0.0.1") && remoteAddress === "127.0.0.1";
+}
+/** Resolve the client IP from request headers, respecting trusted proxies. */
+export function resolveClientIp(request, trustedProxies, remoteAddress) {
+    const remote = remoteAddress || "127.0.0.1";
+    if (!isTrustedProxy(remote, trustedProxies)) {
+        return remote;
+    }
+    const forwarded = request.headers.get("X-Forwarded-For");
+    if (forwarded) {
+        const first = forwarded.split(",")[0]?.trim();
+        if (first)
+            return first;
+    }
+    const realIp = request.headers.get("X-Real-IP");
+    if (realIp)
+        return realIp.trim();
+    return remote;
+}
+//# sourceMappingURL=proxy.js.map

package/dist/middleware/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../src/middleware/proxy.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,oEAAoE;AACpE,MAAM,UAAU,cAAc,CAAC,aAAqB,EAAE,OAAiB;IACrE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,OAAO,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,aAAa,KAAK,WAAW,CAAC;AAC3G,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAC7B,OAAgB,EAChB,cAAwB,EACxB,aAAsB;IAEtB,MAAM,MAAM,GAAG,aAAa,IAAI,WAAW,CAAC;IAC5C,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,CAAC;QAC5C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACzD,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QAC9C,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAChD,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IAEjC,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Rate limiting middleware for Boltstore.
+ *
+ * Uses a sliding-window counter approach with per-IP, per-endpoint,
+ * per-tier tracking. All state is in-memory (no SQLite dependency) for
+ * speed — resets on server restart.
+ *
+ * Three tiers:
+ * - **public**: Unauthenticated endpoints (health, login, register)
+ * - **auth**: Authenticated endpoints (CRUD, queries)
+ * - **admin**: Admin endpoints under `/api/admin/*`
+ *
+ * Configurable via `BoltstoreConfig.rateLimitPublic` and `rateLimitAuth`,
+ * or set explicitly in `ServerConfig.rateLimit`.
+ *
+ * @module boltstore/middleware/rate-limit
+ */
+export type RateLimitTier = "public" | "auth" | "admin";
+export interface RateLimitConfig {
+    /** Requests per window for public endpoints. Default: 100. */
+    public: number;
+    /** Requests per window for authenticated endpoints. Default: 1000. */
+    auth: number;
+    /** Requests per window for admin endpoints. Default: 500. */
+    admin: number;
+    /** Window size in seconds. Default: 60 (1 minute). */
+    windowSeconds: number;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    /** How many requests remain in this window. */
+    remaining: number;
+    /** Total limit for this tier. */
+    limit: number;
+    /** Unix timestamp (seconds) when the window resets. */
+    reset: number;
+    /** Seconds until the window resets (only set when rate-limited). */
+    retryAfter: number;
+}
+export declare const DEFAULT_RATE_LIMIT_CONFIG: RateLimitConfig;
+/**
+ * Stop the cleanup timer. Call during server shutdown.
+ */
+export declare function stopRateLimitCleanup(): void;
+/**
+ * Check if a request should be rate-limited.
+ *
+ * @param clientIp - The client's IP address (or "127.0.0.1" as fallback).
+ * @param pathname - The request path (used as part of the rate limit key).
+ * @param tier - The rate limit tier for this request.
+ * @param config - Rate limit configuration.
+ * @returns A result indicating whether the request is allowed.
+ */
+export declare function checkRateLimit(clientIp: string, pathname: string, tier: RateLimitTier, config: RateLimitConfig): RateLimitResult;
+/**
+ * Get the current rate limit status for a client without incrementing.
+ * Useful for informational endpoints.
+ */
+export declare function getRateLimitStatus(clientIp: string, pathname: string, tier: RateLimitTier, config: RateLimitConfig): RateLimitResult;
+/**
+ * Reset all rate limit counters. Useful for testing.
+ */
+export declare function resetRateLimits(): void;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,eAAO,MAAM,yBAAyB,EAAE,eAKvC,CAAC;AAsCF;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,eAAe,GACtB,eAAe,CAiCjB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,eAAe,GACtB,eAAe,CA4BjB;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}