@lastshotlabs/bunshot 0.0.20 → 0.0.25

package/dist/lib/idempotency.js

@@ -0,0 +1,182 @@
+import { getRedis } from "./redis";
+import { appConnection, mongoose } from "./mongo";
+import { getAppName } from "./appConfig";
+import { getSigningConfig, getSigningSecret } from "./appConfig";
+import { hmacSign } from "./signing";
+import { HEADER_IDEMPOTENCY_KEY } from "./constants";
+let _store = "redis";
+export const setIdempotencyStore = (store) => { _store = store; };
+// ---------------------------------------------------------------------------
+// Memory store (tests only — no TTL eviction)
+// ---------------------------------------------------------------------------
+const _memory = new Map();
+export const clearIdempotencyMemoryStore = () => _memory.clear();
+function getIdempotencyModel() {
+    if (appConnection.models["Idempotency"])
+        return appConnection.models["Idempotency"];
+    const { Schema } = mongoose;
+    const schema = new Schema({
+        key: { type: String, required: true, unique: true },
+        status: { type: Number, required: true },
+        body: { type: String, required: true },
+        createdAt: { type: Date, required: true },
+        expiresAt: { type: Date, required: true, index: { expireAfterSeconds: 0 } },
+    }, { collection: "idempotency" });
+    return appConnection.model("Idempotency", schema);
+}
+// ---------------------------------------------------------------------------
+// SQLite helpers (lazy — only available when bun:sqlite is in use)
+// ---------------------------------------------------------------------------
+function getSqliteDb() {
+    const { getDb } = require("../adapters/sqliteAuth");
+    return getDb();
+}
+function sqliteEnsureTable() {
+    const db = getSqliteDb();
+    db.run(`CREATE TABLE IF NOT EXISTS idempotency (
+    key       TEXT PRIMARY KEY,
+    status    INTEGER NOT NULL,
+    body      TEXT NOT NULL,
+    createdAt INTEGER NOT NULL,
+    expiresAt INTEGER NOT NULL
+  )`);
+}
+// ---------------------------------------------------------------------------
+// Key derivation
+// ---------------------------------------------------------------------------
+function deriveKey(rawKey, userId) {
+    const prefix = userId ?? "anon";
+    const cfg = getSigningConfig();
+    if (cfg?.idempotencyKeys) {
+        const secret = getSigningSecret();
+        if (secret) {
+            return `${prefix}:${hmacSign(rawKey, secret)}`;
+        }
+    }
+    return `${prefix}:${rawKey}`;
+}
+function redisIdempotencyKey(key) {
+    return `idempotency:${getAppName()}:${key}`;
+}
+// ---------------------------------------------------------------------------
+// Store operations
+// ---------------------------------------------------------------------------
+async function getRecord(key) {
+    if (_store === "memory") {
+        return _memory.get(key) ?? null;
+    }
+    if (_store === "sqlite") {
+        sqliteEnsureTable();
+        const row = getSqliteDb().query("SELECT status, body, createdAt FROM idempotency WHERE key = ? AND expiresAt > ?").get(key, Date.now());
+        return row ? { status: row.status, body: row.body, createdAt: row.createdAt } : null;
+    }
+    if (_store === "redis") {
+        const raw = await getRedis().get(redisIdempotencyKey(key));
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    // mongo
+    const doc = await getIdempotencyModel()
+        .findOne({ key, expiresAt: { $gt: new Date() } }, "status body createdAt")
+        .lean();
+    return doc ? { status: doc.status, body: doc.body, createdAt: doc.createdAt.getTime() } : null;
+}
+/**
+ * Attempt to store a record. Returns true if stored, false if a record
+ * already exists (write collision — treat as cache hit).
+ */
+async function tryStoreRecord(key, record, ttl) {
+    if (_store === "memory") {
+        if (_memory.has(key))
+            return false;
+        _memory.set(key, record);
+        return true;
+    }
+    if (_store === "sqlite") {
+        sqliteEnsureTable();
+        const db = getSqliteDb();
+        const expiresAt = record.createdAt + ttl * 1000;
+        db.run("INSERT OR IGNORE INTO idempotency (key, status, body, createdAt, expiresAt) VALUES (?, ?, ?, ?, ?)", [key, record.status, record.body, record.createdAt, expiresAt]);
+        // SQLite INSERT OR IGNORE doesn't throw on conflict; check changes count
+        const changes = db.query("SELECT changes() as changes").get()?.changes ?? 0;
+        return changes > 0;
+    }
+    if (_store === "redis") {
+        // SET NX: set-if-not-exists — second concurrent writer gets a no-op
+        const value = JSON.stringify(record);
+        const result = await getRedis().set(redisIdempotencyKey(key), value, "EX", ttl, "NX");
+        return result === "OK";
+    }
+    // mongo — unique index on key; second writer catches duplicate key error
+    try {
+        const now = new Date(record.createdAt);
+        await getIdempotencyModel().create({
+            key,
+            status: record.status,
+            body: record.body,
+            createdAt: now,
+            expiresAt: new Date(now.getTime() + ttl * 1000),
+        });
+        return true;
+    }
+    catch (err) {
+        // Duplicate key — another concurrent request already stored the result
+        if (err?.code === 11000 || err?.code === "11000")
+            return false;
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// Middleware factory
+// ---------------------------------------------------------------------------
+/**
+ * Idempotency middleware. Reads the `Idempotency-Key` header and returns a
+ * cached response if one exists for this user + key combination. Otherwise
+ * calls the next handler, stores the response, and returns it.
+ *
+ * On write collision (two concurrent identical requests), the second request
+ * re-reads and returns the first-stored result.
+ *
+ * When `signing.idempotencyKeys: true`, keys are HMAC'd before storage to
+ * prevent enumeration. When off, raw keys are stored (slight enumeration risk).
+ */
+export const idempotent = (opts) => async (c, next) => {
+    const rawKey = c.req.header(HEADER_IDEMPOTENCY_KEY);
+    if (!rawKey) {
+        await next();
+        return;
+    }
+    const userId = c.get("authUserId") ?? null;
+    const key = deriveKey(rawKey, userId);
+    const ttl = opts?.ttl ?? 86400;
+    // Cache hit — return stored response
+    const cached = await getRecord(key);
+    if (cached) {
+        return c.json(JSON.parse(cached.body), cached.status);
+    }
+    // Cache miss — call handler
+    await next();
+    // Capture the response body by reading it
+    const status = c.res.status;
+    let body = "";
+    try {
+        body = await c.res.clone().text();
+    }
+    catch {
+        // Non-text/non-json response — skip caching
+        return;
+    }
+    const record = { status, body, createdAt: Date.now() };
+    const stored = await tryStoreRecord(key, record, ttl);
+    if (!stored) {
+        // Write collision — return the first-stored result
+        const winner = await getRecord(key);
+        if (winner) {
+            c.res = new Response(winner.body, {
+                status: winner.status,
+                headers: { "content-type": "application/json" },
+            });
+        }
+    }
+};

package/dist/lib/metrics.d.ts

@@ -0,0 +1,14 @@
+type Labels = Record<string, string>;
+export declare function defaultNormalizePath(path: string): string;
+export declare function incrementCounter(name: string, labels: Labels, amount?: number): void;
+export declare function observeHistogram(name: string, labels: Labels, value: number, buckets?: number[]): void;
+type GaugeCallback = () => Promise<{
+    labels: Labels;
+    value: number;
+}[]>;
+export declare function registerGaugeCallback(name: string, cb: GaugeCallback): void;
+export declare function serializeMetrics(): Promise<string>;
+export declare function resetMetrics(): void;
+export declare function setMetricsQueues(map: Map<string, any>): void;
+export declare function closeMetricsQueues(): Promise<void>;
+export {};

package/dist/lib/metrics.js

@@ -0,0 +1,158 @@
+// In-memory Prometheus-compatible metrics registry.
+// Bun is single-threaded so no atomics are needed.
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function labelKey(labels) {
+    return Object.entries(labels)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}="${v}"`)
+        .join(",");
+}
+function formatLabels(labels) {
+    const pairs = Object.entries(labels)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([k, v]) => `${k}="${v}"`);
+    return pairs.length ? `{${pairs.join(",")}}` : "";
+}
+// ── Path normalization ───────────────────────────────────────────────────────
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const OBJECTID_RE = /^[0-9a-f]{24}$/i;
+const NUMERIC_RE = /^\d+$/;
+export function defaultNormalizePath(path) {
+    return path
+        .split("/")
+        .map((seg) => {
+        if (!seg)
+            return seg;
+        if (UUID_RE.test(seg))
+            return ":id";
+        if (OBJECTID_RE.test(seg))
+            return ":id";
+        if (NUMERIC_RE.test(seg))
+            return ":id";
+        return seg;
+    })
+        .join("/");
+}
+const counters = new Map();
+export function incrementCounter(name, labels, amount = 1) {
+    let metric = counters.get(name);
+    if (!metric) {
+        metric = new Map();
+        counters.set(name, metric);
+    }
+    const key = labelKey(labels);
+    const existing = metric.get(key);
+    if (existing) {
+        existing.value += amount;
+    }
+    else {
+        metric.set(key, { labels: { ...labels }, value: amount });
+    }
+}
+// ── Histogram ────────────────────────────────────────────────────────────────
+const DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+const histograms = new Map();
+export function observeHistogram(name, labels, value, buckets = DEFAULT_BUCKETS) {
+    let metric = histograms.get(name);
+    if (!metric) {
+        metric = { boundaries: buckets, entries: new Map() };
+        histograms.set(name, metric);
+    }
+    const key = labelKey(labels);
+    let entry = metric.entries.get(key);
+    if (!entry) {
+        entry = { labels: { ...labels }, buckets: new Array(buckets.length).fill(0), sum: 0, count: 0 };
+        metric.entries.set(key, entry);
+    }
+    // Find the first (tightest) bucket the value fits in.
+    // Serialization will compute cumulative sums across buckets.
+    for (let i = 0; i < metric.boundaries.length; i++) {
+        if (value <= metric.boundaries[i]) {
+            entry.buckets[i]++;
+            break;
+        }
+    }
+    entry.sum += value;
+    entry.count++;
+}
+const gaugeCallbacks = new Map();
+export function registerGaugeCallback(name, cb) {
+    gaugeCallbacks.set(name, cb);
+}
+// ── Serialize ────────────────────────────────────────────────────────────────
+export async function serializeMetrics() {
+    const lines = [];
+    // Collect gauge callbacks first so any error-counter increments are
+    // included when we serialize counters below.
+    const gaugeLines = [];
+    for (const [name, cb] of gaugeCallbacks) {
+        try {
+            const results = await cb();
+            gaugeLines.push(`# HELP ${name} ${name.replace(/_/g, " ")}`);
+            gaugeLines.push(`# TYPE ${name} gauge`);
+            for (const { labels, value } of results) {
+                gaugeLines.push(`${name}${formatLabels(labels)} ${value}`);
+            }
+            gaugeLines.push("");
+        }
+        catch (err) {
+            console.warn(`[metrics] Gauge callback "${name}" failed:`, err);
+            incrementCounter("bunshot_gauge_errors_total", { gauge: name });
+        }
+    }
+    // Counters
+    for (const [name, entries] of counters) {
+        lines.push(`# HELP ${name} Total ${name.replace(/_/g, " ")}`);
+        lines.push(`# TYPE ${name} counter`);
+        for (const entry of entries.values()) {
+            lines.push(`${name}${formatLabels(entry.labels)} ${entry.value}`);
+        }
+        lines.push("");
+    }
+    // Histograms
+    for (const [name, metric] of histograms) {
+        lines.push(`# HELP ${name} ${name.replace(/_/g, " ")}`);
+        lines.push(`# TYPE ${name} histogram`);
+        for (const entry of metric.entries.values()) {
+            const lbls = formatLabels(entry.labels);
+            let cumulative = 0;
+            for (let i = 0; i < metric.boundaries.length; i++) {
+                cumulative += entry.buckets[i];
+                const bucketLabels = { ...entry.labels, le: String(metric.boundaries[i]) };
+                lines.push(`${name}_bucket${formatLabels(bucketLabels)} ${cumulative}`);
+            }
+            const infLabels = { ...entry.labels, le: "+Inf" };
+            lines.push(`${name}_bucket${formatLabels(infLabels)} ${entry.count}`);
+            lines.push(`${name}_sum${lbls} ${entry.sum}`);
+            lines.push(`${name}_count${lbls} ${entry.count}`);
+        }
+        lines.push("");
+    }
+    // Gauges (already collected above)
+    lines.push(...gaugeLines);
+    return lines.join("\n");
+}
+// ── Reset (for tests) ───────────────────────────────────────────────────────
+export function resetMetrics() {
+    counters.clear();
+    histograms.clear();
+    gaugeCallbacks.clear();
+}
+// ── Queue cleanup ────────────────────────────────────────────────────────────
+let metricsQueues = null;
+export function setMetricsQueues(map) {
+    metricsQueues = map;
+}
+export async function closeMetricsQueues() {
+    if (!metricsQueues)
+        return;
+    for (const q of metricsQueues.values()) {
+        try {
+            await q.close();
+        }
+        catch {
+            // best-effort cleanup
+        }
+    }
+    metricsQueues.clear();
+}

package/dist/lib/pagination.d.ts

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import type { ZodType } from "zod";
+export type { PaginationOpts, PaginatedResult } from "./groups";
+export interface OffsetParamDefaults {
+    /** Default: 50 */
+    limit?: number;
+    /** Default: 200 */
+    maxLimit?: number;
+    /** Default: 0 */
+    offset?: number;
+}
+export interface ParsedOffsetParams {
+    limit: number;
+    offset: number;
+}
+/**
+ * Zod schema for offset pagination query params.
+ * Fields are `z.string().optional()` — matches the existing query param
+ * convention. Parse the values with `parseOffsetParams`.
+ *
+ * @example
+ * createRoute({ ..., request: { query: offsetParams({ limit: 20 }) }, ... })
+ */
+export declare function offsetParams(defaults?: OffsetParamDefaults): z.ZodObject<{
+    limit: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Parses raw string query values into clamped integers.
+ * - NaN (non-numeric strings) falls back to defaults
+ * - limit clamped to [1, maxLimit]
+ * - offset clamped to [0, ∞)
+ *
+ * @example
+ * const { limit, offset } = parseOffsetParams(c.req.query(), { maxLimit: 100 });
+ */
+export declare function parseOffsetParams(raw: {
+    limit?: string;
+    offset?: string;
+}, defaults?: OffsetParamDefaults): ParsedOffsetParams;
+/**
+ * Zod schema factory for paginated offset responses.
+ * Wraps `itemSchema` in `{ items, total, limit, offset }` and registers
+ * the result as a named OpenAPI component.
+ *
+ * Throws if `name` was previously registered to a different schema instance.
+ * Calling with the same `name` + `schema` pair is idempotent.
+ *
+ * @example
+ * const PaginatedUsersResponse = paginatedResponse(UserSchema, "PaginatedUsers");
+ */
+export declare function paginatedResponse<T extends ZodType>(itemSchema: T, name: string): z.ZodObject<{
+    items: z.ZodArray<T>;
+    total: z.ZodNumber;
+    limit: z.ZodNumber;
+    offset: z.ZodNumber;
+}, z.core.$strip>;
+export interface CursorParamDefaults {
+    /** Default: 50 */
+    limit?: number;
+    /** Default: 200 */
+    maxLimit?: number;
+}
+export interface ParsedCursorParams {
+    limit: number;
+    cursor: string | undefined;
+}
+export interface CursorResult<T> {
+    items: T[];
+    nextCursor: string | null;
+    hasMore: boolean;
+}
+/**
+ * Zod schema for cursor pagination query params.
+ * Fields are `z.string().optional()`. Parse the values with `parseCursorParams`.
+ *
+ * @example
+ * createRoute({ ..., request: { query: cursorParams() }, ... })
+ */
+export declare function cursorParams(defaults?: CursorParamDefaults): z.ZodObject<{
+    limit: z.ZodOptional<z.ZodString>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Parses raw string query values into typed cursor params.
+ * - limit: NaN falls back to default, clamped to [1, maxLimit]
+ * - cursor: empty string normalized to `undefined`; non-empty is pass-through
+ * - When `signing.cursors: true`, verifies the cursor HMAC — invalid cursor returns null
+ *
+ * @example
+ * const { limit, cursor } = parseCursorParams(c.req.query());
+ */
+export declare function parseCursorParams(raw: {
+    limit?: string;
+    cursor?: string;
+}, defaults?: CursorParamDefaults): ParsedCursorParams & {
+    invalidCursor?: true;
+};
+/**
+ * Sign a cursor value if `signing.cursors: true`. Otherwise returns the
+ * cursor unchanged (current behavior).
+ */
+export declare function maybeSignCursor(cursor: string | null): string | null;
+/**
+ * Zod schema factory for cursor-paginated responses.
+ * Wraps `itemSchema` in `{ items, nextCursor, hasMore }` and registers
+ * the result as a named OpenAPI component.
+ *
+ * Throws if `name` was previously registered to a different schema instance.
+ * Calling with the same `name` + `schema` pair is idempotent.
+ *
+ * @example
+ * const PostsPage = cursorResponse(PostSchema, "PostsPage");
+ */
+export declare function cursorResponse<T extends ZodType>(itemSchema: T, name: string): z.ZodObject<{
+    items: z.ZodArray<T>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+    hasMore: z.ZodBoolean;
+}, z.core.$strip>;

package/dist/lib/pagination.js

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { registerSchema } from "./createRoute";
+import { getSigningConfig, getSigningSecret } from "./appConfig";
+import { signCursor, verifyCursor } from "./signing";
+const _registered = new Map();
+function guardedRegister(name, itemSchema, buildWrapper) {
+    const existing = _registered.get(name);
+    if (existing !== undefined) {
+        if (existing.itemSchema !== itemSchema) {
+            throw new Error(`Pagination schema name "${name}" is already registered to a different schema`);
+        }
+        // Same item schema → idempotent, return the cached wrapper
+        return existing.wrapper;
+    }
+    const wrapper = buildWrapper();
+    _registered.set(name, { itemSchema, wrapper });
+    registerSchema(name, wrapper);
+    return wrapper;
+}
+/**
+ * Zod schema for offset pagination query params.
+ * Fields are `z.string().optional()` — matches the existing query param
+ * convention. Parse the values with `parseOffsetParams`.
+ *
+ * @example
+ * createRoute({ ..., request: { query: offsetParams({ limit: 20 }) }, ... })
+ */
+export function offsetParams(defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const defaultOffset = defaults?.offset ?? 0;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    return z.object({
+        limit: z
+            .string()
+            .optional()
+            .describe(`Number of items to return (1–${maxLimit}, default ${defaultLimit})`),
+        offset: z
+            .string()
+            .optional()
+            .describe(`Number of items to skip (default ${defaultOffset})`),
+    });
+}
+/**
+ * Parses raw string query values into clamped integers.
+ * - NaN (non-numeric strings) falls back to defaults
+ * - limit clamped to [1, maxLimit]
+ * - offset clamped to [0, ∞)
+ *
+ * @example
+ * const { limit, offset } = parseOffsetParams(c.req.query(), { maxLimit: 100 });
+ */
+export function parseOffsetParams(raw, defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    const defaultOffset = defaults?.offset ?? 0;
+    const rawLimit = parseInt(raw.limit ?? "", 10);
+    const rawOffset = parseInt(raw.offset ?? "", 10);
+    const limit = isNaN(rawLimit)
+        ? defaultLimit
+        : Math.min(Math.max(rawLimit, 1), maxLimit);
+    const offset = isNaN(rawOffset) ? defaultOffset : Math.max(rawOffset, 0);
+    return { limit, offset };
+}
+/**
+ * Zod schema factory for paginated offset responses.
+ * Wraps `itemSchema` in `{ items, total, limit, offset }` and registers
+ * the result as a named OpenAPI component.
+ *
+ * Throws if `name` was previously registered to a different schema instance.
+ * Calling with the same `name` + `schema` pair is idempotent.
+ *
+ * @example
+ * const PaginatedUsersResponse = paginatedResponse(UserSchema, "PaginatedUsers");
+ */
+export function paginatedResponse(itemSchema, name) {
+    return guardedRegister(name, itemSchema, () => z.object({
+        items: z.array(itemSchema),
+        total: z.number().int().nonnegative(),
+        limit: z.number().int().positive(),
+        offset: z.number().int().nonnegative(),
+    }));
+}
+/**
+ * Zod schema for cursor pagination query params.
+ * Fields are `z.string().optional()`. Parse the values with `parseCursorParams`.
+ *
+ * @example
+ * createRoute({ ..., request: { query: cursorParams() }, ... })
+ */
+export function cursorParams(defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    return z.object({
+        limit: z
+            .string()
+            .optional()
+            .describe(`Number of items to return (1–${maxLimit}, default ${defaultLimit})`),
+        cursor: z
+            .string()
+            .optional()
+            .describe("Opaque cursor from a previous response's nextCursor field"),
+    });
+}
+/**
+ * Parses raw string query values into typed cursor params.
+ * - limit: NaN falls back to default, clamped to [1, maxLimit]
+ * - cursor: empty string normalized to `undefined`; non-empty is pass-through
+ * - When `signing.cursors: true`, verifies the cursor HMAC — invalid cursor returns null
+ *
+ * @example
+ * const { limit, cursor } = parseCursorParams(c.req.query());
+ */
+export function parseCursorParams(raw, defaults) {
+    const defaultLimit = defaults?.limit ?? 50;
+    const maxLimit = defaults?.maxLimit ?? 200;
+    const rawLimit = parseInt(raw.limit ?? "", 10);
+    const limit = isNaN(rawLimit)
+        ? defaultLimit
+        : Math.min(Math.max(rawLimit, 1), maxLimit);
+    if (!raw.cursor)
+        return { limit, cursor: undefined };
+    const cfg = getSigningConfig();
+    if (cfg?.cursors) {
+        const secret = getSigningSecret();
+        if (secret) {
+            const verified = verifyCursor(raw.cursor, secret);
+            if (verified === null)
+                return { limit, cursor: undefined, invalidCursor: true };
+            return { limit, cursor: verified };
+        }
+    }
+    return { limit, cursor: raw.cursor };
+}
+/**
+ * Sign a cursor value if `signing.cursors: true`. Otherwise returns the
+ * cursor unchanged (current behavior).
+ */
+export function maybeSignCursor(cursor) {
+    if (!cursor)
+        return cursor;
+    const cfg = getSigningConfig();
+    if (cfg?.cursors) {
+        const secret = getSigningSecret();
+        if (secret)
+            return signCursor(cursor, secret);
+    }
+    return cursor;
+}
+/**
+ * Zod schema factory for cursor-paginated responses.
+ * Wraps `itemSchema` in `{ items, nextCursor, hasMore }` and registers
+ * the result as a named OpenAPI component.
+ *
+ * Throws if `name` was previously registered to a different schema instance.
+ * Calling with the same `name` + `schema` pair is idempotent.
+ *
+ * @example
+ * const PostsPage = cursorResponse(PostSchema, "PostsPage");
+ */
+export function cursorResponse(itemSchema, name) {
+    return guardedRegister(name, itemSchema, () => z.object({
+        items: z.array(itemSchema),
+        nextCursor: z.string().nullable(),
+        hasMore: z.boolean(),
+    }));
+}

package/dist/lib/session.d.ts

@@ -32,4 +32,8 @@ export declare const setRefreshToken: (sessionId: string, refreshToken: string)
 export declare const getSessionByRefreshToken: (refreshToken: string) => Promise<RefreshResult | null>;
 /** Rotate the refresh token: move current to prev with grace window, set new token + access token. */
 export declare const rotateRefreshToken: (sessionId: string, newRefreshToken: string, newAccessToken: string) => Promise<void>;
+/** Read the stored fingerprint for a session. Returns null if not yet set. */
+export declare const getSessionFingerprint: (sessionId: string) => Promise<string | null>;
+/** Store a fingerprint on an existing session. No-op if the session does not exist. */
+export declare const setSessionFingerprint: (sessionId: string, fingerprint: string) => Promise<void>;
 export {};