@lastshotlabs/bunshot 0.0.13 → 0.0.18

package/dist/lib/authAdapter.d.ts

@@ -3,6 +3,20 @@ export interface OAuthProfile {
     name?: string;
     avatarUrl?: string;
 }
+export interface WebAuthnCredential {
+    /** Base64url-encoded credential ID. */
+    credentialId: string;
+    /** Base64url-encoded public key. */
+    publicKey: string;
+    /** Counter for signature verification (replay protection). */
+    signCount: number;
+    /** Transport hints from the authenticator (usb, ble, nfc, internal). */
+    transports?: string[];
+    /** User-assigned name for the key (e.g. "YubiKey 5"). */
+    name?: string;
+    /** When the credential was registered (epoch ms). */
+    createdAt: number;
+}
 export interface AuthAdapter {
     findByEmail(email: string): Promise<{
         id: string;
@@ -48,6 +62,46 @@ export interface AuthAdapter {
     setEmailVerified?(userId: string, verified: boolean): Promise<void>;
     /** Optional. Return whether a user's email address has been verified. */
     getEmailVerified?(userId: string): Promise<boolean>;
+    /** Optional. Permanently delete a user account. Used by DELETE /auth/me. */
+    deleteUser?(userId: string): Promise<void>;
+    /** Optional. Check whether a user has a password set (credential account vs OAuth-only). */
+    hasPassword?(userId: string): Promise<boolean>;
+    /** Optional. Store the TOTP secret for MFA setup (encrypted or plaintext, adapter decides). */
+    setMfaSecret?(userId: string, secret: string | null): Promise<void>;
+    /** Optional. Retrieve the TOTP secret for MFA verification. */
+    getMfaSecret?(userId: string): Promise<string | null>;
+    /** Optional. Check whether MFA is enabled for a user. */
+    isMfaEnabled?(userId: string): Promise<boolean>;
+    /** Optional. Enable or disable MFA for a user. */
+    setMfaEnabled?(userId: string, enabled: boolean): Promise<void>;
+    /** Optional. Store hashed recovery codes for MFA. */
+    setRecoveryCodes?(userId: string, codes: string[]): Promise<void>;
+    /** Optional. Retrieve hashed recovery codes for MFA. */
+    getRecoveryCodes?(userId: string): Promise<string[]>;
+    /** Optional. Remove a single recovery code after use. */
+    removeRecoveryCode?(userId: string, code: string): Promise<void>;
+    /** Optional. Get the MFA methods enabled for a user (e.g., ["totp"], ["emailOtp"], ["totp", "emailOtp"]). */
+    getMfaMethods?(userId: string): Promise<string[]>;
+    /** Optional. Set the MFA methods enabled for a user. */
+    setMfaMethods?(userId: string, methods: string[]): Promise<void>;
+    /** Optional. Get roles for a user within a specific tenant. */
+    getTenantRoles?(userId: string, tenantId: string): Promise<string[]>;
+    /** Optional. Set roles for a user within a specific tenant (replaces existing). */
+    setTenantRoles?(userId: string, tenantId: string, roles: string[]): Promise<void>;
+    /** Optional. Add a single role to a user within a specific tenant. */
+    addTenantRole?(userId: string, tenantId: string, role: string): Promise<void>;
+    /** Optional. Remove a single role from a user within a specific tenant. */
+    removeTenantRole?(userId: string, tenantId: string, role: string): Promise<void>;
+    /** Optional. Get all WebAuthn credentials for a user. */
+    getWebAuthnCredentials?(userId: string): Promise<WebAuthnCredential[]>;
+    /** Optional. Add a WebAuthn credential for a user. */
+    addWebAuthnCredential?(userId: string, credential: WebAuthnCredential): Promise<void>;
+    /** Optional. Remove a WebAuthn credential by its credential ID. */
+    removeWebAuthnCredential?(userId: string, credentialId: string): Promise<void>;
+    /** Optional. Update the sign count for a WebAuthn credential after successful authentication. */
+    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>;
 }
 export declare const setAuthAdapter: (adapter: AuthAdapter) => void;
 export declare const getAuthAdapter: () => AuthAdapter;

package/dist/lib/authRateLimit.d.ts

@@ -9,3 +9,5 @@ export declare const isLimited: (key: string, opts: LimitOpts) => Promise<boolea
 export declare const trackAttempt: (key: string, opts: LimitOpts) => Promise<boolean>;
 /** Resets a rate limit key. Use on login success or for admin unlock. */
 export declare const bustAuthLimit: (key: string) => Promise<void>;
+/** Clears all in-memory rate limit entries. Called by clearMemoryStore(). */
+export declare const clearMemoryRateLimitStore: () => void;

package/dist/lib/authRateLimit.js

@@ -75,3 +75,7 @@ export const trackAttempt = async (key, opts) => {
 export const bustAuthLimit = async (key) => {
     await _store.delete(key);
 };
+/** Clears all in-memory rate limit entries. Called by clearMemoryStore(). */
+export const clearMemoryRateLimitStore = () => {
+    _memoryStore.clear();
+};

package/dist/lib/clientIp.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from "hono";
+export declare const setTrustProxy: (value: false | number) => void;
+/**
+ * Returns the client IP address, respecting the `trustProxy` setting.
+ *
+ * - When `trustProxy` is `false`: returns the socket-level IP (via Bun's
+ *   `server.requestIP()`), ignoring `X-Forwarded-For` entirely.
+ * - When `trustProxy` is a number N: takes the Nth-from-right entry in the
+ *   `X-Forwarded-For` chain (skipping N trusted proxy hops), falling back to
+ *   the socket-level IP.
+ *
+ * Returns `"unknown"` if no IP can be determined.
+ */
+export declare const getClientIp: (c: Context<any>) => string;

package/dist/lib/clientIp.js

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// Trust-proxy configuration (set once at startup via setTrustProxy)
+// ---------------------------------------------------------------------------
+let _trustProxy = false;
+export const setTrustProxy = (value) => {
+    _trustProxy = value;
+};
+// ---------------------------------------------------------------------------
+// Centralized client IP extraction
+// ---------------------------------------------------------------------------
+/**
+ * Returns the client IP address, respecting the `trustProxy` setting.
+ *
+ * - When `trustProxy` is `false`: returns the socket-level IP (via Bun's
+ *   `server.requestIP()`), ignoring `X-Forwarded-For` entirely.
+ * - When `trustProxy` is a number N: takes the Nth-from-right entry in the
+ *   `X-Forwarded-For` chain (skipping N trusted proxy hops), falling back to
+ *   the socket-level IP.
+ *
+ * Returns `"unknown"` if no IP can be determined.
+ */
+export const getClientIp = (c) => {
+    // Socket-level IP via Bun's server (passed as c.env by Bun.serve)
+    let socketIp;
+    try {
+        const server = c.env;
+        if (server?.requestIP) {
+            const info = server.requestIP(c.req.raw);
+            if (info)
+                socketIp = info.address;
+        }
+    }
+    catch { /* not running under Bun.serve — e.g. test environment */ }
+    if (_trustProxy === false) {
+        return socketIp ?? "unknown";
+    }
+    // Trust N proxy hops: take the Nth-from-right in XFF
+    const xff = c.req.header("x-forwarded-for");
+    if (xff) {
+        const ips = xff.split(",").map(s => s.trim()).filter(Boolean);
+        // Index from the right: trustProxy=1 means 1 proxy, so take ips[length - 2]
+        const idx = ips.length - _trustProxy - 1;
+        if (idx >= 0 && ips[idx]) {
+            return ips[idx];
+        }
+        // If fewer entries than expected, fall back to leftmost (or socket IP)
+        if (ips.length > 0)
+            return ips[0];
+    }
+    // Fallback: X-Real-IP header, then socket IP
+    return c.req.header("x-real-ip") ?? socketIp ?? "unknown";
+};

package/dist/lib/constants.d.ts

@@ -1,2 +1,6 @@
 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";

package/dist/lib/constants.js

@@ -1,2 +1,6 @@
 export const COOKIE_TOKEN = "token";
 export const HEADER_USER_TOKEN = "x-user-token";
+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";

package/dist/lib/context.d.ts

@@ -3,6 +3,8 @@ export type AppVariables = {
     authUserId: string | null;
     roles: string[] | null;
     sessionId: string | null;
+    tenantId: string | null;
+    tenantConfig: Record<string, unknown> | null;
 };
 export type AppEnv = {
     Variables: AppVariables;

package/dist/lib/createDtoMapper.d.ts

@@ -0,0 +1,33 @@
+type ZodSchema = any;
+export type DtoMapperConfig = {
+    /** DB field name → API field name for ObjectId refs (e.g., { account: "accountId" }) */
+    refs?: Record<string, string>;
+    /** API field names that are Date in DB, string in DTO */
+    dates?: string[];
+    /** Subdocument array fields mapped with a sub-mapper: { items: itemMapper } */
+    subdocs?: Record<string, (item: any) => any>;
+};
+/**
+ * Create a toDto mapper function from a Zod schema.
+ *
+ * The Zod schema defines which fields exist in the DTO. The config declares
+ * how to transform DB-specific types (ObjectId refs, Dates, subdocuments).
+ *
+ * Handles automatically:
+ * - `_id` → `id` (toString)
+ * - ObjectId refs → string (toString), with field renaming via `refs`
+ * - Date fields → ISO string via `dates`
+ * - Subdocument arrays via `subdocs`
+ * - Nullable/optional fields → `null` coercion (from `undefined`)
+ * - All other fields → passthrough
+ *
+ * @example
+ * ```ts
+ * const toDto = createDtoMapper<LedgerItemDto>(LedgerItemSchema, {
+ *   refs: { account: "accountId" },
+ *   dates: ["date"],
+ * });
+ * ```
+ */
+export declare function createDtoMapper<TDto>(zodSchema: ZodSchema, config?: DtoMapperConfig): (doc: any) => TDto;
+export {};

package/dist/lib/createDtoMapper.js

@@ -0,0 +1,69 @@
+/** Check if a Zod type is nullable or optional */
+function isNullable(zodType) {
+    const defType = zodType?._zod?.def?.type;
+    if (defType === "nullable")
+        return true;
+    if (defType === "optional")
+        return true;
+    if (defType === "default")
+        return isNullable(zodType._zod.def.innerType);
+    return false;
+}
+/**
+ * Create a toDto mapper function from a Zod schema.
+ *
+ * The Zod schema defines which fields exist in the DTO. The config declares
+ * how to transform DB-specific types (ObjectId refs, Dates, subdocuments).
+ *
+ * Handles automatically:
+ * - `_id` → `id` (toString)
+ * - ObjectId refs → string (toString), with field renaming via `refs`
+ * - Date fields → ISO string via `dates`
+ * - Subdocument arrays via `subdocs`
+ * - Nullable/optional fields → `null` coercion (from `undefined`)
+ * - All other fields → passthrough
+ *
+ * @example
+ * ```ts
+ * const toDto = createDtoMapper<LedgerItemDto>(LedgerItemSchema, {
+ *   refs: { account: "accountId" },
+ *   dates: ["date"],
+ * });
+ * ```
+ */
+export function createDtoMapper(zodSchema, config = {}) {
+    const apiFields = Object.keys(zodSchema.shape);
+    const shape = zodSchema.shape;
+    // Build reverse lookup: apiField → dbField for refs
+    const refByApiField = new Map();
+    if (config.refs) {
+        for (const [dbField, apiField] of Object.entries(config.refs)) {
+            refByApiField.set(apiField, dbField);
+        }
+    }
+    const dateSet = new Set(config.dates ?? []);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return (doc) => {
+        const dto = {};
+        for (const field of apiFields) {
+            if (field === "id") {
+                dto.id = doc._id.toString();
+                continue;
+            }
+            if (refByApiField.has(field)) {
+                dto[field] = doc[refByApiField.get(field)].toString();
+                continue;
+            }
+            if (dateSet.has(field)) {
+                dto[field] = doc[field].toISOString();
+                continue;
+            }
+            if (config.subdocs?.[field]) {
+                dto[field] = (doc[field] ?? []).map(config.subdocs[field]);
+                continue;
+            }
+            dto[field] = isNullable(shape[field]) ? (doc[field] ?? null) : doc[field];
+        }
+        return dto;
+    };
+}

package/dist/lib/crypto.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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;

package/dist/lib/crypto.js

@@ -0,0 +1,22 @@
+import { createHash, timingSafeEqual as nodeTimingSafeEqual } 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");
+}

package/dist/lib/emailVerification.d.ts

@@ -1,9 +1,13 @@
 type VerificationStore = "redis" | "mongo" | "sqlite" | "memory";
 export declare const setEmailVerificationStore: (store: VerificationStore) => void;
+/** Create a verification token. Returns the raw token (for the email link).
+ *  Only the SHA-256 hash is persisted in the store. */
 export declare const createVerificationToken: (userId: string, email: string) => Promise<string>;
+/** Look up a verification token by its raw value. Hashes before lookup. */
 export declare const getVerificationToken: (token: string) => Promise<{
     userId: string;
     email: string;
 } | null>;
+/** Delete a verification token by its raw value. Hashes before lookup. */
 export declare const deleteVerificationToken: (token: string) => Promise<void>;
 export {};

package/dist/lib/emailVerification.js

@@ -1,6 +1,7 @@
 import { getRedis } from "./redis";
 import { appConnection, mongoose } from "./mongo";
 import { getAppName, getTokenExpiry } from "./appConfig";
+import { sha256 } from "./crypto";
 import { sqliteCreateVerificationToken, sqliteGetVerificationToken, sqliteDeleteVerificationToken, } from "../adapters/sqliteAuth";
 import { memoryCreateVerificationToken, memoryGetVerificationToken, memoryDeleteVerificationToken, } from "../adapters/memoryAuth";
 function getVerificationModel() {
@@ -20,59 +21,66 @@ export const setEmailVerificationStore = (store) => { _store = store; };
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
+/** Create a verification token. Returns the raw token (for the email link).
+ *  Only the SHA-256 hash is persisted in the store. */
 export const createVerificationToken = async (userId, email) => {
     const token = crypto.randomUUID();
+    const hash = sha256(token);
     const ttl = getTokenExpiry();
     if (_store === "memory") {
-        memoryCreateVerificationToken(token, userId, email, ttl);
+        memoryCreateVerificationToken(hash, userId, email, ttl);
         return token;
     }
     if (_store === "sqlite") {
-        sqliteCreateVerificationToken(token, userId, email, ttl);
+        sqliteCreateVerificationToken(hash, userId, email, ttl);
         return token;
     }
     if (_store === "mongo") {
         await getVerificationModel().create({
-            token,
+            token: hash,
             userId,
             email,
             expiresAt: new Date(Date.now() + ttl * 1000),
         });
         return token;
     }
-    await getRedis().set(`verify:${getAppName()}:${token}`, JSON.stringify({ userId, email }), "EX", ttl);
+    await getRedis().set(`verify:${getAppName()}:${hash}`, JSON.stringify({ userId, email }), "EX", ttl);
     return token;
 };
+/** Look up a verification token by its raw value. Hashes before lookup. */
 export const getVerificationToken = async (token) => {
+    const hash = sha256(token);
     if (_store === "memory")
-        return memoryGetVerificationToken(token);
+        return memoryGetVerificationToken(hash);
     if (_store === "sqlite")
-        return sqliteGetVerificationToken(token);
+        return sqliteGetVerificationToken(hash);
     if (_store === "mongo") {
         const doc = await getVerificationModel()
-            .findOne({ token, expiresAt: { $gt: new Date() } })
+            .findOne({ token: hash, expiresAt: { $gt: new Date() } })
             .lean();
         if (!doc)
             return null;
         return { userId: doc.userId, email: doc.email };
     }
-    const raw = await getRedis().get(`verify:${getAppName()}:${token}`);
+    const raw = await getRedis().get(`verify:${getAppName()}:${hash}`);
     if (!raw)
         return null;
     return JSON.parse(raw);
 };
+/** Delete a verification token by its raw value. Hashes before lookup. */
 export const deleteVerificationToken = async (token) => {
+    const hash = sha256(token);
     if (_store === "memory") {
-        memoryDeleteVerificationToken(token);
+        memoryDeleteVerificationToken(hash);
         return;
     }
     if (_store === "sqlite") {
-        sqliteDeleteVerificationToken(token);
+        sqliteDeleteVerificationToken(hash);
         return;
     }
     if (_store === "mongo") {
-        await getVerificationModel().deleteOne({ token });
+        await getVerificationModel().deleteOne({ token: hash });
         return;
     }
-    await getRedis().del(`verify:${getAppName()}:${token}`);
+    await getRedis().del(`verify:${getAppName()}:${hash}`);
 };

package/dist/lib/jwt.d.ts

@@ -1,2 +1,2 @@
-export declare const signToken: (userId: string, sessionId: string) => Promise<string>;
+export declare const signToken: (userId: string, sessionId: string, expirySeconds?: number) => Promise<string>;
 export declare const verifyToken: (token: string) => Promise<import("jose").JWTPayload>;

package/dist/lib/jwt.js

@@ -1,11 +1,24 @@
 import { SignJWT, jwtVerify } from "jose";
-const isProd = process.env.NODE_ENV === "production";
-const secret = new TextEncoder().encode(isProd ? process.env.JWT_SECRET_PROD : process.env.JWT_SECRET_DEV);
-export const signToken = async (userId, sessionId) => new SignJWT({ sub: userId, sid: sessionId })
+let _secret = null;
+function getSecret() {
+    if (_secret)
+        return _secret;
+    const isProd = process.env.NODE_ENV === "production";
+    const envKey = isProd ? "JWT_SECRET_PROD" : "JWT_SECRET_DEV";
+    const rawSecret = process.env[envKey];
+    if (!rawSecret || rawSecret.length < 32) {
+        throw new Error(`[security] ${envKey} is missing or too short (${rawSecret?.length ?? 0} chars). ` +
+            `JWT secrets must be at least 32 characters. Generate one with: ` +
+            `node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"`);
+    }
+    _secret = new TextEncoder().encode(rawSecret);
+    return _secret;
+}
+export const signToken = async (userId, sessionId, expirySeconds) => new SignJWT({ sub: userId, sid: sessionId })
     .setProtectedHeader({ alg: "HS256" })
-    .setExpirationTime("7d")
-    .sign(secret);
+    .setExpirationTime(expirySeconds ? `${expirySeconds}s` : "7d")
+    .sign(getSecret());
 export const verifyToken = async (token) => {
-    const { payload } = await jwtVerify(token, secret);
+    const { payload } = await jwtVerify(token, getSecret());
     return payload;
 };

package/dist/lib/mfaChallenge.d.ts

@@ -0,0 +1,42 @@
+export type MfaChallengePurpose = "login" | "webauthn-registration";
+export interface MfaChallengeOptions {
+    emailOtpHash?: string;
+    webauthnChallenge?: string;
+}
+export interface MfaChallengeData {
+    userId: string;
+    purpose: MfaChallengePurpose;
+    emailOtpHash?: string;
+    webauthnChallenge?: string;
+}
+/** Reset all in-memory MFA challenge state. Called by clearMemoryStore(). */
+export declare const clearMemoryMfaChallenges: () => void;
+/** Must be called when store is "sqlite" to inject the db instance. */
+export declare const setMfaChallengeSqliteDb: (db: any) => void;
+type MfaChallengeStore = "redis" | "mongo" | "sqlite" | "memory";
+export declare const setMfaChallengeStore: (store: MfaChallengeStore) => void;
+export declare const createMfaChallenge: (userId: string, options?: MfaChallengeOptions) => Promise<string>;
+export declare const consumeMfaChallenge: (token: string) => Promise<MfaChallengeData | null>;
+/**
+ * Replace the email OTP hash on an existing challenge without consuming it.
+ * Used for the resend flow. Increments resendCount and caps the challenge lifetime.
+ * Returns { userId, resendCount } on success, null if challenge not found/expired/max resends reached.
+ */
+export declare const replaceMfaChallengeOtp: (token: string, newEmailOtpHash: string) => Promise<{
+    userId: string;
+    resendCount: number;
+} | null>;
+/**
+ * Create a WebAuthn registration challenge token. Separate from the login flow —
+ * uses `purpose: "webauthn-registration"` so it cannot be consumed by `consumeMfaChallenge`.
+ */
+export declare const createWebAuthnRegistrationChallenge: (userId: string, challenge: string) => Promise<string>;
+/**
+ * Consume a WebAuthn registration challenge token.
+ * Only accepts tokens with `purpose: "webauthn-registration"`.
+ */
+export declare const consumeWebAuthnRegistrationChallenge: (token: string) => Promise<{
+    userId: string;
+    challenge: string;
+} | null>;
+export {};