@lastshotlabs/bunshot 0.0.27 → 0.0.28

package/dist/src/lib/redis.js

@@ -0,0 +1,72 @@
+// Redis connection management — no module-level mutable state.
+//
+// Phase 1 singleton elimination: connectRedis() returns the client directly
+// instead of storing it in a module global. disconnectRedis() accepts the
+// client as a parameter. Use getRedisFromApp(app) for context-aware access.
+import { log } from '../framework/lib/logger';
+import { getContext } from '../../packages/bunshot-core/src/index.js';
+function requireIoredis() {
+    try {
+        // Bun supports require() in ESM; this defers the import to call time
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const mod = require('ioredis');
+        return mod.default ?? mod;
+    }
+    catch {
+        throw new Error('ioredis is not installed. Run: bun add ioredis');
+    }
+}
+export const getRedisConnectionOptions = (creds) => {
+    const host_port = creds.host;
+    if (!host_port)
+        throw new Error('Missing Redis host — pass credentials via ISecretRepository');
+    const [host, port] = host_port.split(':');
+    if (!host || !port)
+        throw new Error(`Invalid Redis host format — expected "host:port", got "${host_port}"`);
+    const username = creds.user;
+    const password = creds.password;
+    return {
+        host,
+        port: Number(port),
+        ...(username && { username }),
+        ...(password && { password }),
+    };
+};
+/**
+ * Connect to Redis and return the client.
+ * The caller is responsible for storing the client (e.g., on BunshotContext).
+ *
+ * @param creds Credentials resolved by ISecretRepository. No process.env fallback.
+ */
+export const connectRedis = (creds) => {
+    const Redis = requireIoredis();
+    const opts = getRedisConnectionOptions(creds);
+    const client = new Redis(opts);
+    client.on('error', err => log(`[redis] error: ${err.message}`));
+    return new Promise((resolve, reject) => {
+        client.once('ready', () => {
+            log(`[redis] connected to ${opts.host}:${opts.port} as ${opts.username || 'default user'}`);
+            resolve(client);
+        });
+        client.once('error', reject);
+    });
+};
+/**
+ * Gracefully close the Redis connection.
+ * Accepts the client as parameter — no module-level state.
+ */
+export const disconnectRedis = async (client) => {
+    if (!client)
+        return;
+    await client.quit();
+    log('[redis] disconnected');
+};
+/**
+ * Context-aware Redis getter. Returns the instance-scoped Redis from
+ * BunshotContext, or null when Redis is not configured on the context.
+ * Throws if no BunshotContext is attached to the app.
+ */
+export const getRedisFromApp = (app) => {
+    const ctx = getContext(app);
+    return ctx.redis ?? null;
+};

package/dist/{lib → src/lib}/signing.d.ts

@@ -27,10 +27,10 @@ export declare function signCursor(payload: string, secret: string | string[]):
 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, and expiry timestamp so that:
+ * 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 or expiry invalidates the signature
+ *  - 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

package/dist/src/lib/signing.js

@@ -0,0 +1,210 @@
+import { createHmac } from 'crypto';
+import { timingSafeEqual } from '../../packages/bunshot-core/src/index.js';
+// ---------------------------------------------------------------------------
+// Core HMAC primitives
+// ---------------------------------------------------------------------------
+/**
+ * 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 function hmacSign(data, secret) {
+    const key = Array.isArray(secret) ? secret[0] : secret;
+    if (!key) {
+        throw new Error('hmacSign: secret key must be a non-empty string');
+    }
+    return createHmac('sha256', key).update(data).digest('hex');
+}
+/**
+ * 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 function hmacVerify(data, sig, secret) {
+    const keys = Array.isArray(secret) ? secret : [secret];
+    if (keys.length === 0)
+        return false;
+    for (const key of keys) {
+        if (!key)
+            continue;
+        const expected = createHmac('sha256', key).update(data).digest('hex');
+        try {
+            if (timingSafeEqual(expected, sig))
+                return true;
+        }
+        catch {
+            // timingSafeEqual (src/lib/crypto.ts) handles length mismatches itself:
+            // it returns false rather than throwing, so this catch block is never
+            // reached under normal conditions. It is kept as a defensive no-op in
+            // case the underlying implementation changes in the future.
+        }
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Cookie signing
+//
+// Value is base64url-encoded before appending ".sig" to avoid delimiter
+// collision — raw values may contain "." which would break naive
+// split-on-last-dot parsing.
+//
+// Edge case: base64url("") === "" so the signed form for an empty value is
+// ".sig". Split uses lastIndexOf("."), not indexOf("."), and dotIdx === 0
+// is treated as a valid (empty) value, not a parse error.
+// ---------------------------------------------------------------------------
+function toBase64url(s) {
+    return Buffer.from(s).toString('base64url');
+}
+function fromBase64url(s) {
+    return Buffer.from(s, 'base64url').toString('utf8');
+}
+/** Returns `"base64url(value).hmac"`. */
+export function signCookieValue(value, secret) {
+    const encoded = toBase64url(value);
+    const sig = hmacSign(encoded, secret);
+    return `${encoded}.${sig}`;
+}
+/** Returns the original value or `null` if the signature is invalid. */
+export function verifyCookieValue(signed, secret) {
+    const dotIdx = signed.lastIndexOf('.');
+    // dotIdx === 0 is valid: empty encoded value (signed form ".sig")
+    if (dotIdx < 0)
+        return null;
+    const encoded = signed.slice(0, dotIdx);
+    const sig = signed.slice(dotIdx + 1);
+    if (!hmacVerify(encoded, sig, secret))
+        return null;
+    try {
+        return fromBase64url(encoded);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Cursor signing (same structure as cookie signing)
+// ---------------------------------------------------------------------------
+/** Returns `"base64url(payload).hmac"`. */
+export function signCursor(payload, secret) {
+    const encoded = toBase64url(payload);
+    const sig = hmacSign(encoded, secret);
+    return `${encoded}.${sig}`;
+}
+/** Returns the original payload or `null` if the signature is invalid. */
+export function verifyCursor(cursor, secret) {
+    const dotIdx = cursor.lastIndexOf('.');
+    if (dotIdx < 0)
+        return null;
+    const encoded = cursor.slice(0, dotIdx);
+    const sig = cursor.slice(dotIdx + 1);
+    if (!hmacVerify(encoded, sig, secret))
+        return null;
+    try {
+        return fromBase64url(encoded);
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Presigned URLs
+//
+// Signing data = method + "\n" + key + "\n" + exp + "\n" + sortedParams
+// Newline delimiter is safe: keys like "uploads/2024/photo.jpg" contain dots
+// but cannot contain newlines; method and exp never contain newlines.
+// Using "." would create ambiguity with keys containing dots.
+//
+// Extra params are included in the HMAC so that an attacker cannot modify,
+// add, or remove query parameters without invalidating the signature.
+// sortedParams is always present (empty string when no extra params) so the
+// "\n" delimiter is consistent — prevents length-extension confusion.
+// ---------------------------------------------------------------------------
+/**
+ * Serialize extra params for inclusion in the HMAC signing string.
+ * Keys are sorted, then each key and value are percent-encoded (encodeURIComponent)
+ * and joined as "key=value&key2=value2". Returns "" when params is empty/undefined.
+ */
+function serializeExtraParams(params) {
+    if (!params || Object.keys(params).length === 0)
+        return '';
+    return Object.keys(params)
+        .sort()
+        .map(k => `${encodeURIComponent(k)}=${encodeURIComponent(params[k])}`)
+        .join('&');
+}
+/**
+ * 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 function createPresignedUrl(base, key, opts, secret) {
+    const exp = Math.floor(Date.now() / 1000) + opts.expiry;
+    const method = opts.method.toUpperCase();
+    const sortedParams = serializeExtraParams(opts.extra);
+    const data = `${method}\n${key}\n${exp}\n${sortedParams}`;
+    const sig = hmacSign(data, secret);
+    const url = new URL(base);
+    url.searchParams.set('key', key);
+    url.searchParams.set('exp', String(exp));
+    url.searchParams.set('method', method);
+    url.searchParams.set('sig', sig);
+    if (opts.extra) {
+        for (const [k, v] of Object.entries(opts.extra)) {
+            url.searchParams.set(k, v);
+        }
+    }
+    return url.toString();
+}
+/**
+ * Verify an HMAC-signed URL. Returns the key and any extra params, or null
+ * if the URL is expired, tampered, or method-mismatched.
+ */
+export function verifyPresignedUrl(url, method, secret) {
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const key = parsedUrl.searchParams.get('key');
+    const exp = parsedUrl.searchParams.get('exp');
+    const sig = parsedUrl.searchParams.get('sig');
+    const urlMethod = parsedUrl.searchParams.get('method');
+    if (!key || !exp || !sig || !urlMethod)
+        return null;
+    // Method binding check
+    if (urlMethod !== method.toUpperCase())
+        return null;
+    // Expiry check
+    const expNum = parseInt(exp, 10);
+    if (!isFinite(expNum) || expNum < Math.floor(Date.now() / 1000))
+        return null;
+    // Collect extra params (all except reserved ones)
+    const reserved = new Set(['key', 'exp', 'sig', 'method']);
+    const extra = {};
+    for (const [k, v] of parsedUrl.searchParams.entries()) {
+        if (!reserved.has(k))
+            extra[k] = v;
+    }
+    // Signature check — includes extra params so tampering is detected
+    const sortedParams = serializeExtraParams(Object.keys(extra).length > 0 ? extra : undefined);
+    const data = `${urlMethod}\n${key}\n${exp}\n${sortedParams}`;
+    if (!hmacVerify(data, sig, secret))
+        return null;
+    return Object.keys(extra).length > 0 ? { key, extra } : { key };
+}

package/dist/src/lib/signingConfig.d.ts

@@ -0,0 +1,40 @@
+import type { DataEncryptionKey } from '../../packages/bunshot-core/src/index.js';
+export type { DataEncryptionKey };
+export interface SigningConfig {
+    /**
+     * HMAC secret. Defaults to JWT_SECRET env var if omitted.
+     * Pass string[] to support key rotation - first element signs, all elements verify.
+     */
+    secret?: string | string[];
+    /** Sign/verify cookie values set via exported helpers. Default: false. */
+    cookies?: boolean;
+    /** Sign pagination cursor tokens to prevent client tampering. Default: false. */
+    cursors?: boolean;
+    /** HMAC-based stateless presigned URLs (no DB lookup). Default: false. */
+    presignedUrls?: boolean | {
+        defaultExpiry?: number;
+    };
+    /** Require clients to HMAC-sign requests (method+path+timestamp+body). Default: false. */
+    requestSigning?: boolean | {
+        tolerance?: number;
+        header?: string;
+        timestampHeader?: string;
+    };
+    /** Hash idempotency keys before storage. Default: false. */
+    idempotencyKeys?: boolean;
+    /** Bind sessions to client IP+UA fingerprint. Default: false. */
+    sessionBinding?: boolean | {
+        fields?: Array<'ip' | 'ua' | 'accept-language'>;
+        onMismatch?: 'unauthenticate' | 'reject' | 'log-only';
+    };
+}
+/**
+ * Parse data encryption keys from a raw string value resolved by the ISecretRepository.
+ *
+ * Format: comma-separated "keyId:base64key" pairs, first is active.
+ * Example: "v1:base64key1,v0:base64key0"
+ * Returns [] when empty or not provided.
+ *
+ * @param rawValue Value resolved by ISecretRepository. No process.env fallback.
+ */
+export declare function getDataEncryptionKeys(rawValue?: string): DataEncryptionKey[];

package/dist/src/lib/signingConfig.js

@@ -0,0 +1,28 @@
+// ---------------------------------------------------------------------------
+// Data encryption keys (AES-256-GCM for field-level encryption at rest)
+// ---------------------------------------------------------------------------
+/**
+ * Parse data encryption keys from a raw string value resolved by the ISecretRepository.
+ *
+ * Format: comma-separated "keyId:base64key" pairs, first is active.
+ * Example: "v1:base64key1,v0:base64key0"
+ * Returns [] when empty or not provided.
+ *
+ * @param rawValue Value resolved by ISecretRepository. No process.env fallback.
+ */
+export function getDataEncryptionKeys(rawValue) {
+    const raw = rawValue ?? '';
+    if (!raw.trim())
+        return [];
+    return raw.split(',').map(entry => {
+        const colonIdx = entry.indexOf(':');
+        if (colonIdx === -1)
+            throw new Error(`getDataEncryptionKeys: invalid entry "${entry}" - expected "keyId:base64key"`);
+        const keyId = entry.slice(0, colonIdx).trim();
+        const keyBase64 = entry.slice(colonIdx + 1).trim();
+        const key = Buffer.from(keyBase64, 'base64');
+        if (key.length !== 32)
+            throw new Error(`getDataEncryptionKeys: key "${keyId}" must be 32 bytes (got ${key.length})`);
+        return { keyId, key };
+    });
+}

package/dist/src/server.d.ts

@@ -0,0 +1,146 @@
+import { type HeartbeatConfig } from './framework/lib/wsHeartbeat';
+import type { WsMessageDefaults, WsMessageStore } from './framework/lib/wsMessages';
+import type { WsTransportAdapter } from './framework/lib/wsTransport';
+import { type SocketData } from './framework/ws/index';
+import type { BunFile, Server, ServerWebSocket } from 'bun';
+import type { SseEndpointConfig } from '../packages/bunshot-core/src/index.js';
+import type { BunshotContext } from '../packages/bunshot-core/src/index.js';
+import { type CreateAppConfig } from './app';
+export type { SocketData };
+/**
+ * Retrieve the BunshotContext associated with a server.
+ * Available after createServer() completes. Used by test helpers.
+ */
+export declare function getServerContext(server: object): BunshotContext | null;
+/**
+ * TLS options passed through to Bun.serve().
+ * Fields are a subset of Bun's TLSOptions interface.
+ * Keep aligned with bun-types on Bun upgrades.
+ */
+export interface BunTLSConfig {
+    key?: string | BunFile;
+    cert?: string | BunFile;
+    ca?: string | BunFile;
+    passphrase?: string;
+    /** SNI server name */
+    serverName?: string;
+    dhParamsFile?: string;
+    lowMemoryMode?: boolean;
+    /** OpenSSL SSL_OP_* bitmask; use carefully */
+    secureOptions?: number;
+    /** Reject clients with invalid certificates (mTLS) */
+    rejectUnauthorized?: boolean;
+    /** Request a client certificate (mTLS) */
+    requestCert?: boolean;
+}
+export interface WsEndpointConfig<T extends object = object> {
+    /**
+     * Auth and upgrade logic for this endpoint.
+     * Return undefined after calling server.upgrade() to accept.
+     * Return a Response to reject (e.g. 401, 403).
+     * Omit to use the default upgrade handler (attaches userId from session/JWT if present).
+     */
+    upgrade?: (req: Request, server: Server<SocketData<T>>) => Promise<Response | undefined>;
+    /**
+     * Application-layer WebSocket hooks.
+     *
+     * Framework effects (heartbeat registration, presence tracking, room cleanup)
+     * always run first. These hooks fire after. Any hook not provided is a no-op.
+     *
+     * `pong` is intentionally excluded. Pong frames are owned exclusively by the
+     * heartbeat system.
+     *
+     * Async contract:
+     * - `open`, `message`, `close` — awaited. Throws are caught, logged, execution continues.
+     * - `drain` — NOT awaited (fire-and-forget).
+     * - `upgrade` — awaited. Throws propagate as HTTP 500 responses.
+     */
+    on?: {
+        open?: (ws: ServerWebSocket<SocketData<T>>) => void | Promise<void>;
+        message?: (ws: ServerWebSocket<SocketData<T>>, message: string | Buffer) => void | Promise<void>;
+        close?: (ws: ServerWebSocket<SocketData<T>>, code: number, reason: string) => void | Promise<void>;
+        drain?: (ws: ServerWebSocket<SocketData<T>>) => void | Promise<void>;
+    };
+    /** Guard called before a socket joins a room. Return false to deny. */
+    onRoomSubscribe?: (ws: ServerWebSocket<SocketData<T>>, room: string) => boolean | Promise<boolean>;
+    /** Max message bytes for this endpoint. Default: 65536 (64 KB). */
+    maxMessageSize?: number;
+    /**
+     * Heartbeat keepalive. true = defaults (30s interval, 10s timeout).
+     * Global tick runs at the minimum intervalMs across all active endpoints.
+     */
+    heartbeat?: boolean | HeartbeatConfig;
+    /**
+     * Presence tracking. true = broadcast presence_join / presence_leave to rooms.
+     * Events are scoped to this endpoint.
+     */
+    presence?: boolean | {
+        broadcastEvents?: boolean;
+    };
+    /**
+     * Message persistence. Rooms must be opted in per-endpoint via configureRoom().
+     */
+    persistence?: {
+        store?: WsMessageStore;
+        defaults?: WsMessageDefaults;
+    };
+}
+export interface WsConfig<T extends object = object> {
+    /**
+     * WebSocket endpoints. Each key is the upgrade URL path.
+     *
+     * @example
+     * {
+     *   "/chat": { heartbeat: true, presence: true },
+     *   "/notifications": { upgrade: publicUpgrade },
+     *   "/admin": { upgrade: adminRoleCheck, maxMessageSize: 8192 },
+     * }
+     */
+    endpoints: Record<string, WsEndpointConfig<T>>;
+    /** Cross-instance pub/sub transport. Shared across all endpoints. */
+    transport?: WsTransportAdapter;
+    idleTimeout?: number;
+    backpressureLimit?: number;
+    closeOnBackpressureLimit?: boolean;
+    perMessageDeflate?: boolean;
+    publishToSelf?: boolean;
+}
+export type { SseEndpointConfig };
+export interface SseConfig<T extends object = object> {
+    /**
+     * SSE endpoints. Every key MUST:
+     * - start with `/__sse/`
+     * - be a literal path (no `:param` segments, no `*` wildcards)
+     *
+     * @example { "/__sse/feed": { events: ['community:thread.created'] } }
+     */
+    endpoints: Record<string, SseEndpointConfig<T>>;
+}
+export interface CreateServerConfig<T extends object = object> extends CreateAppConfig {
+    port?: number;
+    /**
+     * Bind address. Default "0.0.0.0".
+     * Omitted when `unix` is set.
+     */
+    hostname?: string;
+    /**
+     * Unix domain socket path. Mutually exclusive with port, hostname, and tls.
+     */
+    unix?: string;
+    /** TLS configuration. Passed through to Bun.serve(). */
+    tls?: BunTLSConfig;
+    /** Absolute path to the service's workers directory — auto-imports all .ts files */
+    workersDir?: string;
+    /** Set false to disable auto-loading workers. Defaults to true */
+    enableWorkers?: boolean;
+    /** WebSocket configuration */
+    ws?: WsConfig<T>;
+    /** SSE configuration */
+    sse?: SseConfig<T>;
+    /**
+     * Maximum request body size in bytes. Defaults to the upload config limit when present
+     * (maxFileSize * maxFiles), otherwise Bun's default (128 MB).
+     */
+    maxRequestBodySize?: number;
+}
+export declare const createServer: <T extends object = object>(config: CreateServerConfig<T>) => Promise<Server<SocketData<T>>>;