local-lite 0.0.19 → 0.0.21

package/README.md

@@ -92,7 +92,11 @@ This recovers sync state; it does not repair corrupt SQLite files or cancel hung
 * **🔄 Infinite-Loop Safe:** Incoming remote deltas update local tables and fire reactive UI listeners without echoing back into the outbox.
 * **☁️ Database Backups:** Export and restore SQLite snapshots independently of your live sync backend.
 * **🔑 Google Sign-In Out of the Box:** Secure, zero-backend Google OAuth 2.0 (PKCE) authentication with automatic token refresh, user profile retrieval, persistent session storage, and `useGoogleAuth()` hook.
-* **📨 Action Outbox & Email Queue:** Enqueue transactional emails, push notifications, and webhooks offline with idempotency keys, automatic retry backoff, crash recovery, and TTL expiration.
+* **📨 Action Outbox & Email Queue:** Enqueue transactional emails, push notifications, and webhooks offline with idempotency keys, automatic retry backoff, crash recovery, and TTL expiration.
+* **⚡ Fast Key-Value & Encrypted Preferences (`client.kv`):** Typed storage, TTL expiration, and AES-256-GCM zero-knowledge secret protection.
+* **🔍 Instant Full-Text Search (`client.search`):** SQLite FTS5 indexer with prefix matching, BM25 rank scoring, and highlighting.
+* **📁 Offline Media & Blob Storage (`client.storage`):** Decoupled binary attachments, SHA-256 verification, and cloud sync queue (S3/Supabase/Firebase).
+* **⏰ Offline Job Scheduler & Background Cron (`client.scheduler`):** Persistent background task runner supporting human schedules and 5-field cron.
 
 
 ---

package/dist/actions/store.js

@@ -169,7 +169,7 @@ class ActionStore {
      * Cancels a pending action if it has not yet executed.
      */
     static async cancel(db, tableName = exports.DEFAULT_ACTIONS_TABLE, id) {
-        const rows = await db.execute(`UPDATE ${tableName} SET status = 'CANCELLED' WHERE id = ? AND status = 'PENDING';`, [id]);
+        await db.execute(`UPDATE ${tableName} SET status = 'CANCELLED' WHERE id = ? AND status = 'PENDING';`, [id]);
         // In drivers that return affected rows or execute successfully
         const record = await this.findById(db, tableName, id);
         return record?.status === 'CANCELLED';

package/dist/auth/index.d.ts

@@ -2,3 +2,4 @@ export * from './google.js';
 export * from './microsoft.js';
 export * from './github.js';
 export * from './apple.js';
+export * from './session.js';

package/dist/auth/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./google.js"), exports);
 __exportStar(require("./microsoft.js"), exports);
 __exportStar(require("./github.js"), exports);
 __exportStar(require("./apple.js"), exports);
+__exportStar(require("./session.js"), exports);

package/dist/auth/session.d.ts

@@ -0,0 +1,107 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { EventEmitter } from '../reactive/event-emitter.js';
+export declare const DEFAULT_SESSIONS_TABLE = "_local_sessions";
+export declare const DEFAULT_OFFLINE_DURATION_MS: number;
+export interface SessionRecord<TUser = any> {
+    id: string;
+    userId: string;
+    user: TUser;
+    token?: string | null;
+    refreshToken?: string | null;
+    provider?: string | null;
+    createdAt: number;
+    lastActiveAt: number;
+    expiresAt?: number | null;
+    offlineAccessUntil?: number | null;
+    metadata?: Record<string, any> | null;
+    isActive: boolean;
+}
+export interface CreateSessionOptions<TUser = any> {
+    id?: string;
+    userId: string;
+    user: TUser;
+    token?: string | null;
+    refreshToken?: string | null;
+    provider?: string | null;
+    expiresAt?: number | null;
+    /**
+     * Duration in ms the session remains valid while offline without re-authenticating.
+     * Default: 30 days. Set to 0 or Infinity for unlimited offline access.
+     */
+    offlineDurationMs?: number;
+    metadata?: Record<string, any>;
+    /**
+     * Whether to activate this session as the active user immediately.
+     * Default: true
+     */
+    setActive?: boolean;
+}
+export interface SessionManagerOptions {
+    tableName?: string;
+    defaultOfflineDurationMs?: number;
+    network?: {
+        isOnline(): boolean | Promise<boolean>;
+    };
+}
+export declare function mapSessionRow<TUser = any>(r: any): SessionRecord<TUser>;
+export declare class SessionManager {
+    private db;
+    private events?;
+    private tableName;
+    private defaultOfflineDurationMs;
+    private network?;
+    constructor(db: DBExecutable, events?: EventEmitter | undefined, options?: SessionManagerOptions);
+    /**
+     * Ensures the _local_sessions schema exists.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Creates or updates a user session, persisting it to local SQLite so it remains available offline.
+     */
+    createSession<TUser = any>(options: CreateSessionOptions<TUser>): Promise<SessionRecord<TUser>>;
+    /**
+     * Retrieves the currently active session.
+     * If offline, the session remains active even if server tokens expired, as long as offlineAccessUntil is valid.
+     */
+    getActiveSession<TUser = any>(): Promise<SessionRecord<TUser> | null>;
+    /**
+     * Returns true if there is an active valid session (works offline and online).
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Retrieves the authenticated user profile object, or null if signed out.
+     */
+    getUser<TUser = any>(): Promise<TUser | null>;
+    /**
+     * Updates last active timestamp.
+     */
+    touch(sessionId?: string): Promise<void>;
+    /**
+     * Partially updates the active user's profile data in SQLite.
+     */
+    updateUser<TUser = any>(partialUser: Partial<TUser>): Promise<SessionRecord<TUser> | null>;
+    /**
+     * Updates access tokens without re-authenticating or resetting the offline grace period.
+     */
+    updateTokens(tokens: {
+        token?: string | null;
+        refreshToken?: string | null;
+        expiresAt?: number | null;
+    }): Promise<void>;
+    /**
+     * Signs out the active user session.
+     */
+    clearSession(): Promise<void>;
+    /**
+     * Completely purges all stored sessions (e.g. factory reset or privacy wipe).
+     */
+    purgeAllSessions(): Promise<void>;
+    /**
+     * Lists all sessions currently cached in SQLite.
+     */
+    listSessions<TUser = any>(): Promise<SessionRecord<TUser>[]>;
+    /**
+     * Switches the active session to a different account (e.g., multi-account or organization switching offline).
+     */
+    switchSession<TUser = any>(sessionIdOrUserId: string): Promise<SessionRecord<TUser> | null>;
+}

package/dist/auth/session.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionManager = exports.DEFAULT_OFFLINE_DURATION_MS = exports.DEFAULT_SESSIONS_TABLE = void 0;
+exports.mapSessionRow = mapSessionRow;
+const uuid_js_1 = require("../utils/uuid.js");
+exports.DEFAULT_SESSIONS_TABLE = '_local_sessions';
+exports.DEFAULT_OFFLINE_DURATION_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+function mapSessionRow(r) {
+    let userData;
+    try {
+        userData = typeof r.user_data === 'string' ? JSON.parse(r.user_data) : r.user_data;
+    }
+    catch {
+        userData = r.user_data;
+    }
+    let metadata = null;
+    if (r.metadata) {
+        try {
+            metadata = typeof r.metadata === 'string' ? JSON.parse(r.metadata) : r.metadata;
+        }
+        catch {
+            metadata = null;
+        }
+    }
+    return {
+        id: String(r.id),
+        userId: String(r.user_id),
+        user: userData,
+        token: r.token || null,
+        refreshToken: r.refresh_token || null,
+        provider: r.provider || null,
+        createdAt: Number(r.created_at || 0),
+        lastActiveAt: Number(r.last_active_at || 0),
+        expiresAt: r.expires_at != null ? Number(r.expires_at) : null,
+        offlineAccessUntil: r.offline_access_until != null ? Number(r.offline_access_until) : null,
+        metadata,
+        isActive: r.is_active === 1 || r.is_active === '1' || r.is_active === true,
+    };
+}
+class SessionManager {
+    db;
+    events;
+    tableName;
+    defaultOfflineDurationMs;
+    network;
+    constructor(db, events, options = {}) {
+        this.db = db;
+        this.events = events;
+        this.tableName = options.tableName ?? exports.DEFAULT_SESSIONS_TABLE;
+        this.defaultOfflineDurationMs = options.defaultOfflineDurationMs ?? exports.DEFAULT_OFFLINE_DURATION_MS;
+        this.network = options.network;
+    }
+    /**
+     * Ensures the _local_sessions schema exists.
+     */
+    async initialize() {
+        await this.db.execute(`CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        id TEXT PRIMARY KEY,
+        user_id TEXT NOT NULL,
+        user_data TEXT NOT NULL,
+        token TEXT,
+        refresh_token TEXT,
+        provider TEXT,
+        created_at INTEGER NOT NULL,
+        last_active_at INTEGER NOT NULL,
+        expires_at INTEGER,
+        offline_access_until INTEGER,
+        metadata TEXT,
+        is_active INTEGER NOT NULL DEFAULT 1
+      );`);
+        await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_user ON ${this.tableName} (user_id);`);
+        await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_${this.tableName}_active ON ${this.tableName} (is_active);`);
+    }
+    /**
+     * Creates or updates a user session, persisting it to local SQLite so it remains available offline.
+     */
+    async createSession(options) {
+        const id = options.id || `sess_${(0, uuid_js_1.generateUUID)()}`;
+        const now = Date.now();
+        const offlineDuration = options.offlineDurationMs !== undefined
+            ? options.offlineDurationMs
+            : this.defaultOfflineDurationMs;
+        const offlineAccessUntil = offlineDuration === 0 || offlineDuration === Infinity
+            ? null
+            : now + offlineDuration;
+        const setActive = options.setActive !== false;
+        const userDataStr = JSON.stringify(options.user ?? {});
+        const metadataStr = options.metadata ? JSON.stringify(options.metadata) : null;
+        if (setActive) {
+            // Deactivate other sessions
+            await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?;`, [0]);
+        }
+        const sql = `
+      INSERT INTO ${this.tableName} (id, user_id, user_data, token, refresh_token, provider, created_at, last_active_at, expires_at, offline_access_until, metadata, is_active)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        user_id = excluded.user_id,
+        user_data = excluded.user_data,
+        token = excluded.token,
+        refresh_token = excluded.refresh_token,
+        provider = excluded.provider,
+        last_active_at = excluded.last_active_at,
+        expires_at = excluded.expires_at,
+        offline_access_until = excluded.offline_access_until,
+        metadata = excluded.metadata,
+        is_active = excluded.is_active;
+    `;
+        await this.db.execute(sql, [
+            id,
+            options.userId,
+            userDataStr,
+            options.token ?? null,
+            options.refreshToken ?? null,
+            options.provider ?? null,
+            now,
+            now,
+            options.expiresAt ?? null,
+            offlineAccessUntil,
+            metadataStr,
+            setActive ? 1 : 0,
+        ]);
+        const session = {
+            id,
+            userId: options.userId,
+            user: options.user,
+            token: options.token || null,
+            refreshToken: options.refreshToken || null,
+            provider: options.provider || null,
+            createdAt: now,
+            lastActiveAt: now,
+            expiresAt: options.expiresAt || null,
+            offlineAccessUntil,
+            metadata: options.metadata || null,
+            isActive: setActive,
+        };
+        this.events?.emit(this.tableName, { operation: 'SET_SESSION', session });
+        return session;
+    }
+    /**
+     * Retrieves the currently active session.
+     * If offline, the session remains active even if server tokens expired, as long as offlineAccessUntil is valid.
+     */
+    async getActiveSession() {
+        const rows = await this.db.execute(`SELECT * FROM ${this.tableName} WHERE is_active = ? LIMIT 1;`, [1]);
+        if (!rows || rows.length === 0) {
+            return null;
+        }
+        const session = mapSessionRow(rows[0]);
+        const now = Date.now();
+        // Check if offline access grace period has expired
+        if (session.offlineAccessUntil != null && now > session.offlineAccessUntil) {
+            await this.clearSession();
+            return null;
+        }
+        // Touch last active
+        await this.touch(session.id);
+        return session;
+    }
+    /**
+     * Returns true if there is an active valid session (works offline and online).
+     */
+    async isAuthenticated() {
+        const session = await this.getActiveSession();
+        return session !== null;
+    }
+    /**
+     * Retrieves the authenticated user profile object, or null if signed out.
+     */
+    async getUser() {
+        const session = await this.getActiveSession();
+        return session ? session.user : null;
+    }
+    /**
+     * Updates last active timestamp.
+     */
+    async touch(sessionId) {
+        const now = Date.now();
+        if (sessionId) {
+            await this.db.execute(`UPDATE ${this.tableName} SET last_active_at = ? WHERE id = ?;`, [now, sessionId]);
+        }
+        else {
+            await this.db.execute(`UPDATE ${this.tableName} SET last_active_at = ? WHERE is_active = ?;`, [now, 1]);
+        }
+    }
+    /**
+     * Partially updates the active user's profile data in SQLite.
+     */
+    async updateUser(partialUser) {
+        const session = await this.getActiveSession();
+        if (!session)
+            return null;
+        const updatedUser = {
+            ...session.user,
+            ...partialUser,
+        };
+        const userDataStr = JSON.stringify(updatedUser);
+        const now = Date.now();
+        await this.db.execute(`UPDATE ${this.tableName} SET user_data = ?, last_active_at = ? WHERE id = ?;`, [userDataStr, now, session.id]);
+        session.user = updatedUser;
+        session.lastActiveAt = now;
+        this.events?.emit(this.tableName, { operation: 'UPDATE_USER', session });
+        return session;
+    }
+    /**
+     * Updates access tokens without re-authenticating or resetting the offline grace period.
+     */
+    async updateTokens(tokens) {
+        const session = await this.getActiveSession();
+        if (!session)
+            return;
+        const token = tokens.token !== undefined ? tokens.token : session.token;
+        const refreshToken = tokens.refreshToken !== undefined ? tokens.refreshToken : session.refreshToken;
+        const expiresAt = tokens.expiresAt !== undefined ? tokens.expiresAt : session.expiresAt;
+        const now = Date.now();
+        await this.db.execute(`UPDATE ${this.tableName} SET token = ?, refresh_token = ?, expires_at = ?, last_active_at = ? WHERE id = ?;`, [token, refreshToken, expiresAt, now, session.id]);
+        session.token = token;
+        session.refreshToken = refreshToken;
+        session.expiresAt = expiresAt;
+        this.events?.emit(this.tableName, { operation: 'UPDATE_TOKENS', session });
+    }
+    /**
+     * Signs out the active user session.
+     */
+    async clearSession() {
+        await this.db.execute(`UPDATE ${this.tableName} SET is_active = ? WHERE is_active = ?;`, [0, 1]);
+        this.events?.emit(this.tableName, { operation: 'CLEAR_SESSION' });
+    }
+    /**
+     * Completely purges all stored sessions (e.g. factory reset or privacy wipe).
+     */
+    async purgeAllSessions() {
+        await this.db.execute(`DELETE FROM ${this.tableName};`);
+        this.events?.emit(this.tableName, { operation: 'PURGE_SESSIONS' });
+    }
+    /**
+     * Lists all sessions currently cached in SQLite.
+     */
+    async listSessions() {
+        const rows = await this.db.execute(`SELECT * FROM ${this.tableName} ORDER BY last_active_at DESC;`);
+        return (rows || []).map((r) => mapSessionRow(r));
+    }
+    /**
+     * Switches the active session to a different account (e.g., multi-account or organization switching offline).
+     */
+    async switchSession(sessionIdOrUserId) {
+        const rows = await this.db.execute(`SELECT * FROM ${this.tableName} WHERE id = ? OR user_id = ? LIMIT 1;`, [sessionIdOrUserId, sessionIdOrUserId]);
+        if (!rows || rows.length === 0) {
+            return null;
+        }
+        const targetSession = mapSessionRow(rows[0]);
+        await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?;`, [0]);
+        await this.db.execute(`UPDATE ${this.tableName} SET is_active = ?, last_active_at = ? WHERE id = ?;`, [1, Date.now(), targetSession.id]);
+        targetSession.isActive = true;
+        targetSession.lastActiveAt = Date.now();
+        this.events?.emit(this.tableName, { operation: 'SWITCH_SESSION', session: targetSession });
+        return targetSession;
+    }
+}
+exports.SessionManager = SessionManager;

package/dist/core/client.d.ts

@@ -10,6 +10,12 @@ import { QueryBuilder, AggregateSpec, AggregateResult } from './query-builder.js
 import { type ExportJsonOptions, type ImportJsonOptions, type ExportCsvOptions, type ImportCsvOptions, type ImportSummary } from '../utils/portability.js';
 import { type BackupStorage, type CreateDatabaseBackupOptions, type EncryptedBackupOptions, type RestoreEncryptedBackupOptions } from '../backups/index.js';
 import { ActionManager, type ActionManagerOptions } from '../actions/index.js';
+import { ApiKeyManager, type ApiKeyManagerOptions } from '../keys/index.js';
+import { KVManager, type KVStoreOptions } from '../kv/index.js';
+import { SearchManager } from '../search/index.js';
+import { BlobStorageManager, type BlobStorageManagerOptions } from '../storage/index.js';
+import { JobScheduler, type JobSchedulerOptions } from '../scheduler/index.js';
+import { SessionManager, type SessionManagerOptions } from '../auth/session.js';
 export interface LocalFirstClientConfig {
     local: LocalDBAdapter;
     remote: RemoteDBAdapter;
@@ -41,6 +47,11 @@ export interface LocalFirstClientConfig {
      */
     touchUpdatedAt?: boolean | string;
     actions?: ActionManagerOptions;
+    keys?: ApiKeyManagerOptions;
+    kv?: KVStoreOptions;
+    storage?: BlobStorageManagerOptions;
+    scheduler?: JobSchedulerOptions;
+    session?: SessionManagerOptions;
 }
 export declare class TransactionalClient {
     private parent;
@@ -89,6 +100,12 @@ export declare class LocalFirstClient {
     touchColumn: string | null;
     readonly maintenance: DatabaseMaintenance;
     readonly actions: ActionManager;
+    readonly keys: ApiKeyManager;
+    readonly kv: KVManager;
+    readonly search: SearchManager;
+    readonly storage: BlobStorageManager;
+    readonly scheduler: JobScheduler;
+    readonly session: SessionManager;
     private primaryKey;
     private migrations;
     private autoStart;
@@ -328,6 +345,7 @@ export declare class LocalFirstClient {
      */
     reset(options?: {
         dropTables?: boolean;
+        includeInternal?: boolean;
     }): Promise<void>;
     private getAllTableNames;
     /**

package/dist/core/client.js

@@ -15,6 +15,12 @@ const query_builder_js_1 = require("./query-builder.js");
 const portability_js_1 = require("../utils/portability.js");
 const index_js_1 = require("../backups/index.js");
 const index_js_2 = require("../actions/index.js");
+const index_js_3 = require("../keys/index.js");
+const index_js_4 = require("../kv/index.js");
+const index_js_5 = require("../search/index.js");
+const index_js_6 = require("../storage/index.js");
+const index_js_7 = require("../scheduler/index.js");
+const session_js_1 = require("../auth/session.js");
 function hasFunctionFilter(value) {
     if (typeof value === 'function')
         return true;
@@ -168,6 +174,12 @@ class LocalFirstClient {
     touchColumn;
     maintenance;
     actions;
+    keys;
+    kv;
+    search;
+    storage;
+    scheduler;
+    session;
     primaryKey;
     migrations;
     autoStart;
@@ -192,8 +204,30 @@ class LocalFirstClient {
                     ? touch
                     : this.remote?.updatedAtColumn || 'updated_at';
         this.schemaManager = new schema_manager_js_1.SchemaManager();
-        this.maintenance = new maintenance_js_1.DatabaseMaintenance(this.db, () => this.tables);
+        this.maintenance = new maintenance_js_1.DatabaseMaintenance(this.db, () => [
+            ...this.tables,
+            '_local_kv',
+            '_local_blobs',
+            '_local_scheduled_jobs',
+            '_local_job_runs',
+            '_local_api_keys',
+            '_local_actions',
+            '_local_sessions',
+            '_local_sessions',
+        ]);
         const actionNetwork = config.actions?.network ?? config.network;
+        this.keys = new index_js_3.ApiKeyManager(this.db, config.keys);
+        this.kv = new index_js_4.KVManager(this.db, this.events, config.kv);
+        this.search = new index_js_5.SearchManager(this.db, this.events, (table, id) => this.findById(table, id));
+        this.storage = new index_js_6.BlobStorageManager(this.db, {
+            network: config.network,
+            ...config.storage,
+        });
+        this.scheduler = new index_js_7.JobScheduler(this.db, config.scheduler);
+        this.session = new session_js_1.SessionManager(this.db, this.events, {
+            network: config.network,
+            ...config.session,
+        });
         this.actions = new index_js_2.ActionManager(this.db, this.events, () => Promise.resolve(actionNetwork ? actionNetwork.isOnline() : true), {
             network: actionNetwork,
             ...config.actions,
@@ -357,6 +391,11 @@ class LocalFirstClient {
         await meta_store_js_1.MetaStore.ensureSchema(this.db);
         await outbox_store_js_1.OutboxStore.resetStaleProcessing(this.db);
         await this.actions.initialize();
+        await this.keys.initialize();
+        await this.kv.initialize();
+        await this.storage.initialize();
+        await this.scheduler.initialize();
+        await this.session.initialize();
         if (this.migrations.length > 0) {
             await this.db.transaction(async (tx) => {
                 for (const query of this.migrations) {
@@ -871,6 +910,7 @@ class LocalFirstClient {
     stop() {
         this.syncWorker.stop();
         this.actions.stop();
+        this.scheduler.stop();
     }
     /**
      * Stops background sync workers, cleans up remote listeners,
@@ -891,7 +931,20 @@ class LocalFirstClient {
      */
     async reset(options = {}) {
         this.stop();
-        const tablesToReset = Array.from(new Set([...this.tables, 'sync_outbox', 'sync_meta']));
+        const internalTables = [
+            '_local_kv',
+            '_local_blobs',
+            '_local_scheduled_jobs',
+            '_local_job_runs',
+            '_local_api_keys',
+            '_local_actions',
+        ];
+        const tablesToReset = Array.from(new Set([
+            ...this.tables,
+            'sync_outbox',
+            'sync_meta',
+            ...(options.includeInternal ? internalTables : []),
+        ]));
         for (const table of tablesToReset) {
             try {
                 if (options.dropTables) {

package/dist/index.d.ts

@@ -23,3 +23,8 @@ export * from './schema/index.js';
 export * from './auth/index.js';
 export * from './backups/index.js';
 export * from './actions/index.js';
+export * from './keys/index.js';
+export * from './kv/index.js';
+export * from './search/index.js';
+export * from './storage/index.js';
+export * from './scheduler/index.js';

package/dist/index.js

@@ -39,3 +39,8 @@ __exportStar(require("./schema/index.js"), exports);
 __exportStar(require("./auth/index.js"), exports);
 __exportStar(require("./backups/index.js"), exports);
 __exportStar(require("./actions/index.js"), exports);
+__exportStar(require("./keys/index.js"), exports);
+__exportStar(require("./kv/index.js"), exports);
+__exportStar(require("./search/index.js"), exports);
+__exportStar(require("./storage/index.js"), exports);
+__exportStar(require("./scheduler/index.js"), exports);

package/dist/keys/generator.d.ts

@@ -0,0 +1,38 @@
+import { GenerateApiKeyOptions, GeneratedApiKey } from './types.js';
+/**
+ * Generates cryptographically secure random bytes across Web, Expo/React Native, and Node.js.
+ */
+export declare function getRandomBytes(length: number): Uint8Array;
+/**
+ * Encodes raw bytes into a base62 string.
+ */
+export declare function bytesToBase62(bytes: Uint8Array): string;
+/**
+ * Calculates a 4-byte (8-char hex) checksum over the prefix and random entropy.
+ */
+export declare function calculateKeyChecksum(content: string): string;
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ */
+export declare function timingSafeEqual(a: string, b: string): boolean;
+/**
+ * Hashes an API key using SHA-256 for secure storage.
+ */
+export declare function hashApiKey(key: string): string;
+/**
+ * Generates an industry-standard, cryptographically secure API key.
+ * Format: [prefix]_[entropy]_[checksum]
+ *
+ * Example:
+ * prop_a7F9x2K1m8P0qW4z_c4f910e2
+ */
+export declare function generateApiKey(options?: GenerateApiKeyOptions): GeneratedApiKey;
+/**
+ * Verifies whether a key string is syntactically valid and has an authentic checksum.
+ * Does not require a database lookup.
+ */
+export declare function verifyApiKeyFormat(key: string, expectedPrefix?: string): boolean;
+/**
+ * Validates a raw API key against a stored SHA-256 hash in constant time.
+ */
+export declare function verifyApiKey(rawKey: string, storedHash: string, expectedPrefix?: string): boolean;