@lastshotlabs/bunshot 0.0.27 → 0.1.0

package/dist/src/server.js

@@ -0,0 +1,469 @@
+import { validateServerConfig } from './framework/config/schema';
+import { log } from './framework/lib/logger';
+import { routePatternCanMatchLiteral } from './framework/lib/sseCollision';
+import { cleanupSocket, handleRoomActions } from './framework/lib/ws';
+import { deregisterSocket, handlePong, registerSocket, startHeartbeat, stopHeartbeat, } from './framework/lib/wsHeartbeat';
+import { wsEndpointKey } from './framework/lib/wsNamespace';
+import { trackSocket, untrackSocket } from './framework/lib/wsPresence';
+// ensureClientSafeEventKey is now an instance method on BunshotEventBus
+import { createSseRegistry, createSseUpgradeHandler } from './framework/sse/index';
+import { createWsUpgradeHandler } from './framework/ws/index';
+import { disconnectMongo } from './lib/mongo';
+import { disconnectRedis } from './lib/redis';
+import { createApp } from './app';
+// ---------------------------------------------------------------------------
+// Server → Context mapping (for testing / tooling access)
+// ---------------------------------------------------------------------------
+const SERVER_CONTEXT_SYMBOL = Symbol.for('bunshot.serverContext');
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 30_000;
+const SHUTDOWN_REGISTRY_SYMBOL = Symbol.for('bunshot.shutdownRegistry');
+function getShutdownRegistry() {
+    const proc = process;
+    let registry = proc[SHUTDOWN_REGISTRY_SYMBOL];
+    if (!registry) {
+        registry = { callbacks: new Map(), listeners: null };
+        proc[SHUTDOWN_REGISTRY_SYMBOL] = registry;
+    }
+    return registry;
+}
+function ensureProcessShutdownListeners() {
+    const registry = getShutdownRegistry();
+    if (registry.listeners)
+        return;
+    let dispatching = false;
+    const dispatch = (signal) => {
+        if (dispatching)
+            return;
+        dispatching = true;
+        const forceExit = setTimeout(() => {
+            console.error(`[shutdown] Timed out after ${DEFAULT_SHUTDOWN_TIMEOUT_MS}ms during ${signal}; forcing exit`);
+            process.exit(1);
+        }, DEFAULT_SHUTDOWN_TIMEOUT_MS);
+        forceExit.unref?.();
+        const cbs = [...registry.callbacks.values()];
+        void Promise.allSettled(cbs.map(cb => cb(signal))).then(results => {
+            clearTimeout(forceExit);
+            const exitCode = results.some(r => r.status === 'rejected' || (r.status === 'fulfilled' && r.value !== 0))
+                ? 1
+                : 0;
+            console.log(`[shutdown] All servers completed with exit code ${exitCode}`);
+            process.exit(exitCode);
+        });
+    };
+    const sigterm = () => dispatch('SIGTERM');
+    const sigint = () => dispatch('SIGINT');
+    process.on('SIGTERM', sigterm);
+    process.on('SIGINT', sigint);
+    registry.listeners = { sigterm, sigint };
+}
+function removeProcessShutdownListeners() {
+    const registry = getShutdownRegistry();
+    const { listeners } = registry;
+    if (!listeners)
+        return;
+    process.off('SIGTERM', listeners.sigterm);
+    process.off('SIGINT', listeners.sigint);
+    registry.listeners = null;
+}
+/**
+ * Retrieve the BunshotContext associated with a server.
+ * Available after createServer() completes. Used by test helpers.
+ */
+export function getServerContext(server) {
+    return (server[SERVER_CONTEXT_SYMBOL] ?? null);
+}
+// ---------------------------------------------------------------------------
+// createServer
+// ---------------------------------------------------------------------------
+export const createServer = async (config) => {
+    const serverOwnerId = crypto.randomUUID();
+    // Validate the full server config shape — catches typos and type errors.
+    // createApp separately validates its own subset (app-level keys only).
+    const { warnings } = validateServerConfig(config);
+    for (const w of warnings)
+        console.warn(w);
+    // Startup validation — unix is mutually exclusive with port/hostname/tls
+    if (config.unix && config.port !== undefined)
+        throw new Error('[bunshot] unix and port are mutually exclusive');
+    if (config.unix && config.hostname)
+        throw new Error('[bunshot] unix and hostname are mutually exclusive');
+    if (config.unix && config.tls)
+        throw new Error('[bunshot] unix sockets do not support TLS');
+    // Extract only app-level config keys — createApp validates its own shape and
+    // will warn about unknown keys. Passing the full CreateServerConfig would
+    // trigger false warnings for server-only keys like port, sse, ws, etc.
+    const { port: _port, hostname: _hostname, unix: _unix, tls: _tls, workersDir: _workersDir, enableWorkers: _enableWorkers, ws: _ws, sse: _sse, maxRequestBodySize: _maxRequestBodySize, ...appConfig } = config;
+    const { app, ctx } = await createApp(appConfig);
+    const port = Number(process.env.PORT ?? config.port ?? 3000);
+    const { workersDir, enableWorkers = true, ws: wsConfig } = config;
+    const sseRegistry = createSseRegistry();
+    const sseBusListeners = [];
+    if (config.sse) {
+        // Read bus from context (replaces appMeta WeakMap)
+        const bus = ctx.bus;
+        const { endpoints: sseEndpoints } = config.sse;
+        const wsEndpointPaths = new Set(Object.keys(config.ws?.endpoints ?? {}));
+        const honoGetPatterns = app.routes
+            .filter(r => r.method === 'GET')
+            .map(r => r.path);
+        for (const [ssePath, epConfig] of Object.entries(sseEndpoints)) {
+            // 1. Literal path — no :params or wildcards in sse.endpoints keys
+            if (ssePath.includes(':') || ssePath.includes('*'))
+                throw new Error(`[sse] "${ssePath}" must be a literal path — no :params or * wildcards`);
+            // 2. Prefix enforcement
+            if (!ssePath.startsWith('/__sse/'))
+                throw new Error(`[sse] "${ssePath}" must be under the /__sse/ prefix`);
+            // 3. WS path collision
+            if (wsEndpointPaths.has(ssePath))
+                throw new Error(`[sse] "${ssePath}" collides with an existing WS endpoint`);
+            // 4. Hono GET route collision (pattern-aware — existing routes may use :param or *)
+            for (const pattern of honoGetPatterns) {
+                if (routePatternCanMatchLiteral(pattern, ssePath))
+                    throw new Error(`[sse] "${ssePath}" collides with Hono GET route "${pattern}"`);
+            }
+            // 5. Per-endpoint bus subscriptions (once per event key, not per client)
+            const heartbeatMs = epConfig.heartbeat === undefined ? 30_000 : epConfig.heartbeat;
+            const upgradeHandler = epConfig.upgrade ?? createSseUpgradeHandler(ssePath, ctx.userResolver);
+            for (const rawKey of epConfig.events) {
+                const key = bus.ensureClientSafeEventKey(rawKey, `sse.endpoints["${ssePath}"].events`);
+                const listener = (payload) => {
+                    sseRegistry.fanout(ssePath, key, payload, epConfig.filter);
+                };
+                bus.on(key, listener);
+                sseBusListeners.push({ key, listener });
+            }
+            // 6. Mount Hono GET route
+            app.get(ssePath, async (c) => {
+                const result = await upgradeHandler(c.req.raw);
+                if (result instanceof Response)
+                    return result;
+                const stream = sseRegistry.createClientStream(ssePath, result, heartbeatMs);
+                c.header('Content-Type', 'text/event-stream');
+                c.header('Cache-Control', 'no-cache');
+                c.header('Connection', 'keep-alive');
+                c.header('X-Accel-Buffering', 'no');
+                return c.newResponse(stream);
+            });
+        }
+    }
+    // Compute maxRequestBodySize: explicit config wins, else derive from upload config
+    let maxRequestBodySize = config.maxRequestBodySize;
+    if (maxRequestBodySize === undefined && config.upload) {
+        const maxFileSize = config.upload.maxFileSize ?? 10 * 1024 * 1024;
+        const maxFiles = config.upload.maxFiles ?? 10;
+        maxRequestBodySize = maxFileSize * maxFiles;
+    }
+    let server;
+    if (wsConfig) {
+        const { endpoints, transport: wsTransport, idleTimeout, backpressureLimit, closeOnBackpressureLimit, perMessageDeflate, publishToSelf, } = wsConfig;
+        // Compute presence flag once — true if any endpoint enables presence
+        const presenceEnabled = Object.values(endpoints).some(ep => !!ep.presence);
+        const wsState = {
+            server: null,
+            transport: wsTransport ?? null,
+            instanceId: crypto.randomUUID(),
+            presenceEnabled,
+            roomRegistry: new Map(),
+            heartbeatSockets: new Map(),
+            heartbeatEndpointConfigs: new Map(),
+            heartbeatTimer: null,
+            socketUsers: new Map(),
+            roomPresence: new Map(),
+        };
+        // Configure per-endpoint side effects
+        for (const [, ep] of Object.entries(endpoints)) {
+            if (ep.persistence?.defaults) {
+                ctx.persistence.setDefaults(ep.persistence.defaults);
+            }
+        }
+        const wsHandler = {
+            async open(socket) {
+                const ep = endpoints[socket.data.endpoint];
+                if (ep?.heartbeat)
+                    registerSocket(wsState, socket, socket.data.id, socket.data.endpoint);
+                if (ep?.presence)
+                    trackSocket(wsState, socket.data.id, socket.data.userId);
+                socket.send(JSON.stringify({ event: 'connected', id: socket.data.id }));
+                if (ep?.on?.open) {
+                    try {
+                        await ep.on.open(socket);
+                    }
+                    catch (e) {
+                        console.error(`[ws:hook] ${socket.data.endpoint} open error`, e);
+                    }
+                }
+            },
+            async message(socket, message) {
+                const ep = endpoints[socket.data.endpoint];
+                const maxSize = ep?.maxMessageSize ?? 65_536;
+                const size = typeof message === 'string' ? message.length : message.byteLength;
+                if (size > maxSize) {
+                    socket.close(1009, 'Message too large');
+                    return;
+                }
+                if (!(await handleRoomActions(wsState, socket, message, ep?.onRoomSubscribe))) {
+                    if (ep?.on?.message) {
+                        try {
+                            await ep.on.message(socket, message);
+                        }
+                        catch (e) {
+                            console.error(`[ws:hook] ${socket.data.endpoint} message error`, e);
+                        }
+                    }
+                }
+            },
+            async close(socket, code, reason) {
+                const ep = endpoints[socket.data.endpoint];
+                if (ep?.heartbeat)
+                    deregisterSocket(wsState, socket.data.id);
+                if (ep?.presence)
+                    untrackSocket(wsState, socket.data.id);
+                cleanupSocket(wsState, socket);
+                if (ep?.on?.close) {
+                    try {
+                        await ep.on.close(socket, code, reason);
+                    }
+                    catch (e) {
+                        console.error(`[ws:hook] ${socket.data.endpoint} close error`, e);
+                    }
+                }
+            },
+            pong(socket) {
+                handlePong(wsState, socket.data.id);
+            },
+            drain(socket) {
+                void endpoints[socket.data.endpoint]?.on?.drain?.(socket);
+            },
+        };
+        // One upgrade route per endpoint
+        const routes = Object.fromEntries(Object.entries(endpoints).map(([path, ep]) => [
+            path,
+            (req) => ep.upgrade
+                ? ep.upgrade(req, server)
+                : createWsUpgradeHandler(server, path, ctx.userResolver)(req),
+        ]));
+        server = Bun.serve({
+            ...(config.unix
+                ? { unix: config.unix }
+                : { port, ...(config.hostname ? { hostname: config.hostname } : {}) }),
+            ...(config.tls ? { tls: config.tls } : {}),
+            ...(maxRequestBodySize !== undefined ? { maxRequestBodySize } : {}),
+            routes,
+            fetch: app.fetch,
+            websocket: {
+                ...wsHandler,
+                ...(idleTimeout !== undefined ? { idleTimeout } : {}),
+                ...(backpressureLimit !== undefined ? { backpressureLimit } : {}),
+                ...(closeOnBackpressureLimit !== undefined ? { closeOnBackpressureLimit } : {}),
+                ...(perMessageDeflate !== undefined ? { perMessageDeflate } : {}),
+                ...(publishToSelf !== undefined ? { publishToSelf } : {}),
+            },
+            error(err) {
+                console.error(err);
+                return Response.json({ error: 'Internal Server Error' }, { status: 500 });
+            },
+        });
+        wsState.server = server;
+        // Connect cross-instance transport
+        if (wsTransport) {
+            const localId = wsState.instanceId;
+            await wsTransport.connect((endpoint, room, msg, origin) => {
+                if (origin === localId)
+                    return;
+                server.publish(wsEndpointKey(endpoint, room), msg);
+            });
+        }
+        // Heartbeat — collect per-endpoint configs
+        const heartbeatConfigs = {};
+        for (const [path, ep] of Object.entries(endpoints)) {
+            if (ep.heartbeat)
+                heartbeatConfigs[path] = ep.heartbeat;
+        }
+        if (Object.keys(heartbeatConfigs).length > 0) {
+            startHeartbeat(wsState, heartbeatConfigs);
+        }
+        // Populate WS state on the BunshotContext so instance-scoped consumers
+        // can read it via getContext(app).ws instead of module-level singletons.
+        // presenceEnabled already computed above
+        ctx.ws = wsState;
+    }
+    else {
+        // No WS config — plain HTTP server
+        server = Bun.serve({
+            ...(config.unix
+                ? { unix: config.unix }
+                : { port, ...(config.hostname ? { hostname: config.hostname } : {}) }),
+            ...(config.tls ? { tls: config.tls } : {}),
+            ...(maxRequestBodySize !== undefined ? { maxRequestBodySize } : {}),
+            fetch: app.fetch,
+            error(err) {
+                console.error(err);
+                return Response.json({ error: 'Internal Server Error' }, { status: 500 });
+            },
+        });
+    }
+    const releaseProcessShutdownOwnership = () => {
+        const registry = getShutdownRegistry();
+        registry.callbacks.delete(serverOwnerId);
+        if (registry.callbacks.size === 0) {
+            removeProcessShutdownListeners();
+        }
+    };
+    const originalStop = server.stop.bind(server);
+    server.stop = (async (...args) => {
+        releaseProcessShutdownOwnership();
+        return originalStop(...args);
+    });
+    // Graceful shutdown — stop accepting new work, then tear down plugins/bus/db.
+    // Returns an exit code (0 = clean, 1 = errors). process.exit() is called by
+    // the dispatch layer after all registered servers have finished shutting down.
+    let shutdownPromise = null;
+    const gracefulShutdown = (signal) => {
+        if (shutdownPromise) {
+            console.warn(`[shutdown] ${signal} received while shutdown is already in progress`);
+            return shutdownPromise;
+        }
+        shutdownPromise = (async () => {
+            console.log(`[shutdown] Received ${signal}; starting graceful shutdown`);
+            let exitCode = 0;
+            try {
+                await server.stop();
+                if (ctx.ws)
+                    stopHeartbeat(ctx.ws);
+                // Plugin teardown runs BEFORE WS transport disconnect so plugins can
+                // still publish to rooms (e.g. "user X disconnected" broadcasts).
+                const bunshotPlugins = [...ctx.plugins];
+                const bunshotBus = ctx.bus;
+                bunshotBus.emit('app:shutdown', { signal });
+                const teardownResults = await Promise.allSettled(bunshotPlugins.map(p => p.teardown?.()));
+                for (const [i, result] of teardownResults.entries()) {
+                    if (result.status === 'rejected') {
+                        console.error(`[shutdown] Plugin teardown error (plugin index ${i}):`, result.reason);
+                        exitCode = 1;
+                    }
+                }
+                // SSE teardown — unsubscribe listeners and close streams BEFORE the bus
+                // shuts down, so cleanup runs against a live bus.
+                for (const { key, listener } of sseBusListeners)
+                    bunshotBus.off(key, listener);
+                sseRegistry.closeAll();
+                await bunshotBus.shutdown?.();
+                // WS transport disconnect — after plugins and SSE are torn down,
+                // no more consumers need the transport.
+                const wsTransport = wsConfig?.transport;
+                if (wsTransport) {
+                    try {
+                        await wsTransport.disconnect();
+                    }
+                    catch (e) {
+                        console.error('[ws-transport] disconnect error:', e);
+                        exitCode = 1;
+                    }
+                    if (ctx.ws)
+                        ctx.ws.transport = null;
+                }
+                // Database disconnects — close persistent connections last, after all consumers are torn down
+                const dbConfig = config.db ?? {};
+                const enableRedis = dbConfig.redis ?? true;
+                const mongoMode = dbConfig.mongo ?? 'single';
+                if (enableRedis && ctx.redis) {
+                    try {
+                        await disconnectRedis(ctx.redis);
+                    }
+                    catch (e) {
+                        console.error('[shutdown] Redis disconnect error:', e);
+                        exitCode = 1;
+                    }
+                }
+                if (mongoMode !== false && ctx.mongo) {
+                    try {
+                        await disconnectMongo(ctx.mongo.auth, ctx.mongo.app);
+                    }
+                    catch (e) {
+                        console.error('[shutdown] MongoDB disconnect error:', e);
+                        exitCode = 1;
+                    }
+                }
+            }
+            catch (e) {
+                console.error(`[shutdown] Unhandled shutdown error during ${signal}:`, e);
+                exitCode = 1;
+            }
+            console.log(`[shutdown] Server ${serverOwnerId.slice(0, 8)} completed with exit code ${exitCode}`);
+            return exitCode;
+        })();
+        return shutdownPromise;
+    };
+    // Register this server's shutdown callback. Multiple concurrent servers are
+    // supported — each gets its own entry, all invoked in parallel on signal.
+    getShutdownRegistry().callbacks.set(serverOwnerId, signal => gracefulShutdown(signal));
+    ensureProcessShutdownListeners();
+    if (enableWorkers && workersDir) {
+        const glob = new Bun.Glob('**/*.ts');
+        const currentNames = new Set();
+        // Build a QueueFactory from resolved secrets so worker files receive
+        // properly-credentialed infrastructure rather than reading process.env.
+        let queueFactory = null;
+        const redisHost = ctx.resolvedSecrets.redisHost;
+        if (redisHost) {
+            try {
+                const { createQueueFactory } = await import('./lib/queue');
+                queueFactory = createQueueFactory({
+                    host: redisHost,
+                    user: ctx.resolvedSecrets.redisUser,
+                    password: ctx.resolvedSecrets.redisPassword,
+                });
+            }
+            catch {
+                /* bullmq not installed — queue workers will fail at import time */
+            }
+        }
+        // Load scheduler names saved by the previous deployment before importing
+        // workers, so we can diff current vs. previous after discovery.
+        const previousNames = await ctx.persistence.cronRegistry.getAll();
+        for await (const file of glob.scan({ cwd: workersDir })) {
+            const mod = await import(`${workersDir}/${file}`);
+            if (typeof mod.default === 'function' && queueFactory) {
+                try {
+                    const names = await mod.default(queueFactory);
+                    if (Array.isArray(names)) {
+                        for (const name of names)
+                            currentNames.add(name);
+                    }
+                }
+                catch (e) {
+                    console.error(`[workers] error initialising worker ${file}:`, e);
+                }
+            }
+        }
+        // Persist current names for the next deployment's cleanup pass.
+        await ctx.persistence.cronRegistry.save(currentNames);
+        // Remove schedulers present in the previous deployment but absent from
+        // the current one. knownNames is the union so cleanupStaleSchedulers
+        // iterates everything it might need to remove.
+        if (queueFactory) {
+            const knownNames = new Set([...previousNames, ...currentNames]);
+            try {
+                await queueFactory.cleanupStaleSchedulers([...currentNames], knownNames);
+            }
+            catch {
+                /* best-effort — bullmq not installed or Redis unavailable */
+            }
+        }
+    }
+    // Store context on server for test/tooling access
+    Object.defineProperty(server, SERVER_CONTEXT_SYMBOL, {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value: ctx,
+    });
+    if (!config.unix) {
+        log(`[server] running at http://localhost:${server.port}`);
+        log(`[server] API docs at http://localhost:${server.port}/docs`);
+    }
+    else {
+        log(`[server] running at unix:${config.unix}`);
+    }
+    return server;
+};

package/dist/src/shared/lib/HttpError.d.ts

@@ -0,0 +1 @@
+export { HttpError, ValidationError } from '../../../packages/bunshot-core/src/index.js';

package/dist/src/shared/lib/HttpError.js

@@ -0,0 +1,2 @@
+// Redirect to core so there's only one class definition — avoids instanceof mismatches
+export { HttpError, ValidationError } from '../../../packages/bunshot-core/src/index.js';

package/dist/src/shared/lib/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const COOKIE_TOKEN = "token";
+export declare const HEADER_USER_TOKEN = "x-user-token";
+export declare const COOKIE_REFRESH_TOKEN = "refresh_token";
+export declare const HEADER_REFRESH_TOKEN = "x-refresh-token";
+export declare const COOKIE_CSRF_TOKEN = "csrf_token";
+export declare const HEADER_CSRF_TOKEN = "x-csrf-token";
+export declare const HEADER_REQUEST_ID = "x-request-id";
+export declare const HEADER_IDEMPOTENCY_KEY = "idempotency-key";
+export declare const HEADER_SIGNATURE = "x-signature";
+export declare const HEADER_TIMESTAMP = "x-timestamp";

package/dist/src/shared/lib/crypto.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * Returns true if both strings are equal, false otherwise.
+ * Always compares the full length even on mismatch.
+ */
+export declare function timingSafeEqual(a: string, b: string): boolean;
+/**
+ * SHA-256 hash a string and return the hex digest.
+ * Centralized to avoid duplicate implementations across modules.
+ */
+export declare function sha256(input: string): string;
+/**
+ * Named alias for sha256 — use when hashing tokens for storage.
+ * The plaintext token is what gets sent to the client;
+ * the hash is what gets stored.
+ */
+export declare function hashToken(token: string): string;
+/**
+ * A data encryption key entry.
+ * keyId: short identifier used in the ciphertext envelope (e.g. "v1")
+ * key: 32-byte AES-256 key
+ */
+export interface DataEncryptionKey {
+    keyId: string;
+    key: Buffer;
+}
+/**
+ * Encrypt a plaintext value with AES-256-GCM.
+ * keyConfig: first entry is the active key, rest are for decryption-only rotation.
+ * Returns: "keyId.base64url(iv).base64url(ciphertext).base64url(tag)"
+ */
+export declare function encryptField(plaintext: string, keyConfig: DataEncryptionKey[]): Promise<string>;
+/**
+ * Decrypt a value encrypted by encryptField.
+ * keyConfig: all available keys (current + rotated).
+ * Returns: plaintext string, or throws if no matching key found.
+ */
+export declare function decryptField(ciphertext: string, keyConfig: DataEncryptionKey[]): Promise<string>;
+/**
+ * Detect whether a stored value looks like an encrypted ciphertext produced by encryptField.
+ * Format: "keyId.base64url(iv).base64url(ct).base64url(tag)" — exactly 4 dot-separated parts.
+ */
+export declare function isEncryptedField(value: string): boolean;

package/dist/src/shared/lib/crypto.js

@@ -0,0 +1,74 @@
+import { createHash, timingSafeEqual as nodeTimingSafeEqual, createCipheriv, createDecipheriv, randomBytes } from "crypto";
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ * Returns true if both strings are equal, false otherwise.
+ * Always compares the full length even on mismatch.
+ */
+export function timingSafeEqual(a, b) {
+    if (a.length !== b.length) {
+        // Compare against self to burn the same time, then return false
+        const buf = Buffer.from(a, "utf-8");
+        nodeTimingSafeEqual(buf, buf);
+        return false;
+    }
+    return nodeTimingSafeEqual(Buffer.from(a, "utf-8"), Buffer.from(b, "utf-8"));
+}
+/**
+ * SHA-256 hash a string and return the hex digest.
+ * Centralized to avoid duplicate implementations across modules.
+ */
+export function sha256(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+/**
+ * Named alias for sha256 — use when hashing tokens for storage.
+ * The plaintext token is what gets sent to the client;
+ * the hash is what gets stored.
+ */
+export function hashToken(token) {
+    return sha256(token);
+}
+/**
+ * Encrypt a plaintext value with AES-256-GCM.
+ * keyConfig: first entry is the active key, rest are for decryption-only rotation.
+ * Returns: "keyId.base64url(iv).base64url(ciphertext).base64url(tag)"
+ */
+export async function encryptField(plaintext, keyConfig) {
+    if (keyConfig.length === 0)
+        throw new Error("encryptField: no encryption keys configured");
+    const { keyId, key } = keyConfig[0];
+    const iv = randomBytes(12); // 96-bit IV for AES-GCM
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const encode = (buf) => buf.toString("base64url");
+    return `${keyId}.${encode(iv)}.${encode(encrypted)}.${encode(tag)}`;
+}
+/**
+ * Decrypt a value encrypted by encryptField.
+ * keyConfig: all available keys (current + rotated).
+ * Returns: plaintext string, or throws if no matching key found.
+ */
+export async function decryptField(ciphertext, keyConfig) {
+    const parts = ciphertext.split(".");
+    if (parts.length !== 4)
+        throw new Error("decryptField: invalid ciphertext format");
+    const [keyId, ivB64, ctB64, tagB64] = parts;
+    const keyEntry = keyConfig.find((k) => k.keyId === keyId);
+    if (!keyEntry)
+        throw new Error(`decryptField: no key found for keyId "${keyId}"`);
+    const iv = Buffer.from(ivB64, "base64url");
+    const ct = Buffer.from(ctB64, "base64url");
+    const tag = Buffer.from(tagB64, "base64url");
+    const decipher = createDecipheriv("aes-256-gcm", keyEntry.key, iv);
+    decipher.setAuthTag(tag);
+    const decrypted = Buffer.concat([decipher.update(ct), decipher.final()]);
+    return decrypted.toString("utf8");
+}
+/**
+ * Detect whether a stored value looks like an encrypted ciphertext produced by encryptField.
+ * Format: "keyId.base64url(iv).base64url(ct).base64url(tag)" — exactly 4 dot-separated parts.
+ */
+export function isEncryptedField(value) {
+    return value.split(".").length === 4;
+}

package/dist/src/shared/lib/signing.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Sign `data` with the active key (first element of `secret`).
+ * Normalizes string | string[] so that an array is never passed directly to
+ * createHmac() — which would silently call .toString() and produce
+ * "[object Array]" as the key.
+ */
+export declare function hmacSign(data: string, secret: string | string[]): string;
+/**
+ * Verify `sig` against `data` using one of the provided keys.
+ * Keys are tried newest-first (index 0 is the active signing key).
+ *
+ * Key ordering convention: put the current (newest) key first; rotated keys
+ * after. The common case (valid current-key signature) succeeds on the first
+ * comparison; old rotated keys only matter for in-flight tokens.
+ *
+ * MUST use timingSafeEqual — never === — to prevent timing side-channel leaks.
+ * This is the most common HMAC implementation mistake.
+ */
+export declare function hmacVerify(data: string, sig: string, secret: string | string[]): boolean;
+/** Returns `"base64url(value).hmac"`. */
+export declare function signCookieValue(value: string, secret: string | string[]): string;
+/** Returns the original value or `null` if the signature is invalid. */
+export declare function verifyCookieValue(signed: string, secret: string | string[]): string | null;
+/** Returns `"base64url(payload).hmac"`. */
+export declare function signCursor(payload: string, secret: string | string[]): string;
+/** Returns the original payload or `null` if the signature is invalid. */
+export declare function verifyCursor(cursor: string, secret: string | string[]): string | null;
+/**
+ * Create a stateless HMAC-signed URL. The signature covers the HTTP method,
+ * storage key, expiry timestamp, and any extra query params so that:
+ *  - Expired URLs are rejected (replay prevention)
+ *  - URLs are method-bound (a GET URL can't be replayed as a PUT)
+ *  - Tampering with the key, expiry, or any extra param invalidates the signature
+ *
+ * @param base   Base URL string (e.g. "https://api.example.com/uploads/presign")
+ * @param key    Storage object key
+ * @param opts   Method, expiry in seconds from now, optional extra query params
+ * @param secret HMAC secret (supports key rotation via string[])
+ */
+export declare function createPresignedUrl(base: string, key: string, opts: {
+    method: string;
+    expiry: number;
+    extra?: Record<string, string>;
+}, secret: string | string[]): string;
+/**
+ * Verify an HMAC-signed URL. Returns the key and any extra params, or null
+ * if the URL is expired, tampered, or method-mismatched.
+ */
+export declare function verifyPresignedUrl(url: string, method: string, secret: string | string[]): {
+    key: string;
+    extra?: Record<string, string>;
+} | null;