@lastshotlabs/bunshot 0.0.21 → 0.0.27

package/dist/lib/authRateLimit.js

@@ -20,10 +20,34 @@ const memoryStore = {
     async delete(key) {
         _memoryStore.delete(key);
     },
+    // No increment — memory store uses the read-modify-write fallback (single-process, acceptable)
 };
 // ---------------------------------------------------------------------------
 // Redis implementation
 // ---------------------------------------------------------------------------
+// Lua script: atomically read + increment + write JSON entry, preserving { count, resetAt } format.
+// Returns the new count as a number.
+const TRACK_SCRIPT = `
+local key = KEYS[1]
+local windowMs = tonumber(ARGV[1])
+local now = tonumber(ARGV[2])
+local raw = redis.call("GET", key)
+local count, resetAt
+
+if raw then
+  local entry = cjson.decode(raw)
+  count = entry.count + 1
+  resetAt = entry.resetAt
+else
+  count = 1
+  resetAt = now + windowMs
+end
+
+local ttl = math.max(1, resetAt - now)
+local payload = cjson.encode({count = count, resetAt = resetAt})
+redis.call("SET", key, payload, "PX", ttl)
+return count
+`;
 const redisStore = {
     async get(key) {
         const { getRedis } = await import("./redis");
@@ -43,6 +67,13 @@ const redisStore = {
         const { getRedis } = await import("./redis");
         await getRedis().del(`rl:${getAppName()}:${key}`);
     },
+    async increment(key, windowMs) {
+        const { getRedis } = await import("./redis");
+        const fullKey = `rl:${getAppName()}:${key}`;
+        const now = Date.now();
+        const count = await getRedis().eval(TRACK_SCRIPT, 1, fullKey, windowMs, now);
+        return count;
+    },
 };
 // ---------------------------------------------------------------------------
 // Active store + setter
@@ -60,6 +91,11 @@ export const isLimited = async (key, opts) => {
 };
 /** Increments the counter and returns true if now over the limit. */
 export const trackAttempt = async (key, opts) => {
+    if (_store.increment) {
+        const count = await _store.increment(key, opts.windowMs);
+        return count >= opts.max;
+    }
+    // Read-modify-write fallback for memory store (single-process — no lost increments)
     const now = Date.now();
     const existing = await _store.get(key);
     if (!existing) {

package/dist/lib/breachedPassword.d.ts

@@ -0,0 +1,13 @@
+import type { BreachedPasswordConfig } from "./appConfig";
+export type { BreachedPasswordConfig };
+/**
+ * Check whether a password has appeared in a data breach using the
+ * HaveIBeenPwned k-Anonymity API.
+ *
+ * Sends only the first 5 hex chars of the SHA-1 hash — the full hash
+ * never leaves the server.
+ */
+export declare function checkBreachedPassword(password: string, config?: BreachedPasswordConfig): Promise<{
+    breached: boolean;
+    count: number;
+}>;

package/dist/lib/breachedPassword.js

@@ -0,0 +1,48 @@
+/**
+ * Check whether a password has appeared in a data breach using the
+ * HaveIBeenPwned k-Anonymity API.
+ *
+ * Sends only the first 5 hex chars of the SHA-1 hash — the full hash
+ * never leaves the server.
+ */
+export async function checkBreachedPassword(password, config) {
+    const timeout = config?.timeout ?? 3000;
+    const minCount = config?.minBreachCount ?? 1;
+    // SHA-1 the password
+    const encoder = new TextEncoder();
+    const data = encoder.encode(password);
+    const hashBuffer = await crypto.subtle.digest("SHA-1", data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    const hashHex = hashArray.map((b) => b.toString(16).padStart(2, "0")).join("").toUpperCase();
+    const prefix = hashHex.slice(0, 5);
+    const suffix = hashHex.slice(5);
+    let responseText;
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout);
+        const res = await fetch(`https://api.pwnedpasswords.com/range/${prefix}`, {
+            signal: controller.signal,
+            headers: { "Add-Padding": "true" },
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            throw new Error(`HIBP API returned ${res.status}`);
+        responseText = await res.text();
+    }
+    catch {
+        // API failure — apply onApiFailure policy
+        if (config?.onApiFailure === "block") {
+            return { breached: true, count: -1 };
+        }
+        return { breached: false, count: 0 };
+    }
+    // Parse response: each line is "SUFFIX:COUNT"
+    for (const line of responseText.split("\n")) {
+        const [lineSuffix, countStr] = line.trim().split(":");
+        if (lineSuffix === suffix) {
+            const count = parseInt(countStr, 10);
+            return { breached: count >= minCount, count };
+        }
+    }
+    return { breached: false, count: 0 };
+}

package/dist/lib/captcha.d.ts

@@ -0,0 +1,25 @@
+export type CaptchaProvider = "recaptcha" | "hcaptcha" | "turnstile";
+export interface CaptchaConfig {
+    provider: CaptchaProvider;
+    secretKey: string;
+    /** Minimum score for reCAPTCHA v3. Default: 0.5. Ignored for v2/hcaptcha/turnstile. */
+    minScore?: number;
+    /** Body field name containing the CAPTCHA token. Default: "captcha-token". */
+    tokenField?: string;
+    /** When true, only require CAPTCHA after rate limit threshold is hit. Default: false. */
+    adaptive?: boolean;
+    /** Rate limit window for adaptive mode. */
+    adaptiveThreshold?: {
+        windowMs: number;
+        max: number;
+    };
+}
+/**
+ * Verify a CAPTCHA token with the provider's API.
+ * Returns { success: true } on pass, { success: false, error } on fail.
+ */
+export declare function verifyCaptcha(token: string, config: CaptchaConfig, ip?: string): Promise<{
+    success: boolean;
+    score?: number;
+    error?: string;
+}>;

package/dist/lib/captcha.js

@@ -0,0 +1,37 @@
+const VERIFY_URLS = {
+    recaptcha: "https://www.google.com/recaptcha/api/siteverify",
+    hcaptcha: "https://hcaptcha.com/siteverify",
+    turnstile: "https://challenges.cloudflare.com/turnstile/v0/siteverify",
+};
+/**
+ * Verify a CAPTCHA token with the provider's API.
+ * Returns { success: true } on pass, { success: false, error } on fail.
+ */
+export async function verifyCaptcha(token, config, ip) {
+    const url = VERIFY_URLS[config.provider];
+    const body = new URLSearchParams({ secret: config.secretKey, response: token });
+    if (ip)
+        body.set("remoteip", ip);
+    let data;
+    try {
+        const res = await fetch(url, { method: "POST", body });
+        if (!res.ok)
+            return { success: false, error: `Provider returned ${res.status}` };
+        data = await res.json();
+    }
+    catch (err) {
+        return { success: false, error: "CAPTCHA provider unreachable" };
+    }
+    if (!data.success) {
+        return { success: false, error: String(data["error-codes"]?.[0] ?? "invalid-token") };
+    }
+    // reCAPTCHA v3: check score
+    if (config.provider === "recaptcha" && typeof data.score === "number") {
+        const minScore = config.minScore ?? 0.5;
+        if (data.score < minScore) {
+            return { success: false, score: data.score, error: "score-too-low" };
+        }
+        return { success: true, score: data.score };
+    }
+    return { success: true };
+}

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";

package/dist/lib/context.d.ts

@@ -1,12 +1,35 @@
-import { OpenAPIHono } from "@hono/zod-openapi";
+import { OpenAPIHono, type Hook } from "@hono/zod-openapi";
+import type { ZodIssue } from "zod";
+import type { JWTPayload } from "jose";
+import type { UploadResult } from "./storageAdapter";
+export interface ValidationErrorDetail {
+    path: string;
+    message: string;
+}
+export interface DefaultValidationErrorBody {
+    error: string;
+    details: ValidationErrorDetail[];
+    requestId: string;
+}
+export type ValidationErrorFormatter = (issues: ZodIssue[], requestId: string) => unknown;
+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;
+    uploadResults: UploadResult[] | null;
+    uploadBucket: string | undefined;
+    /** Set by identify when a scope-bearing M2M token (no sid) is verified. */
+    authClientId: string | null;
+    /** Raw verified JWT payload stashed by identify for downstream middleware. Null when unauthenticated. */
+    tokenPayload: JWTPayload | null;
 };
 export type AppEnv = {
     Variables: AppVariables;
 };
+export declare const defaultHook: Hook<any, AppEnv, any, any>;
 export declare const createRouter: () => OpenAPIHono<AppEnv, {}, "/">;

package/dist/lib/context.js

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

package/dist/lib/createRoute.d.ts

@@ -1,5 +1,27 @@
 import type { RouteConfig } from "@hono/zod-openapi";
 import type { ZodType } from "zod";
+/**
+ * Sets the active version prefix for schema name generation and creates a unique
+ * Symbol token for interleaving detection. Call before importing a version's route files.
+ */
+export declare function setVersionPrefix(version: string): void;
+/**
+ * Clears the active version prefix and token. Call after each version's route files
+ * have been fully imported.
+ */
+export declare function clearVersionPrefix(): void;
+/** Returns the current version token for assertion after import. */
+export declare function getVersionToken(): symbol | null;
+/**
+ * Drains and returns all tokens captured by createRoute() calls since the last drain.
+ * Used by versioned route discovery to detect interleaving.
+ */
+export declare function drainCapturedTokens(): (symbol | null)[];
+/**
+ * Asserts that all tokens in the array match the expected token.
+ * Throws a clear startup error if any mismatch is detected.
+ */
+export declare function assertCapturedTokens(tokens: (symbol | null)[], expectedToken: symbol | null): void;
 /**
  * Registers a Zod schema as a named entry in `components/schemas`.
  *
@@ -53,9 +75,13 @@ export declare const withSecurity: <T extends RouteConfig>(route: T, ...schemes:
  * OpenAPI components so they appear in `components/schemas` instead of being
  * inlined at every use site. Generated names follow the convention:
  *
- *   {Method}{PathSegments}Body         — request body
- *   {Method}{PathSegments}{StatusCode} — response body
+ *   {Version}{Method}{PathSegments}Request — request body (when versioning is active)
+ *   {Version}{Method}{PathSegments}{Status} — response body (when versioning is active)
  *
  * Schemas already named via `.openapi("Name")` are never overwritten.
+ *
+ * When `setVersionPrefix` has been called, the version prefix is prepended to all
+ * generated schema names and the current version token is captured for interleaving
+ * detection via `drainCapturedTokens()` / `assertCapturedTokens()`.
  */
 export declare const createRoute: <T extends RouteConfig>(config: T) => T;

package/dist/lib/createRoute.js

@@ -1,5 +1,50 @@
 import { createRoute as _createRoute } from "@hono/zod-openapi";
 import { getRefId, zodToOpenAPIRegistry } from "@asteasolutions/zod-to-openapi";
+// ---------------------------------------------------------------------------
+// Version prefix state — set once per version batch before importing route files
+// ---------------------------------------------------------------------------
+let _versionPrefix = "";
+let _versionToken = null;
+/** Tokens captured by createRoute() calls since the last drainCapturedTokens() call. */
+const _capturedTokens = [];
+/**
+ * Sets the active version prefix for schema name generation and creates a unique
+ * Symbol token for interleaving detection. Call before importing a version's route files.
+ */
+export function setVersionPrefix(version) {
+    _versionPrefix = version.charAt(0).toUpperCase() + version.slice(1);
+    _versionToken = Symbol(version);
+}
+/**
+ * Clears the active version prefix and token. Call after each version's route files
+ * have been fully imported.
+ */
+export function clearVersionPrefix() {
+    _versionPrefix = "";
+    _versionToken = null;
+}
+/** Returns the current version token for assertion after import. */
+export function getVersionToken() {
+    return _versionToken;
+}
+/**
+ * Drains and returns all tokens captured by createRoute() calls since the last drain.
+ * Used by versioned route discovery to detect interleaving.
+ */
+export function drainCapturedTokens() {
+    return _capturedTokens.splice(0);
+}
+/**
+ * Asserts that all tokens in the array match the expected token.
+ * Throws a clear startup error if any mismatch is detected.
+ */
+export function assertCapturedTokens(tokens, expectedToken) {
+    for (const tok of tokens) {
+        if (tok !== expectedToken) {
+            throw new Error("Route file imported with wrong version prefix — avoid unbounded top-level await in versioned route files");
+        }
+    }
+}
 const STATUS_SUFFIX = {
     "200": "Response",
     "201": "Response",
@@ -128,13 +173,19 @@ export const withSecurity = (route, ...schemes) => Object.assign(route, { securi
  * OpenAPI components so they appear in `components/schemas` instead of being
  * inlined at every use site. Generated names follow the convention:
  *
- *   {Method}{PathSegments}Body         — request body
- *   {Method}{PathSegments}{StatusCode} — response body
+ *   {Version}{Method}{PathSegments}Request — request body (when versioning is active)
+ *   {Version}{Method}{PathSegments}{Status} — response body (when versioning is active)
  *
  * Schemas already named via `.openapi("Name")` are never overwritten.
+ *
+ * When `setVersionPrefix` has been called, the version prefix is prepended to all
+ * generated schema names and the current version token is captured for interleaving
+ * detection via `drainCapturedTokens()` / `assertCapturedTokens()`.
  */
 export const createRoute = (config) => {
-    const base = toBaseName(config.method, config.path);
+    const base = (_versionPrefix ? `${_versionPrefix}` : "") + toBaseName(config.method, config.path);
+    // Capture the current version token for interleaving detection
+    _capturedTokens.push(_versionToken);
     // Auto-name the JSON request body schema if present and unnamed
     const bodySchema = config.request?.body?.content?.["application/json"]?.schema;
     maybeRegister(bodySchema, `${base}Request`);

package/dist/lib/credentialStuffing.d.ts

@@ -0,0 +1,31 @@
+export interface CredentialStuffingConfig {
+    /** Block when an IP attempts login against this many distinct accounts. Default: 5 per 15 min. */
+    maxAccountsPerIp?: {
+        count: number;
+        windowMs: number;
+    };
+    /** Block when an account is attempted from this many distinct IPs. Default: 10 per 15 min. */
+    maxIpsPerAccount?: {
+        count: number;
+        windowMs: number;
+    };
+    /** Called when stuffing is detected. Non-blocking, errors swallowed. */
+    onDetected?: (signal: {
+        type: "ip" | "account";
+        key: string;
+        count: number;
+    }) => void;
+}
+export declare function setCredentialStuffingConfig(config: CredentialStuffingConfig | null): void;
+export declare function getCredentialStuffingConfig(): CredentialStuffingConfig | null;
+/**
+ * Track a failed login attempt. Call this AFTER confirming the login failed.
+ */
+export declare function trackFailedLogin(ip: string, identifier: string): void;
+/**
+ * Check whether this login attempt should be blocked.
+ * Call this BEFORE verifying credentials.
+ */
+export declare function isStuffingBlocked(ip: string, identifier: string): boolean;
+/** Clear the in-memory store (for testing). */
+export declare function clearCredentialStuffingStore(): void;

package/dist/lib/credentialStuffing.js

@@ -0,0 +1,77 @@
+// In-memory store: key → BoundedSet
+const _store = new Map();
+function cleanExpired() {
+    const now = Date.now();
+    for (const [key, entry] of _store.entries()) {
+        if (entry.expiresAt < now)
+            _store.delete(key);
+    }
+}
+function addToSet(key, member, windowMs) {
+    cleanExpired();
+    const now = Date.now();
+    let entry = _store.get(key);
+    if (!entry || entry.expiresAt < now) {
+        entry = { members: new Set(), expiresAt: now + windowMs };
+        _store.set(key, entry);
+    }
+    entry.members.add(member);
+    return entry.members.size;
+}
+function getSetSize(key) {
+    cleanExpired();
+    const now = Date.now();
+    const entry = _store.get(key);
+    if (!entry || entry.expiresAt < now)
+        return 0;
+    return entry.members.size;
+}
+let _config = null;
+export function setCredentialStuffingConfig(config) {
+    _config = config;
+}
+export function getCredentialStuffingConfig() {
+    return _config;
+}
+/**
+ * Track a failed login attempt. Call this AFTER confirming the login failed.
+ */
+export function trackFailedLogin(ip, identifier) {
+    if (!_config)
+        return;
+    const ipWindowMs = _config.maxAccountsPerIp?.windowMs ?? 15 * 60 * 1000;
+    const accountWindowMs = _config.maxIpsPerAccount?.windowMs ?? 15 * 60 * 1000;
+    addToSet(`ip:${ip}`, identifier, ipWindowMs);
+    addToSet(`account:${identifier}`, ip, accountWindowMs);
+}
+/**
+ * Check whether this login attempt should be blocked.
+ * Call this BEFORE verifying credentials.
+ */
+export function isStuffingBlocked(ip, identifier) {
+    if (!_config)
+        return false;
+    const ipMax = _config.maxAccountsPerIp?.count ?? 5;
+    const accountMax = _config.maxIpsPerAccount?.count ?? 10;
+    const ipCount = getSetSize(`ip:${ip}`);
+    if (ipCount >= ipMax) {
+        try {
+            _config.onDetected?.({ type: "ip", key: ip, count: ipCount });
+        }
+        catch { /* swallow */ }
+        return true;
+    }
+    const accountCount = getSetSize(`account:${identifier}`);
+    if (accountCount >= accountMax) {
+        try {
+            _config.onDetected?.({ type: "account", key: identifier, count: accountCount });
+        }
+        catch { /* swallow */ }
+        return true;
+    }
+    return false;
+}
+/** Clear the in-memory store (for testing). */
+export function clearCredentialStuffingStore() {
+    _store.clear();
+}

package/dist/lib/deletionCancelToken.d.ts

@@ -0,0 +1,12 @@
+type CancelStore = "redis" | "mongo" | "sqlite" | "memory";
+export declare const setDeletionCancelTokenStore: (store: CancelStore) => void;
+/** Create a cancel token. Returns the raw token (to embed in the cancel link).
+ *  Only the SHA-256 hash is persisted. TTL is gracePeriod + a 5-minute buffer. */
+export declare const createDeletionCancelToken: (userId: string, jobId: string, gracePeriodSeconds: number) => Promise<string>;
+/** Atomically consume a cancel token — returns its payload and deletes it.
+ *  Returns null if the token is invalid, expired, or already used. */
+export declare const consumeDeletionCancelToken: (token: string) => Promise<{
+    userId: string;
+    jobId: string;
+} | null>;
+export {};

package/dist/lib/deletionCancelToken.js

@@ -0,0 +1,88 @@
+import { getRedis } from "./redis";
+import { appConnection, mongoose } from "./mongo";
+import { getAppName } from "./appConfig";
+import { sqliteCreateDeletionCancelToken, sqliteConsumeDeletionCancelToken, } from "../adapters/sqliteAuth";
+import { memoryCreateDeletionCancelToken, memoryConsumeDeletionCancelToken, } from "../adapters/memoryAuth";
+import { sha256 as hashToken } from "./crypto";
+function getCancelModel() {
+    if (appConnection.models["DeletionCancelToken"])
+        return appConnection.models["DeletionCancelToken"];
+    const { Schema } = mongoose;
+    const schema = new Schema({
+        token: { type: String, required: true, unique: true },
+        userId: { type: String, required: true },
+        jobId: { type: String, required: true },
+        expiresAt: { type: Date, required: true, index: { expireAfterSeconds: 0 } },
+    }, { collection: "deletion_cancel_tokens" });
+    return appConnection.model("DeletionCancelToken", schema);
+}
+// ---------------------------------------------------------------------------
+// Redis helpers
+// ---------------------------------------------------------------------------
+async function redisGetDel(key) {
+    const redis = getRedis();
+    if (typeof redis.getdel === "function") {
+        try {
+            return await redis.getdel(key);
+        }
+        catch (err) {
+            const msg = err?.message ?? "";
+            if (!/unknown command|ERR unknown command/i.test(msg))
+                throw err;
+        }
+    }
+    const result = await redis.eval("local v = redis.call('GET', KEYS[1])\nif v then redis.call('DEL', KEYS[1]) end\nreturn v", 1, key);
+    return result ?? null;
+}
+let _store = "redis";
+export const setDeletionCancelTokenStore = (store) => { _store = store; };
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Create a cancel token. Returns the raw token (to embed in the cancel link).
+ *  Only the SHA-256 hash is persisted. TTL is gracePeriod + a 5-minute buffer. */
+export const createDeletionCancelToken = async (userId, jobId, gracePeriodSeconds) => {
+    const token = crypto.randomUUID();
+    const hash = hashToken(token);
+    const ttl = gracePeriodSeconds + 300; // 5-min buffer after grace period expires
+    if (_store === "memory") {
+        memoryCreateDeletionCancelToken(hash, userId, jobId, ttl);
+        return token;
+    }
+    if (_store === "sqlite") {
+        sqliteCreateDeletionCancelToken(hash, userId, jobId, ttl);
+        return token;
+    }
+    if (_store === "mongo") {
+        await getCancelModel().create({
+            token: hash,
+            userId,
+            jobId,
+            expiresAt: new Date(Date.now() + ttl * 1000),
+        });
+        return token;
+    }
+    await getRedis().set(`delcancel:${getAppName()}:${hash}`, JSON.stringify({ userId, jobId }), "EX", ttl);
+    return token;
+};
+/** Atomically consume a cancel token — returns its payload and deletes it.
+ *  Returns null if the token is invalid, expired, or already used. */
+export const consumeDeletionCancelToken = async (token) => {
+    const hash = hashToken(token);
+    if (_store === "memory")
+        return memoryConsumeDeletionCancelToken(hash);
+    if (_store === "sqlite")
+        return sqliteConsumeDeletionCancelToken(hash);
+    if (_store === "mongo") {
+        const doc = await getCancelModel()
+            .findOneAndDelete({ token: hash, expiresAt: { $gt: new Date() } })
+            .lean();
+        if (!doc)
+            return null;
+        return { userId: doc.userId, jobId: doc.jobId };
+    }
+    const raw = await redisGetDel(`delcancel:${getAppName()}:${hash}`);
+    if (!raw)
+        return null;
+    return JSON.parse(raw);
+};

package/dist/lib/emailVerification.d.ts

@@ -10,4 +10,10 @@ export declare const getVerificationToken: (token: string) => Promise<{
 } | null>;
 /** Delete a verification token by its raw value. Hashes before lookup. */
 export declare const deleteVerificationToken: (token: string) => Promise<void>;
+/** Atomically consume a verification token — returns its payload and deletes it in one operation.
+ *  Returns null if the token is invalid, expired, or already used. */
+export declare const consumeVerificationToken: (token: string) => Promise<{
+    userId: string;
+    email: string;
+} | null>;
 export {};