@lastshotlabs/bunshot 0.0.20 → 0.0.25

package/dist/index.d.ts

@@ -1,28 +1,34 @@
 export { createApp } from "./app";
 export { createServer } from "./server";
-export type { CreateAppConfig, ModelSchemasConfig, DbConfig, AppMeta, AuthConfig, AuthRateLimitConfig, AccountDeletionConfig, OAuthConfig, SecurityConfig, CsrfConfig, BotProtectionConfig, PrimaryField, EmailVerificationConfig, PasswordResetConfig, RefreshTokenConfig, MfaConfig, MfaEmailOtpConfig, MfaWebAuthnConfig, JobsConfig, TenancyConfig, TenantConfig } from "./app";
+export type { CreateAppConfig, ModelSchemasConfig, DbConfig, AppMeta, AuthConfig, AuthRateLimitConfig, AccountDeletionConfig, OAuthConfig, SecurityConfig, CsrfConfig, BotProtectionConfig, PrimaryField, EmailVerificationConfig, PasswordResetConfig, RefreshTokenConfig, MfaConfig, MfaEmailOtpConfig, MfaWebAuthnConfig, JobsConfig, TenancyConfig, TenantConfig, LoggingConfig, MetricsConfig, ValidationConfig, VersioningConfig, SigningConfig } from "./app";
 export type { PasswordPolicyConfig } from "./lib/appConfig";
 export type { CreateServerConfig, WsConfig } from "./server";
 export { appConnection, authConnection, mongoose, connectMongo, connectAuthMongo, connectAppMongo, disconnectMongo } from "./lib/mongo";
 export { connectRedis, disconnectRedis, getRedis } from "./lib/redis";
 export { getAppRoles } from "./lib/appConfig";
-export { HttpError } from "./lib/HttpError";
-export { COOKIE_TOKEN, HEADER_USER_TOKEN, COOKIE_REFRESH_TOKEN, HEADER_REFRESH_TOKEN, COOKIE_CSRF_TOKEN, HEADER_CSRF_TOKEN } from "./lib/constants";
+export { HttpError, ValidationError } from "./lib/HttpError";
+export { COOKIE_TOKEN, HEADER_USER_TOKEN, COOKIE_REFRESH_TOKEN, HEADER_REFRESH_TOKEN, COOKIE_CSRF_TOKEN, HEADER_CSRF_TOKEN, HEADER_REQUEST_ID, HEADER_IDEMPOTENCY_KEY, HEADER_SIGNATURE, HEADER_TIMESTAMP } from "./lib/constants";
 export { createRouter } from "./lib/context";
-export { createRoute, withSecurity, registerSchema, registerSchemas } from "./lib/createRoute";
+export { createRoute, withSecurity, registerSchema, registerSchemas, setVersionPrefix, clearVersionPrefix } from "./lib/createRoute";
+export { stripUnreferencedSchemas } from "./lib/stripUnreferencedSchemas";
 export { zodToMongoose } from "./lib/zodToMongoose";
 export type { ZodToMongooseConfig, ZodToMongooseRefConfig } from "./lib/zodToMongoose";
 export { createDtoMapper } from "./lib/createDtoMapper";
 export type { DtoMapperConfig } from "./lib/createDtoMapper";
-export type { AppEnv, AppVariables } from "./lib/context";
+export type { AppEnv, AppVariables, ValidationErrorFormatter, DefaultValidationErrorBody, ValidationErrorDetail } from "./lib/context";
+export { defaultValidationErrorFormatter } from "./lib/context";
 export { signToken, verifyToken } from "./lib/jwt";
 export { log } from "./lib/logger";
 export { createResetToken, consumeResetToken, setPasswordResetStore } from "./lib/resetPassword";
+export { createDeletionCancelToken, consumeDeletionCancelToken, setDeletionCancelTokenStore } from "./lib/deletionCancelToken";
 export { timingSafeEqual, sha256 } from "./lib/crypto";
+export { hmacSign, hmacVerify, signCookieValue, verifyCookieValue, signCursor, verifyCursor, createPresignedUrl, verifyPresignedUrl } from "./lib/signing";
+export { idempotent, setIdempotencyStore, clearIdempotencyMemoryStore } from "./lib/idempotency";
+export type { IdempotencyOptions } from "./lib/idempotency";
 export { getClientIp, setTrustProxy } from "./lib/clientIp";
 export { storeOAuthCode, consumeOAuthCode, setOAuthCodeStore } from "./lib/oauthCode";
 export type { OAuthCodePayload } from "./lib/oauthCode";
-export { createSession, getSession, deleteSession, getUserSessions, getActiveSessionCount, evictOldestSession, updateSessionLastActive, setSessionStore, deleteUserSessions, setRefreshToken, getSessionByRefreshToken, rotateRefreshToken } from "./lib/session";
+export { createSession, getSession, deleteSession, getUserSessions, getActiveSessionCount, evictOldestSession, updateSessionLastActive, setSessionStore, deleteUserSessions, setRefreshToken, getSessionByRefreshToken, rotateRefreshToken, getSessionFingerprint, setSessionFingerprint } from "./lib/session";
 export type { SessionMetadata, SessionInfo, RefreshResult } from "./lib/session";
 export { createVerificationToken, getVerificationToken, deleteVerificationToken } from "./lib/emailVerification";
 export { createMfaChallenge, consumeMfaChallenge, replaceMfaChallengeOtp, setMfaChallengeStore, createWebAuthnRegistrationChallenge, consumeWebAuthnRegistrationChallenge, clearMemoryMfaChallenges } from "./lib/mfaChallenge";
@@ -39,10 +45,25 @@ export type { RateLimitOptions } from "./middleware/rateLimit";
 export { userAuth } from "./middleware/userAuth";
 export { requireRole } from "./middleware/requireRole";
 export { requireVerifiedEmail } from "./middleware/requireVerifiedEmail";
+export { requireMfaSetup } from "./middleware/requireMfaSetup";
 export { csrfProtection, refreshCsrfToken, clearCsrfToken } from "./middleware/csrf";
 export type { CsrfMiddlewareOptions } from "./middleware/csrf";
 export { cacheResponse, bustCache, bustCachePattern, setCacheStore, getCacheModel } from "./middleware/cacheResponse";
+export { webhookAuth } from "./middleware/webhookAuth";
+export type { WebhookAuthOptions, WebhookTimestampOptions } from "./middleware/webhookAuth";
+export { requireSignedRequest } from "./middleware/requestSigning";
+export type { RequestSigningOptions } from "./middleware/requestSigning";
+export { auditLog } from "./middleware/auditLog";
+export type { AuditLogMiddlewareOptions } from "./middleware/auditLog";
+export { requestId } from "./middleware/requestId";
+export { requestLogger } from "./middleware/requestLogger";
+export type { RequestLogEntry, RequestLoggerOptions, LogLevel } from "./middleware/requestLogger";
+export { metricsCollector } from "./middleware/metrics";
+export type { MetricsMiddlewareOptions } from "./middleware/metrics";
 export { buildFingerprint } from "./lib/fingerprint";
+export { logAuditEntry, getAuditLogs, clearAuditLogMemoryStore } from "./lib/auditLog";
+export { resetMetrics, incrementCounter, observeHistogram, registerGaugeCallback, serializeMetrics, closeMetricsQueues } from "./lib/metrics";
+export type { AuditLogEntry, AuditLogOptions, AuditLogQuery } from "./lib/auditLog";
 export { sqliteAuthAdapter, setSqliteDb, startSqliteCleanup } from "./adapters/sqliteAuth";
 export { memoryAuthAdapter, clearMemoryStore } from "./adapters/memoryAuth";
 export { setUserRoles, addUserRole, removeUserRole, getTenantRoles, setTenantRoles, addTenantRole, removeTenantRole } from "./lib/roles";
@@ -50,7 +71,28 @@ export type { AuthAdapter, OAuthProfile, WebAuthnCredential } from "./lib/authAd
 export type { OAuthProviderConfig } from "./lib/oauth";
 export { websocket, createWsUpgradeHandler } from "./ws/index";
 export type { SocketData } from "./ws/index";
-export { publish, subscribe, unsubscribe, getSubscriptions, handleRoomActions, getRooms, getRoomSubscribers } from "./lib/ws";
+export { publish, subscribe, unsubscribe, getSubscriptions, handleRoomActions, getRooms, getRoomSubscribers, setPresenceEnabled } from "./lib/ws";
+export { registerSocket, deregisterSocket, handlePong, startHeartbeat, stopHeartbeat, clearHeartbeatState } from "./lib/wsHeartbeat";
+export type { HeartbeatConfig } from "./lib/wsHeartbeat";
+export { trackSocket, untrackSocket, addPresence, removePresence, cleanupPresence, getRoomPresence, getUserPresence, clearPresenceStore } from "./lib/wsPresence";
+export { persistMessage, getMessageHistory, configureRoom, setWsMessageStore, setWsMessageDefaults, clearWsMessageMemoryStore } from "./lib/wsMessages";
+export type { StoredMessage, WsMessageStore, WsMessageDefaults, RoomPersistenceConfig } from "./lib/wsMessages";
 export { createTenant, deleteTenant, getTenant, listTenants } from "./lib/tenant";
 export type { TenantInfo, CreateTenantOptions } from "./lib/tenant";
 export { invalidateTenantCache } from "./middleware/tenant";
+export { createGroup, deleteGroup, getGroup, listGroups, updateGroup, addGroupMember, updateGroupMembership, removeGroupMember, getGroupMembers, getUserGroups, getEffectiveRoles, } from "./lib/groups";
+export type { GroupRecord, GroupMembershipRecord, PaginationOpts, PaginatedResult } from "./lib/groups";
+export type { GroupsConfig, GroupsManagementConfig } from "./routes/groups";
+export { offsetParams, parseOffsetParams, paginatedResponse, cursorParams, parseCursorParams, cursorResponse, maybeSignCursor, } from "./lib/pagination";
+export type { OffsetParamDefaults, ParsedOffsetParams, CursorParamDefaults, ParsedCursorParams, CursorResult, } from "./lib/pagination";
+export { handleUpload } from "./middleware/upload";
+export type { UploadMiddlewareOptions } from "./middleware/upload";
+export { parseUpload, setStorageAdapter, getStorageAdapter, setUploadConfig, getUploadConfig } from "./lib/upload";
+export type { UploadOpts } from "./lib/upload";
+export type { StorageAdapter, UploadResult } from "./lib/storageAdapter";
+export type { UploadConfig, PresignedUrlConfig } from "./app";
+export { memoryStorage, clearMemoryUploadStore } from "./adapters/memoryStorage";
+export { localStorage } from "./adapters/localStorage";
+export type { LocalStorageConfig } from "./adapters/localStorage";
+export { s3Storage } from "./adapters/s3Storage";
+export type { S3StorageConfig } from "./adapters/s3Storage";

package/dist/index.js

@@ -6,19 +6,24 @@ export { appConnection, authConnection, mongoose, connectMongo, connectAuthMongo
 export { connectRedis, disconnectRedis, getRedis } from "./lib/redis";
 // Lib utilities
 export { getAppRoles } from "./lib/appConfig";
-export { HttpError } from "./lib/HttpError";
-export { COOKIE_TOKEN, HEADER_USER_TOKEN, COOKIE_REFRESH_TOKEN, HEADER_REFRESH_TOKEN, COOKIE_CSRF_TOKEN, HEADER_CSRF_TOKEN } from "./lib/constants";
+export { HttpError, ValidationError } from "./lib/HttpError";
+export { COOKIE_TOKEN, HEADER_USER_TOKEN, COOKIE_REFRESH_TOKEN, HEADER_REFRESH_TOKEN, COOKIE_CSRF_TOKEN, HEADER_CSRF_TOKEN, HEADER_REQUEST_ID, HEADER_IDEMPOTENCY_KEY, HEADER_SIGNATURE, HEADER_TIMESTAMP } from "./lib/constants";
 export { createRouter } from "./lib/context";
-export { createRoute, withSecurity, registerSchema, registerSchemas } from "./lib/createRoute";
+export { createRoute, withSecurity, registerSchema, registerSchemas, setVersionPrefix, clearVersionPrefix } from "./lib/createRoute";
+export { stripUnreferencedSchemas } from "./lib/stripUnreferencedSchemas";
 export { zodToMongoose } from "./lib/zodToMongoose";
 export { createDtoMapper } from "./lib/createDtoMapper";
+export { defaultValidationErrorFormatter } from "./lib/context";
 export { signToken, verifyToken } from "./lib/jwt";
 export { log } from "./lib/logger";
 export { createResetToken, consumeResetToken, setPasswordResetStore } from "./lib/resetPassword";
+export { createDeletionCancelToken, consumeDeletionCancelToken, setDeletionCancelTokenStore } from "./lib/deletionCancelToken";
 export { timingSafeEqual, sha256 } from "./lib/crypto";
+export { hmacSign, hmacVerify, signCookieValue, verifyCookieValue, signCursor, verifyCursor, createPresignedUrl, verifyPresignedUrl } from "./lib/signing";
+export { idempotent, setIdempotencyStore, clearIdempotencyMemoryStore } from "./lib/idempotency";
 export { getClientIp, setTrustProxy } from "./lib/clientIp";
 export { storeOAuthCode, consumeOAuthCode, setOAuthCodeStore } from "./lib/oauthCode";
-export { createSession, getSession, deleteSession, getUserSessions, getActiveSessionCount, evictOldestSession, updateSessionLastActive, setSessionStore, deleteUserSessions, setRefreshToken, getSessionByRefreshToken, rotateRefreshToken } from "./lib/session";
+export { createSession, getSession, deleteSession, getUserSessions, getActiveSessionCount, evictOldestSession, updateSessionLastActive, setSessionStore, deleteUserSessions, setRefreshToken, getSessionByRefreshToken, rotateRefreshToken, getSessionFingerprint, setSessionFingerprint } from "./lib/session";
 export { createVerificationToken, getVerificationToken, deleteVerificationToken } from "./lib/emailVerification";
 export { createMfaChallenge, consumeMfaChallenge, replaceMfaChallengeOtp, setMfaChallengeStore, createWebAuthnRegistrationChallenge, consumeWebAuthnRegistrationChallenge, clearMemoryMfaChallenges } from "./lib/mfaChallenge";
 export { bustAuthLimit, trackAttempt, isLimited, clearMemoryRateLimitStore } from "./lib/authRateLimit";
@@ -31,17 +36,42 @@ export { rateLimit } from "./middleware/rateLimit";
 export { userAuth } from "./middleware/userAuth";
 export { requireRole } from "./middleware/requireRole";
 export { requireVerifiedEmail } from "./middleware/requireVerifiedEmail";
+export { requireMfaSetup } from "./middleware/requireMfaSetup";
 export { csrfProtection, refreshCsrfToken, clearCsrfToken } from "./middleware/csrf";
 export { cacheResponse, bustCache, bustCachePattern, setCacheStore, getCacheModel } from "./middleware/cacheResponse";
+export { webhookAuth } from "./middleware/webhookAuth";
+export { requireSignedRequest } from "./middleware/requestSigning";
+export { auditLog } from "./middleware/auditLog";
+export { requestId } from "./middleware/requestId";
+export { requestLogger } from "./middleware/requestLogger";
+export { metricsCollector } from "./middleware/metrics";
 // Lib utilities (bot protection)
 export { buildFingerprint } from "./lib/fingerprint";
+export { logAuditEntry, getAuditLogs, clearAuditLogMemoryStore } from "./lib/auditLog";
+export { resetMetrics, incrementCounter, observeHistogram, registerGaugeCallback, serializeMetrics, closeMetricsQueues } from "./lib/metrics";
 // Models
 export { sqliteAuthAdapter, setSqliteDb, startSqliteCleanup } from "./adapters/sqliteAuth";
 export { memoryAuthAdapter, clearMemoryStore } from "./adapters/memoryAuth";
 export { setUserRoles, addUserRole, removeUserRole, getTenantRoles, setTenantRoles, addTenantRole, removeTenantRole } from "./lib/roles";
 // WebSocket
 export { websocket, createWsUpgradeHandler } from "./ws/index";
-export { publish, subscribe, unsubscribe, getSubscriptions, handleRoomActions, getRooms, getRoomSubscribers } from "./lib/ws";
+export { publish, subscribe, unsubscribe, getSubscriptions, handleRoomActions, getRooms, getRoomSubscribers, setPresenceEnabled } from "./lib/ws";
+// WebSocket — Heartbeat
+export { registerSocket, deregisterSocket, handlePong, startHeartbeat, stopHeartbeat, clearHeartbeatState } from "./lib/wsHeartbeat";
+// WebSocket — Presence
+export { trackSocket, untrackSocket, addPresence, removePresence, cleanupPresence, getRoomPresence, getUserPresence, clearPresenceStore } from "./lib/wsPresence";
+// WebSocket — Message Persistence
+export { persistMessage, getMessageHistory, configureRoom, setWsMessageStore, setWsMessageDefaults, clearWsMessageMemoryStore } from "./lib/wsMessages";
 // Tenancy
 export { createTenant, deleteTenant, getTenant, listTenants } from "./lib/tenant";
 export { invalidateTenantCache } from "./middleware/tenant";
+// Groups
+export { createGroup, deleteGroup, getGroup, listGroups, updateGroup, addGroupMember, updateGroupMembership, removeGroupMember, getGroupMembers, getUserGroups, getEffectiveRoles, } from "./lib/groups";
+// Pagination helpers
+export { offsetParams, parseOffsetParams, paginatedResponse, cursorParams, parseCursorParams, cursorResponse, maybeSignCursor, } from "./lib/pagination";
+// Upload
+export { handleUpload } from "./middleware/upload";
+export { parseUpload, setStorageAdapter, getStorageAdapter, setUploadConfig, getUploadConfig } from "./lib/upload";
+export { memoryStorage, clearMemoryUploadStore } from "./adapters/memoryStorage";
+export { localStorage } from "./adapters/localStorage";
+export { s3Storage } from "./adapters/s3Storage";

package/dist/lib/HttpError.d.ts

@@ -2,3 +2,8 @@ export declare class HttpError extends Error {
     status: number;
     constructor(status: number, message: string);
 }
+import type { ZodIssue } from "zod";
+export declare class ValidationError extends HttpError {
+    readonly issues: ZodIssue[];
+    constructor(issues: ZodIssue[]);
+}

package/dist/lib/HttpError.js

@@ -5,3 +5,10 @@ export class HttpError extends Error {
         this.status = status;
     }
 }
+export class ValidationError extends HttpError {
+    issues;
+    constructor(issues) {
+        super(400, "Validation failed");
+        this.issues = issues;
+    }
+}

package/dist/lib/appConfig.d.ts

@@ -102,6 +102,8 @@ export interface MfaConfig {
     emailOtp?: MfaEmailOtpConfig;
     /** WebAuthn/FIDO2 configuration. When set, enables security key MFA routes. */
     webauthn?: MfaWebAuthnConfig;
+    /** When true, authenticated users must complete MFA setup before accessing non-auth endpoints. Default: false. */
+    required?: boolean;
 }
 export declare const setMfaConfig: (config: MfaConfig | null) => void;
 export declare const getMfaConfig: () => MfaConfig | null;
@@ -114,5 +116,47 @@ export declare const getMfaChallengeTtl: () => number;
 export declare const getMfaEmailOtpConfig: () => MfaEmailOtpConfig | null;
 export declare const getMfaEmailOtpCodeLength: () => number;
 export declare const getMfaWebAuthnConfig: () => MfaWebAuthnConfig | null;
+export declare const getMfaRequired: () => boolean;
 export declare const setCsrfEnabled: (v: boolean) => void;
 export declare const getCsrfEnabled: () => boolean;
+export interface SigningConfig {
+    /**
+     * HMAC secret. Defaults to JWT_SECRET_DEV/JWT_SECRET_PROD 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">;
+        /**
+         * What to do when fingerprint doesn't match.
+         * - "unauthenticate": treat as logged-out (default — graceful but masks attacks)
+         * - "reject": return 401 (strict — recommended for security-conscious apps)
+         * - "log-only": allow through but log the mismatch (useful during rollout)
+         */
+        onMismatch?: "unauthenticate" | "reject" | "log-only";
+    };
+}
+export declare const setSigningConfig: (config: SigningConfig | null) => void;
+export declare const getSigningConfig: () => SigningConfig | null;
+/**
+ * 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 declare const getSigningSecret: () => string | string[] | null;

package/dist/lib/appConfig.js

@@ -59,9 +59,25 @@ 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;
 // ---------------------------------------------------------------------------
 // CSRF config
 // ---------------------------------------------------------------------------
 let _csrfEnabled = false;
 export const setCsrfEnabled = (v) => { _csrfEnabled = v; };
 export const getCsrfEnabled = () => _csrfEnabled;
+let _signingConfig = null;
+export const setSigningConfig = (config) => { _signingConfig = config; };
+export const getSigningConfig = () => _signingConfig;
+/**
+ * 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;
+};

package/dist/lib/auditLog.d.ts

@@ -0,0 +1,52 @@
+import type { Database } from "bun:sqlite";
+export interface AuditLogEntry {
+    id: string;
+    userId: string | null;
+    sessionId: string | null;
+    tenantId: string | null;
+    method: string;
+    path: string;
+    status: number;
+    ip: string | null;
+    userAgent: string | null;
+    action?: string;
+    resource?: string;
+    resourceId?: string;
+    meta?: Record<string, unknown>;
+    requestId?: string;
+    /** ISO 8601 string across all backends. */
+    createdAt: string;
+    /** MongoDB TTL only — silently ignored by SQLite and memory stores. */
+    expiresAt?: Date;
+}
+export type AuditLogStore = "mongo" | "sqlite" | "memory";
+export interface AuditLogOptions {
+    store: AuditLogStore;
+    /** Required when `store === "sqlite"`. */
+    db?: Database;
+}
+export interface AuditLogQuery {
+    userId?: string;
+    tenantId?: string;
+    after?: Date | string;
+    before?: Date | string;
+    /** Default 50, max 200. */
+    limit?: number;
+    /** Default 0. */
+    offset?: number;
+}
+export declare function clearAuditLogMemoryStore(): void;
+/**
+ * Persist an audit log entry to the configured store.
+ * Errors are caught internally — this function never throws, to ensure
+ * storage failures never fail the HTTP request.
+ */
+export declare function logAuditEntry(entry: AuditLogEntry, options: AuditLogOptions): Promise<void>;
+/**
+ * Query audit log entries from the configured store.
+ * Returns `{ items, total }` where `total` is the filtered count before pagination.
+ */
+export declare function getAuditLogs(query: AuditLogQuery, options: AuditLogOptions): Promise<{
+    items: AuditLogEntry[];
+    total: number;
+}>;

package/dist/lib/auditLog.js

@@ -0,0 +1,201 @@
+// ---------------------------------------------------------------------------
+// Memory store
+// ---------------------------------------------------------------------------
+let _auditLogs = [];
+export function clearAuditLogMemoryStore() {
+    _auditLogs = [];
+}
+// ---------------------------------------------------------------------------
+// SQLite helpers
+// ---------------------------------------------------------------------------
+function ensureSqliteTable(db) {
+    // No module-level flag — CREATE IF NOT EXISTS is idempotent and cheap.
+    // A flag would break when multiple Database instances are used (e.g. in tests).
+    db.run(`
+    CREATE TABLE IF NOT EXISTS audit_logs (
+      id         TEXT PRIMARY KEY,
+      userId     TEXT,
+      sessionId  TEXT,
+      tenantId   TEXT,
+      method     TEXT NOT NULL,
+      path       TEXT NOT NULL,
+      status     INTEGER NOT NULL,
+      ip         TEXT,
+      userAgent  TEXT,
+      action     TEXT,
+      resource   TEXT,
+      resourceId TEXT,
+      meta       TEXT,
+      createdAt  TEXT NOT NULL
+    )
+  `);
+    db.run("CREATE INDEX IF NOT EXISTS idx_al_user   ON audit_logs(userId,   createdAt)");
+    db.run("CREATE INDEX IF NOT EXISTS idx_al_tenant ON audit_logs(tenantId, createdAt)");
+    db.run("CREATE INDEX IF NOT EXISTS idx_al_path   ON audit_logs(path)");
+}
+// ---------------------------------------------------------------------------
+// logAuditEntry
+// ---------------------------------------------------------------------------
+/**
+ * Persist an audit log entry to the configured store.
+ * Errors are caught internally — this function never throws, to ensure
+ * storage failures never fail the HTTP request.
+ */
+export async function logAuditEntry(entry, options) {
+    try {
+        if (options.store === "memory") {
+            _auditLogs.push(entry);
+            return;
+        }
+        if (options.store === "sqlite") {
+            const db = options.db;
+            if (!db)
+                throw new Error("AuditLog: store is 'sqlite' but no db instance was provided");
+            ensureSqliteTable(db);
+            db.run(`INSERT INTO audit_logs
+           (id, userId, sessionId, tenantId, method, path, status,
+            ip, userAgent, action, resource, resourceId, meta, createdAt)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+                entry.id,
+                entry.userId ?? null,
+                entry.sessionId ?? null,
+                entry.tenantId ?? null,
+                entry.method,
+                entry.path,
+                entry.status,
+                entry.ip ?? null,
+                entry.userAgent ?? null,
+                entry.action ?? null,
+                entry.resource ?? null,
+                entry.resourceId ?? null,
+                entry.meta !== undefined ? JSON.stringify(entry.meta) : null,
+                entry.createdAt,
+            ]);
+            return;
+        }
+        if (options.store === "mongo") {
+            // Lazy import to avoid bundling mongoose when not used
+            const { AuditLog } = await import("../models/AuditLog");
+            await AuditLog.create({
+                ...entry,
+                createdAt: new Date(entry.createdAt),
+            });
+            return;
+        }
+    }
+    catch (err) {
+        console.error("[auditLog] failed to write entry:", err);
+    }
+}
+// ---------------------------------------------------------------------------
+// getAuditLogs
+// ---------------------------------------------------------------------------
+/**
+ * Query audit log entries from the configured store.
+ * Returns `{ items, total }` where `total` is the filtered count before pagination.
+ */
+export async function getAuditLogs(query, options) {
+    const limit = Math.min(query.limit ?? 50, 200);
+    const offset = query.offset ?? 0;
+    const after = query.after ? new Date(query.after).toISOString() : undefined;
+    const before = query.before ? new Date(query.before).toISOString() : undefined;
+    // --- Memory ---
+    if (options.store === "memory") {
+        let filtered = _auditLogs.slice();
+        if (query.userId !== undefined)
+            filtered = filtered.filter(e => e.userId === query.userId);
+        if (query.tenantId !== undefined)
+            filtered = filtered.filter(e => e.tenantId === query.tenantId);
+        if (after)
+            filtered = filtered.filter(e => e.createdAt >= after);
+        if (before)
+            filtered = filtered.filter(e => e.createdAt < before);
+        return { items: filtered.slice(offset, offset + limit), total: filtered.length };
+    }
+    // --- SQLite ---
+    if (options.store === "sqlite") {
+        const db = options.db;
+        if (!db)
+            throw new Error("AuditLog: store is 'sqlite' but no db instance was provided");
+        ensureSqliteTable(db);
+        const conditions = [];
+        const params = [];
+        if (query.userId !== undefined) {
+            conditions.push("userId = ?");
+            params.push(query.userId);
+        }
+        if (query.tenantId !== undefined) {
+            conditions.push("tenantId = ?");
+            params.push(query.tenantId);
+        }
+        if (after) {
+            conditions.push("createdAt >= ?");
+            params.push(after);
+        }
+        if (before) {
+            conditions.push("createdAt < ?");
+            params.push(before);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+        const { count } = db.query(`SELECT COUNT(*) as count FROM audit_logs ${where}`).get(...params) ?? { count: 0 };
+        const rows = db.query(`SELECT * FROM audit_logs ${where} ORDER BY createdAt DESC LIMIT ? OFFSET ?`).all(...params, limit, offset);
+        const items = rows.map(row => ({
+            id: row.id,
+            userId: row.userId ?? null,
+            sessionId: row.sessionId ?? null,
+            tenantId: row.tenantId ?? null,
+            method: row.method,
+            path: row.path,
+            status: row.status,
+            ip: row.ip ?? null,
+            userAgent: row.userAgent ?? null,
+            action: row.action ?? undefined,
+            resource: row.resource ?? undefined,
+            resourceId: row.resourceId ?? undefined,
+            meta: row.meta ? JSON.parse(row.meta) : undefined,
+            createdAt: row.createdAt,
+        }));
+        return { items, total: count };
+    }
+    // --- MongoDB ---
+    if (options.store === "mongo") {
+        const { AuditLog } = await import("../models/AuditLog");
+        const filter = {};
+        if (query.userId !== undefined)
+            filter.userId = query.userId;
+        if (query.tenantId !== undefined)
+            filter.tenantId = query.tenantId;
+        if (after || before) {
+            filter.createdAt = {
+                ...(after ? { $gte: new Date(after) } : {}),
+                ...(before ? { $lt: new Date(before) } : {}),
+            };
+        }
+        const [total, docs] = await Promise.all([
+            AuditLog.countDocuments(filter),
+            AuditLog.find(filter)
+                .sort({ createdAt: -1 })
+                .skip(offset)
+                .limit(limit)
+                .lean(),
+        ]);
+        const items = docs.map(doc => ({
+            id: doc.id,
+            userId: doc.userId ?? null,
+            sessionId: doc.sessionId ?? null,
+            tenantId: doc.tenantId ?? null,
+            method: doc.method,
+            path: doc.path,
+            status: doc.status,
+            ip: doc.ip ?? null,
+            userAgent: doc.userAgent ?? null,
+            action: doc.action,
+            resource: doc.resource,
+            resourceId: doc.resourceId,
+            meta: doc.meta,
+            createdAt: doc.createdAt.toISOString(),
+        }));
+        return { items, total };
+    }
+    return { items: [], total: 0 };
+}

package/dist/lib/authAdapter.d.ts

@@ -1,3 +1,5 @@
+import type { GroupRecord, GroupMembershipRecord, PaginationOpts, PaginatedResult } from "./groups";
+export type { GroupRecord, GroupMembershipRecord, PaginationOpts, PaginatedResult };
 export interface OAuthProfile {
     email?: string;
     name?: string;
@@ -102,6 +104,73 @@ export interface AuthAdapter {
     updateWebAuthnCredentialSignCount?(userId: string, credentialId: string, signCount: number): Promise<void>;
     /** Optional. Find the user who owns a WebAuthn credential. Returns userId or null. Used for cross-user uniqueness checks. */
     findUserByWebAuthnCredentialId?(credentialId: string): Promise<string | null>;
+    /**
+     * Create a new group. Returns the new group's id.
+     * The name must be a slug (/^[a-z0-9_-]+$/) and unique within its scope.
+     * tenantId: null = app-wide group, string = tenant-scoped group.
+     */
+    createGroup?(group: Omit<GroupRecord, "id" | "createdAt" | "updatedAt">): Promise<{
+        id: string;
+    }>;
+    /**
+     * Delete a group and cascade-delete all its memberships.
+     * Cascade behavior is adapter-specific (MongoDB: manual deleteMany, SQLite: ON DELETE CASCADE).
+     */
+    deleteGroup?(groupId: string): Promise<void>;
+    /** Get a group by ID. Returns null if not found. */
+    getGroup?(groupId: string): Promise<GroupRecord | null>;
+    /**
+     * List groups scoped to a tenant (tenantId string) or app-wide (tenantId null).
+     * Results are paginated (default limit 50, max 200).
+     */
+    listGroups?(tenantId: string | null, opts?: PaginationOpts): Promise<PaginatedResult<GroupRecord>>;
+    /**
+     * Update mutable group fields: name, displayName, description, roles.
+     * tenantId is intentionally excluded — it is immutable after creation.
+     */
+    updateGroup?(groupId: string, updates: Partial<Pick<GroupRecord, "roles" | "name" | "displayName" | "description">>): Promise<void>;
+    /**
+     * Add a user to a group with optional per-membership roles.
+     *
+     * CONTRACT: throws if the user is already a member (unique constraint violation).
+     * All adapters must surface this as a thrown error, not a silent no-op.
+     * Use updateGroupMembership to change roles on an existing membership.
+     */
+    addGroupMember?(groupId: string, userId: string, roles?: string[]): Promise<void>;
+    /**
+     * Update the per-membership roles for an existing group member.
+     * Replaces the member's roles[] in place (not additive).
+     * No updatedAt is tracked — intentional, see GroupMembershipRecord.
+     */
+    updateGroupMembership?(groupId: string, userId: string, roles: string[]): Promise<void>;
+    /** Remove a user from a group. No-op if the user is not a member. */
+    removeGroupMember?(groupId: string, userId: string): Promise<void>;
+    /** List members of a group with their per-membership roles. Paginated. */
+    getGroupMembers?(groupId: string, opts?: PaginationOpts): Promise<PaginatedResult<{
+        userId: string;
+        roles: string[];
+    }>>;
+    /**
+     * List all groups a user belongs to in the given scope, with their per-membership roles.
+     * tenantId = null → app-wide groups; tenantId = string → tenant-scoped groups.
+     */
+    getUserGroups?(userId: string, tenantId: string | null): Promise<Array<{
+        group: GroupRecord;
+        membershipRoles: string[];
+    }>>;
+    /**
+     * Return all roles a user effectively has in the given scope, combining:
+     *   1. Direct roles (app-wide or tenant-scoped)
+     *   2. Group baseline roles (from all groups the user belongs to in that scope)
+     *   3. Per-membership roles (user-specific extras within each group)
+     *
+     * SCOPE CONTRACT (matches requireRole behavior):
+     *   - tenantId = null  → app-wide direct roles + app-wide group roles only
+     *   - tenantId = string → tenant-scoped direct roles + tenant-scoped group roles only
+     *
+     * Tenant-scoped group roles NEVER satisfy app-wide role checks and vice versa.
+     */
+    getEffectiveRoles?(userId: string, tenantId: string | null): Promise<string[]>;
 }
 export declare const setAuthAdapter: (adapter: AuthAdapter) => void;
 export declare const getAuthAdapter: () => AuthAdapter;

package/dist/lib/constants.d.ts

@@ -4,3 +4,7 @@ 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/lib/constants.js

@@ -4,3 +4,7 @@ export const COOKIE_REFRESH_TOKEN = "refresh_token";
 export const HEADER_REFRESH_TOKEN = "x-refresh-token";
 export const COOKIE_CSRF_TOKEN = "csrf_token";
 export const HEADER_CSRF_TOKEN = "x-csrf-token";
+export const HEADER_REQUEST_ID = "x-request-id";
+export const HEADER_IDEMPOTENCY_KEY = "idempotency-key";
+export const HEADER_SIGNATURE = "x-signature";
+export const HEADER_TIMESTAMP = "x-timestamp";