@lastshotlabs/bunshot 0.0.25 → 0.0.28

package/dist/src/lib/authConfig.js

@@ -0,0 +1,179 @@
+// Auth-specific runtime configuration singletons.
+// Framework-only config (appName, appRoles, corsConfig, etc.) stays in appConfig.ts.
+let _primaryField = "email";
+export const setPrimaryField = (field) => { _primaryField = field; };
+export const getPrimaryField = () => _primaryField;
+let _concealRegistrationConfig = null;
+export const setConcealRegistrationConfig = (config) => { _concealRegistrationConfig = config; };
+export const getConcealRegistrationConfig = () => _concealRegistrationConfig;
+let _emailVerificationConfig = null;
+export const setEmailVerificationConfig = (config) => { _emailVerificationConfig = config; };
+export const getEmailVerificationConfig = () => _emailVerificationConfig;
+const DEFAULT_TOKEN_EXPIRY = 60 * 60 * 24; // 24 hours
+export const getTokenExpiry = () => _emailVerificationConfig?.tokenExpiry ?? DEFAULT_TOKEN_EXPIRY;
+let _passwordResetConfig = null;
+export const setPasswordResetConfig = (config) => { _passwordResetConfig = config; };
+export const getPasswordResetConfig = () => _passwordResetConfig;
+const DEFAULT_RESET_TOKEN_EXPIRY = 60 * 60; // 1 hour
+export const getResetTokenExpiry = () => _passwordResetConfig?.tokenExpiry ?? DEFAULT_RESET_TOKEN_EXPIRY;
+let _magicLinkConfig = null;
+export const setMagicLinkConfig = (config) => { _magicLinkConfig = config; };
+export const getMagicLinkConfig = () => _magicLinkConfig;
+export const getMagicLinkTtl = () => _magicLinkConfig?.ttlSeconds ?? 900;
+let _passwordPolicy = {};
+export const setPasswordPolicy = (config) => { _passwordPolicy = config; };
+export const getPasswordPolicy = () => _passwordPolicy;
+export const getPasswordPolicyPreventReuse = () => _passwordPolicy.preventReuse ?? 0;
+let _authCookieConfig = {};
+let _csrfCookieConfig = {};
+export function setAuthCookieConfig(c) { _authCookieConfig = c; }
+export function getAuthCookieConfig() { return _authCookieConfig; }
+export function setCsrfCookieConfig(c) { _csrfCookieConfig = c; }
+export function getCsrfCookieConfig() { return _csrfCookieConfig; }
+// ---------------------------------------------------------------------------
+// Session policy
+// ---------------------------------------------------------------------------
+let _maxSessions = 6;
+let _persistSessionMetadata = true;
+let _includeInactiveSessions = false;
+let _trackLastActive = false;
+let _sessionPolicyConfig = {};
+export const setMaxSessions = (n) => { _maxSessions = Number.isFinite(n) && n >= 1 ? Math.floor(n) : 1; };
+export const getMaxSessions = () => _maxSessions;
+export const setPersistSessionMetadata = (v) => { _persistSessionMetadata = v; };
+export const getPersistSessionMetadata = () => _persistSessionMetadata;
+export const setIncludeInactiveSessions = (v) => { _includeInactiveSessions = v; };
+export const getIncludeInactiveSessions = () => _includeInactiveSessions;
+export const setTrackLastActive = (v) => { _trackLastActive = v; };
+export const getTrackLastActive = () => _trackLastActive;
+export function setSessionPolicyConfig(p) { _sessionPolicyConfig = p; }
+export function getSessionPolicyConfig() { return _sessionPolicyConfig; }
+let _refreshTokenConfig = null;
+export const setRefreshTokenConfig = (config) => { _refreshTokenConfig = config; };
+export const getRefreshTokenConfig = () => _refreshTokenConfig;
+const DEFAULT_ACCESS_TOKEN_EXPIRY = 900; // 15 min
+const DEFAULT_REFRESH_TOKEN_EXPIRY = 2_592_000; // 30 days
+const DEFAULT_ROTATION_GRACE_SECONDS = 30;
+export const getAccessTokenExpiry = () => _refreshTokenConfig?.accessTokenExpiry ?? DEFAULT_ACCESS_TOKEN_EXPIRY;
+export const getRefreshTokenExpiry = () => _refreshTokenConfig?.refreshTokenExpiry ?? DEFAULT_REFRESH_TOKEN_EXPIRY;
+export const getRotationGraceSeconds = () => _refreshTokenConfig?.rotationGraceSeconds ?? DEFAULT_ROTATION_GRACE_SECONDS;
+let _mfaConfig = null;
+export const setMfaConfig = (config) => { _mfaConfig = config; };
+export const getMfaConfig = () => _mfaConfig;
+// getMfaIssuer is defined after the getAppName import below
+// ---------------------------------------------------------------------------
+// Forward reference: getAppName lives in appConfig.ts
+// ---------------------------------------------------------------------------
+import { getAppName } from "./appConfig";
+export const getMfaIssuer = () => _mfaConfig?.issuer ?? getAppName();
+export const getMfaAlgorithm = () => _mfaConfig?.algorithm ?? "SHA1";
+export const getMfaDigits = () => _mfaConfig?.digits ?? 6;
+export const getMfaPeriod = () => _mfaConfig?.period ?? 30;
+export const getMfaRecoveryCodeCount = () => _mfaConfig?.recoveryCodes ?? 10;
+export const getMfaChallengeTtl = () => _mfaConfig?.challengeTtlSeconds ?? 300;
+export const getMfaEmailOtpConfig = () => _mfaConfig?.emailOtp ?? null;
+export const getMfaEmailOtpCodeLength = () => _mfaConfig?.emailOtp?.codeLength ?? 6;
+export const getMfaWebAuthnConfig = () => _mfaConfig?.webauthn ?? null;
+export const getMfaRequired = () => _mfaConfig?.required ?? false;
+export const getMfaWebAuthnAllowPasswordlessLogin = () => _mfaConfig?.webauthn?.allowPasswordlessLogin ?? false;
+export const getMfaWebAuthnPasskeyMfaBypass = () => _mfaConfig?.webauthn?.passkeyMfaBypass ?? true;
+// ---------------------------------------------------------------------------
+// CSRF config
+// ---------------------------------------------------------------------------
+let _csrfEnabled = false;
+export const setCsrfEnabled = (v) => { _csrfEnabled = v; };
+export const getCsrfEnabled = () => _csrfEnabled;
+let _signingConfig = null;
+let _signingConfigured = false;
+export const setSigningConfig = (config) => {
+    _signingConfig = config;
+    _signingConfigured = true;
+};
+export const getSigningConfig = () => _signingConfig;
+export const isSigningConfigured = () => _signingConfigured;
+/**
+ * Returns the active signing secret: signing.secret -> JWT_SECRET_PROD/DEV env var.
+ * Returns null when neither is configured - callers must handle this gracefully.
+ */
+export const getSigningSecret = () => {
+    if (_signingConfig?.secret)
+        return _signingConfig.secret;
+    const isProd = process.env.NODE_ENV === "production";
+    const envKey = isProd ? "JWT_SECRET_PROD" : "JWT_SECRET_DEV";
+    const rawSecret = process.env[envKey];
+    return rawSecret ?? null;
+};
+let _jwtConfig = null;
+export const setJwtConfig = (config) => { _jwtConfig = config; };
+export const getJwtConfig = () => _jwtConfig;
+export const getJwtIssuer = () => _jwtConfig?.issuer;
+export const getJwtAudience = () => _jwtConfig?.audience;
+let _breachedPasswordConfig = null;
+export const setBreachedPasswordConfig = (config) => { _breachedPasswordConfig = config; };
+export const getBreachedPasswordConfig = () => _breachedPasswordConfig;
+let _oauthReauthConfig = null;
+export const setOAuthReauthConfig = (config) => { _oauthReauthConfig = config; };
+export const getOAuthReauthConfig = () => _oauthReauthConfig;
+export const getOAuthReauthEnabled = () => _oauthReauthConfig?.enabled ?? false;
+export const getOAuthReauthPromptType = () => _oauthReauthConfig?.promptType ?? "login";
+let _stepUpConfig = null;
+export const setStepUpConfig = (config) => { _stepUpConfig = config; };
+export const getStepUpConfig = () => _stepUpConfig;
+// ---------------------------------------------------------------------------
+// Suspension config
+// ---------------------------------------------------------------------------
+let _checkSuspensionOnIdentify = false;
+export const setCheckSuspensionOnIdentify = (v) => { _checkSuspensionOnIdentify = v; };
+export const getCheckSuspensionOnIdentify = () => _checkSuspensionOnIdentify;
+// ---------------------------------------------------------------------------
+// CAPTCHA config
+// ---------------------------------------------------------------------------
+let _captchaConfig = null;
+export const setCaptchaConfig = (config) => { _captchaConfig = config; };
+export const getCaptchaConfig = () => _captchaConfig;
+let _m2mConfig = null;
+export const setM2MConfig = (config) => { _m2mConfig = config; };
+export const getM2MConfig = () => _m2mConfig;
+export const getM2MTokenExpiry = () => _m2mConfig?.tokenExpiry ?? 3600;
+let _samlConfig = null;
+export const setSamlConfig = (config) => { _samlConfig = config; };
+export const getSamlConfig = () => _samlConfig;
+let _oidcConfig = null;
+export const setOidcConfig = (config) => { _oidcConfig = config; };
+export const getOidcConfig = () => _oidcConfig;
+let _scimConfig = null;
+export const setScimConfig = (config) => { _scimConfig = config; };
+export const getScimConfig = () => _scimConfig;
+let _emailTemplatesConfig = null;
+export const setEmailTemplatesConfig = (config) => { _emailTemplatesConfig = config; };
+export const getEmailTemplatesConfig = () => _emailTemplatesConfig;
+let _hooks = {};
+export function setHooksConfig(h) { _hooks = h; }
+export function getHooksConfig() { return _hooks; }
+/**
+ * Parse data encryption keys from the BUNSHOT_DATA_ENCRYPTION_KEY env var.
+ * Env var format: comma-separated "keyId:base64key" pairs, first is active.
+ * Example: "v1:base64key1,v0:base64key0"
+ * Respects DEV/PROD split: BUNSHOT_DATA_ENCRYPTION_KEY_DEV / BUNSHOT_DATA_ENCRYPTION_KEY_PROD.
+ * Falls back to BUNSHOT_DATA_ENCRYPTION_KEY (no suffix).
+ * Returns [] when not set.
+ */
+export function getDataEncryptionKeys() {
+    const isProd = process.env.NODE_ENV === "production";
+    const raw = (isProd ? process.env.BUNSHOT_DATA_ENCRYPTION_KEY_PROD : process.env.BUNSHOT_DATA_ENCRYPTION_KEY_DEV)
+        ?? process.env.BUNSHOT_DATA_ENCRYPTION_KEY
+        ?? "";
+    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/{lib → src/lib}/context.d.ts

@@ -1,6 +1,7 @@
-import { OpenAPIHono, type Hook } from "@hono/zod-openapi";
-import type { ZodIssue } from "zod";
-import type { UploadResult } from "./storageAdapter";
+import { OpenAPIHono, type Hook } from '@hono/zod-openapi';
+import type { ZodIssue } from 'zod';
+import type { UploadResult } from '../framework/lib/storageAdapter';
+import type { AuthVariables } from '../../packages/bunshot-auth/src/lib/authContext';
 export interface ValidationErrorDetail {
     path: string;
     message: string;
@@ -14,9 +15,6 @@ export type ValidationErrorFormatter = (issues: ZodIssue[], requestId: string) =
 export declare const defaultValidationErrorFormatter: ValidationErrorFormatter;
 export type AppVariables = {
     requestId: string;
-    authUserId: string | null;
-    roles: string[] | null;
-    sessionId: string | null;
     tenantId: string | null;
     tenantConfig: Record<string, unknown> | null;
     validationErrorFormatter: ValidationErrorFormatter;
@@ -24,7 +22,8 @@ export type AppVariables = {
     uploadBucket: string | undefined;
 };
 export type AppEnv = {
-    Variables: AppVariables;
+    Variables: AppVariables & AuthVariables;
 };
 export declare const defaultHook: Hook<any, AppEnv, any, any>;
 export declare const createRouter: () => OpenAPIHono<AppEnv, {}, "/">;
+export type { AuthVariables } from '../../packages/bunshot-auth/src/lib/authContext';

package/dist/{lib → src/lib}/context.js

@@ -1,16 +1,16 @@
-import { OpenAPIHono } from "@hono/zod-openapi";
+import { OpenAPIHono } from '@hono/zod-openapi';
 export const defaultValidationErrorFormatter = (issues, requestId) => {
-    const error = issues.map((i) => i.message).join(", ");
+    const error = issues.map((i) => i.message).join(', ');
     const details = issues.map((i) => ({
-        path: i.path.join("."),
+        path: i.path.join('.'),
         message: i.message,
     }));
     return { error, details, requestId };
 };
 export const defaultHook = (result, c) => {
     if (!result.success) {
-        const requestId = c.get("requestId") ?? "unknown";
-        const formatter = c.get("validationErrorFormatter") ?? defaultValidationErrorFormatter;
+        const requestId = c.get('requestId') ?? 'unknown';
+        const formatter = c.get('validationErrorFormatter') ?? defaultValidationErrorFormatter;
         try {
             return c.json(formatter(result.error.issues, requestId), 400);
         }

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

@@ -0,0 +1 @@
+export { log, authTrace } from "../framework/lib/logger";

package/dist/src/lib/logger.js

@@ -0,0 +1 @@
+export { log, authTrace } from "../framework/lib/logger";

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

@@ -0,0 +1,58 @@
+import type { Connection, Mongoose } from 'mongoose';
+type MongooseModule = Mongoose;
+export interface MongoCredentials {
+    user: string;
+    password: string;
+    host: string;
+    db: string;
+}
+export interface MongoConnections {
+    authConn: Connection;
+    appConn: Connection;
+    mongoose: MongooseModule;
+}
+/**
+ * Connect the auth connection to its dedicated MongoDB server.
+ *
+ * @param creds Credentials resolved by ISecretRepository. No process.env fallback.
+ */
+export declare const connectAuthMongo: (creds: MongoCredentials) => Promise<{
+    authConn: Connection;
+    mongoose: MongooseModule;
+}>;
+/**
+ * Connect the app connection to its MongoDB server.
+ *
+ * @param creds Credentials resolved by ISecretRepository. No process.env fallback.
+ */
+export declare const connectAppMongo: (creds: MongoCredentials) => Promise<{
+    appConn: Connection;
+    mongoose: MongooseModule;
+}>;
+/**
+ * Connect both auth and app connections to the same MongoDB server.
+ * Shorthand for single-DB setups.
+ *
+ * @param creds Credentials resolved by ISecretRepository. No process.env fallback.
+ */
+export declare const connectMongo: (creds: MongoCredentials) => Promise<MongoConnections>;
+/**
+ * Context-aware Mongo getter. Returns the instance-scoped connections from
+ * BunshotContext. Throws if no BunshotContext is attached to the app.
+ * Returns null when Mongo is not configured on the context.
+ */
+export declare const getMongoFromApp: (app: object) => {
+    auth: Connection | null;
+    app: Connection | null;
+} | null;
+/**
+ * Close both auth and app Mongo connections.
+ * Accepts connections as parameters — no module-level state.
+ */
+export declare const disconnectMongo: (authConn: Connection | null, appConn: Connection | null) => Promise<void>;
+/**
+ * Get the mongoose module (lazy-loaded). Useful for consumers that need
+ * the mongoose module without a connection (e.g., Schema class access).
+ */
+export declare const getMongooseModule: () => MongooseModule;
+export {};

package/dist/src/lib/mongo.js

@@ -0,0 +1,96 @@
+// MongoDB connection management — no module-level mutable state.
+//
+// Phase 1 singleton elimination: connect functions return their connections
+// directly instead of storing them in module globals. Module-level proxy
+// objects (authConnection, appConnection, mongoose) are removed.
+// Use getMongoFromApp(app) for context-aware access.
+import { log } from '../framework/lib/logger';
+import { getContext } from '../../packages/bunshot-core/src/index.js';
+/** Lazy mongoose module loader — caching a require() result, not runtime state. */
+function requireMongoose() {
+    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('mongoose');
+        return (mod.default ?? mod);
+    }
+    catch {
+        throw new Error('mongoose is not installed. Run: bun add mongoose');
+    }
+}
+function buildUri(user, password, host, db) {
+    const [hostPart, queryPart] = host.split('?');
+    return `mongodb+srv://${encodeURIComponent(user)}:${encodeURIComponent(password)}@${hostPart.replace(/\/$/, '')}/${db}${queryPart ? `?${queryPart}` : ''}`;
+}
+/**
+ * Connect the auth connection to its dedicated MongoDB server.
+ *
+ * @param creds Credentials resolved by ISecretRepository. No process.env fallback.
+ */
+export const connectAuthMongo = async (creds) => {
+    const mg = requireMongoose();
+    const authConn = mg.createConnection();
+    const uri = buildUri(creds.user, creds.password, creds.host, creds.db);
+    await authConn.openUri(uri);
+    log(`[mongo] auth connected to ${creds.host} as ${creds.user}`);
+    return { authConn, mongoose: mg };
+};
+/**
+ * Connect the app connection to its MongoDB server.
+ *
+ * @param creds Credentials resolved by ISecretRepository. No process.env fallback.
+ */
+export const connectAppMongo = async (creds) => {
+    const mg = requireMongoose();
+    const appConn = mg.createConnection();
+    const uri = buildUri(creds.user, creds.password, creds.host, creds.db);
+    await appConn.openUri(uri);
+    log(`[mongo] app connected to ${creds.host} as ${creds.user}`);
+    return { appConn, mongoose: mg };
+};
+/**
+ * Connect both auth and app connections to the same MongoDB server.
+ * Shorthand for single-DB setups.
+ *
+ * @param creds Credentials resolved by ISecretRepository. No process.env fallback.
+ */
+export const connectMongo = async (creds) => {
+    const mg = requireMongoose();
+    const authConn = mg.createConnection();
+    const appConn = mg.createConnection();
+    const uri = buildUri(creds.user, creds.password, creds.host, creds.db);
+    await Promise.all([authConn.openUri(uri), appConn.openUri(uri)]);
+    log(`[mongo] connected to ${creds.host} as ${creds.user}`);
+    return { authConn, appConn, mongoose: mg };
+};
+/**
+ * Context-aware Mongo getter. Returns the instance-scoped connections from
+ * BunshotContext. Throws if no BunshotContext is attached to the app.
+ * Returns null when Mongo is not configured on the context.
+ */
+export const getMongoFromApp = (app) => {
+    const ctx = getContext(app);
+    if (ctx.mongo) {
+        return {
+            auth: ctx.mongo.auth ?? null,
+            app: ctx.mongo.app ?? null,
+        };
+    }
+    return null;
+};
+/**
+ * Close both auth and app Mongo connections.
+ * Accepts connections as parameters — no module-level state.
+ */
+export const disconnectMongo = async (authConn, appConn) => {
+    await Promise.all([
+        authConn && authConn.readyState !== 0 ? authConn.close() : Promise.resolve(),
+        appConn && appConn.readyState !== 0 ? appConn.close() : Promise.resolve(),
+    ]);
+    log('[mongo] disconnected');
+};
+/**
+ * Get the mongoose module (lazy-loaded). Useful for consumers that need
+ * the mongoose module without a connection (e.g., Schema class access).
+ */
+export const getMongooseModule = () => requireMongoose();

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

@@ -0,0 +1,72 @@
+import type { Job, Processor, QueueOptions, Queue as QueueType, WorkerOptions, Worker as WorkerType } from 'bullmq';
+import { type RedisCredentials } from './redis';
+export interface CronSchedule {
+    /** Cron expression. Mutually exclusive with `every`. */
+    cron?: string;
+    /** Interval in milliseconds. Mutually exclusive with `cron`. */
+    every?: number;
+    /** Timezone for cron expressions. */
+    timezone?: string;
+}
+export interface DLQOptions<T = unknown> {
+    /** Max jobs to keep in the DLQ. Default: 1000. */
+    maxSize?: number;
+    /** Called when a job is moved to the DLQ. */
+    onDeadLetter?: (job: Job<T>, error: Error) => Promise<void>;
+    /** Auto-retry delay in ms. No auto-retry by default. */
+    retryAfter?: number;
+    /** Preserve original job options on retry. Default: true. */
+    preserveJobOptions?: boolean;
+}
+export interface QueueFactory {
+    createQueue<T = unknown, R = unknown>(name: string, options?: Omit<QueueOptions, 'connection'>): QueueType<T, R>;
+    createWorker<T = unknown, R = unknown>(name: string, processor: Processor<T, R>, options?: Omit<WorkerOptions, 'connection'>): WorkerType<T, R>;
+    createCronWorker<T = void, R = unknown>(name: string, processor: Processor<T, R>, schedule: CronSchedule, options?: Omit<WorkerOptions, 'connection'>): {
+        worker: WorkerType<T, R>;
+        queue: QueueType<T, R>;
+        registeredName: string;
+    };
+    cleanupStaleSchedulers(activeNames: string[], registeredNames: ReadonlySet<string>): Promise<void>;
+    createDLQHandler<T = unknown>(sourceWorker: WorkerType<T>, sourceQueueName: string, options?: DLQOptions<T>): {
+        dlqQueue: QueueType<T>;
+        retryJob: (jobId: string) => Promise<void>;
+    };
+}
+export declare function createQueueFactory(credentials: RedisCredentials): QueueFactory;
+export declare function createQueue<T = unknown, R = unknown>(name: string, options?: Omit<QueueOptions, 'connection'>, credentials?: RedisCredentials): QueueType<T, R>;
+export declare function createWorker<T = unknown, R = unknown>(name: string, processor: Processor<T, R>, options?: Omit<WorkerOptions, 'connection'>, credentials?: RedisCredentials): WorkerType<T, R>;
+export declare function createCronWorker<T = void, R = unknown>(name: string, processor: Processor<T, R>, schedule: CronSchedule, options?: Omit<WorkerOptions, 'connection'>, credentials?: RedisCredentials): {
+    worker: WorkerType<T, R>;
+    queue: QueueType<T, R>;
+    registeredName: string;
+};
+export declare function cleanupStaleSchedulers(activeNames: string[], registeredNames: ReadonlySet<string>, credentials?: RedisCredentials): Promise<void>;
+export declare function createDLQHandler<T = unknown>(sourceWorker: WorkerType<T>, sourceQueueName: string, options?: DLQOptions<T>, credentials?: RedisCredentials): {
+    dlqQueue: QueueType<T>;
+    retryJob: (jobId: string) => Promise<void>;
+};
+/**
+ * Contract for worker files loaded by createServer()'s worker discovery.
+ *
+ * A worker file's default export should be a BunshotWorker. The framework
+ * calls it at startup with a properly-credentialed QueueFactory and collects
+ * the returned names for scheduler lifecycle management.
+ *
+ * @example
+ * ```ts
+ * // workers/digest.ts
+ * import type { BunshotWorker } from 'bunshot/queue'
+ *
+ * const worker: BunshotWorker = async (factory) => {
+ *   const { registeredName } = factory.createCronWorker(
+ *     'digest-emails',
+ *     digestProcessor,
+ *     { cron: '0 9 * * *' },
+ *   )
+ *   return [registeredName]
+ * }
+ * export default worker
+ * ```
+ */
+export type BunshotWorker = (factory: QueueFactory) => string[] | Promise<string[]>;
+export type { Job, RedisCredentials as QueueRedisCredentials };

package/dist/src/lib/queue.js

@@ -0,0 +1,152 @@
+import { getRedisConnectionOptions } from './redis';
+function requireBullMQ() {
+    try {
+        // Bun supports require() in ESM; this defers the import to call time.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('bullmq');
+    }
+    catch {
+        throw new Error('bullmq is not installed. Run: bun add bullmq');
+    }
+}
+function requireQueueRedisCredentials(credentials) {
+    if (!credentials?.host) {
+        throw new Error('Queue helpers require explicit Redis credentials. Resolve Redis secrets at startup and pass them to createQueueFactory(...) or as the final queue helper argument.');
+    }
+    return credentials;
+}
+function getQueueRedisConnectionOptions(credentials) {
+    return getRedisConnectionOptions(credentials);
+}
+function buildQueueHelpers(getConnectionOptions) {
+    return {
+        createQueue(name, options) {
+            const { Queue } = requireBullMQ();
+            return new Queue(name, { connection: getConnectionOptions(), ...options });
+        },
+        createWorker(name, processor, options) {
+            const { Worker } = requireBullMQ();
+            return new Worker(name, processor, {
+                connection: getConnectionOptions(),
+                ...options,
+            });
+        },
+        createCronWorker(name, processor, schedule, options) {
+            const { Queue, Worker } = requireBullMQ();
+            const connection = getConnectionOptions();
+            const queue = new Queue(name, { connection });
+            const worker = new Worker(name, processor, { connection, ...options });
+            // Use upsertJobScheduler — idempotent across restarts.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- BullMQ's ExtractNameType<T>
+            // constrains the scheduler ID to match job data's `name` field, but we use a plain
+            // string ID. The runtime API accepts any string; the generic constraint is overly
+            // narrow for scheduler IDs.
+            const q = queue;
+            if (schedule.cron) {
+                q.upsertJobScheduler(name, { pattern: schedule.cron, tz: schedule.timezone }, { name });
+            }
+            else if (schedule.every) {
+                q.upsertJobScheduler(name, { every: schedule.every }, { name });
+            }
+            return { worker, queue, registeredName: name };
+        },
+        async cleanupStaleSchedulers(activeNames, registeredNames) {
+            const { Queue } = requireBullMQ();
+            const connection = getConnectionOptions();
+            const activeSet = new Set(activeNames);
+            for (const name of registeredNames) {
+                if (activeSet.has(name))
+                    continue;
+                const queue = new Queue(name, { connection });
+                try {
+                    await queue.removeJobScheduler(name);
+                }
+                catch {
+                    /* scheduler may not exist */
+                }
+                await queue.close();
+            }
+        },
+        createDLQHandler(sourceWorker, sourceQueueName, options) {
+            const { Queue } = requireBullMQ();
+            const connection = getConnectionOptions();
+            const dlqName = `${sourceQueueName}-dlq`;
+            const dlqQueue = new Queue(dlqName, { connection });
+            const maxSize = options?.maxSize ?? 1000;
+            const preserveJobOptions = options?.preserveJobOptions ?? true;
+            sourceWorker.on('failed', async (job, error) => {
+                if (!job)
+                    return;
+                if (job.attemptsMade < (job.opts?.attempts ?? 1))
+                    return;
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- BullMQ's ExtractNameType<T>
+                // constrains job names to literal types from the data shape, but DLQ jobs use
+                // dynamic `dlq:` prefixed names.
+                await dlqQueue.add(`dlq:${job.name}`, job.data, {
+                    ...(preserveJobOptions
+                        ? {
+                            delay: job.opts?.delay,
+                            priority: job.opts?.priority,
+                            attempts: job.opts?.attempts,
+                            backoff: job.opts?.backoff,
+                        }
+                        : {}),
+                    jobId: `dlq:${job.id}`,
+                });
+                if (options?.onDeadLetter) {
+                    try {
+                        await options.onDeadLetter(job, error);
+                    }
+                    catch (e) {
+                        console.error(`[dlq:${sourceQueueName}] onDeadLetter callback error:`, e);
+                    }
+                }
+                const waitingCount = await dlqQueue.getWaitingCount();
+                if (waitingCount > maxSize) {
+                    const excess = waitingCount - maxSize;
+                    const jobs = await dlqQueue.getWaiting(0, excess - 1);
+                    for (const j of jobs) {
+                        await j.remove();
+                    }
+                }
+            });
+            const sourceQueue = new Queue(sourceQueueName, { connection });
+            const retryJob = async (jobId) => {
+                const job = await dlqQueue.getJob(jobId);
+                if (!job)
+                    throw new Error(`Job ${jobId} not found in DLQ`);
+                const retryOptions = preserveJobOptions
+                    ? {
+                        delay: job.opts?.delay,
+                        priority: job.opts?.priority,
+                        attempts: job.opts?.attempts,
+                        backoff: job.opts?.backoff,
+                    }
+                    : {};
+                await sourceQueue.add(job.name, job.data, retryOptions);
+                await job.remove();
+            };
+            return { dlqQueue, retryJob };
+        },
+    };
+}
+export function createQueueFactory(credentials) {
+    const resolvedCredentials = requireQueueRedisCredentials(credentials);
+    const getConnectionOptions = () => getQueueRedisConnectionOptions(resolvedCredentials);
+    return buildQueueHelpers(getConnectionOptions);
+}
+export function createQueue(name, options, credentials) {
+    return createQueueFactory(requireQueueRedisCredentials(credentials)).createQueue(name, options);
+}
+export function createWorker(name, processor, options, credentials) {
+    return createQueueFactory(requireQueueRedisCredentials(credentials)).createWorker(name, processor, options);
+}
+export function createCronWorker(name, processor, schedule, options, credentials) {
+    return createQueueFactory(requireQueueRedisCredentials(credentials)).createCronWorker(name, processor, schedule, options);
+}
+export function cleanupStaleSchedulers(activeNames, registeredNames, credentials) {
+    return createQueueFactory(requireQueueRedisCredentials(credentials)).cleanupStaleSchedulers(activeNames, registeredNames);
+}
+export function createDLQHandler(sourceWorker, sourceQueueName, options, credentials) {
+    return createQueueFactory(requireQueueRedisCredentials(credentials)).createDLQHandler(sourceWorker, sourceQueueName, options);
+}

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

@@ -0,0 +1,28 @@
+import type { default as RedisClass, RedisOptions } from 'ioredis';
+export interface RedisCredentials {
+    /** Redis host:port (e.g., "localhost:6379") */
+    host: string;
+    /** Redis username */
+    user?: string;
+    /** Redis password */
+    password?: string;
+}
+export declare const getRedisConnectionOptions: (creds: RedisCredentials) => RedisOptions;
+/**
+ * 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 declare const connectRedis: (creds: RedisCredentials) => Promise<RedisClass>;
+/**
+ * Gracefully close the Redis connection.
+ * Accepts the client as parameter — no module-level state.
+ */
+export declare const disconnectRedis: (client: RedisClass | null) => Promise<void>;
+/**
+ * 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 declare const getRedisFromApp: (app: object) => RedisClass | null;