local-lite 0.0.19 → 0.0.21

package/dist/keys/generator.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getRandomBytes = getRandomBytes;
+exports.bytesToBase62 = bytesToBase62;
+exports.calculateKeyChecksum = calculateKeyChecksum;
+exports.timingSafeEqual = timingSafeEqual;
+exports.hashApiKey = hashApiKey;
+exports.generateApiKey = generateApiKey;
+exports.verifyApiKeyFormat = verifyApiKeyFormat;
+exports.verifyApiKey = verifyApiKey;
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const BASE62_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+/**
+ * Generates cryptographically secure random bytes across Web, Expo/React Native, and Node.js.
+ */
+function getRandomBytes(length) {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj?.getRandomValues) {
+        return cryptoObj.getRandomValues(new Uint8Array(length));
+    }
+    try {
+        // Dynamic fallback for Node.js environments without globalThis.crypto
+        const nodeCrypto = globalThis.process?.versions?.node
+            ? globalThis.require('node:crypto')
+            : null;
+        if (nodeCrypto?.randomBytes) {
+            return new Uint8Array(nodeCrypto.randomBytes(length));
+        }
+    }
+    catch {
+        // Fallback ignored
+    }
+    throw new Error('Cryptographically secure random number generator is unavailable.');
+}
+/**
+ * Encodes raw bytes into a base62 string.
+ */
+function bytesToBase62(bytes) {
+    let result = '';
+    for (let i = 0; i < bytes.length; i++) {
+        result += BASE62_ALPHABET[bytes[i] % 62];
+    }
+    return result;
+}
+/**
+ * Calculates a 4-byte (8-char hex) checksum over the prefix and random entropy.
+ */
+function calculateKeyChecksum(content) {
+    const hash = (0, sha2_js_1.sha256)((0, utils_js_1.utf8ToBytes)(content));
+    return (0, utils_js_1.bytesToHex)(hash.slice(0, 4));
+}
+/**
+ * Constant-time string comparison to prevent timing attacks.
+ */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let mismatch = 0;
+    for (let i = 0; i < a.length; i++) {
+        mismatch |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return mismatch === 0;
+}
+/**
+ * Hashes an API key using SHA-256 for secure storage.
+ */
+function hashApiKey(key) {
+    return (0, utils_js_1.bytesToHex)((0, sha2_js_1.sha256)((0, utils_js_1.utf8ToBytes)(key.trim())));
+}
+/**
+ * Generates an industry-standard, cryptographically secure API key.
+ * Format: [prefix]_[entropy]_[checksum]
+ *
+ * Example:
+ * prop_a7F9x2K1m8P0qW4z_c4f910e2
+ */
+function generateApiKey(options = {}) {
+    const prefix = (options.prefix || 'key').trim().toLowerCase().replace(/[^a-z0-9_-]/g, '');
+    const byteLength = options.byteLength ?? 24;
+    const withChecksum = options.withChecksum ?? true;
+    const entropyBytes = getRandomBytes(byteLength);
+    const entropy = bytesToBase62(entropyBytes);
+    let key;
+    let checksum = '';
+    if (withChecksum) {
+        checksum = calculateKeyChecksum(`${prefix}_${entropy}`);
+        key = `${prefix}_${entropy}_${checksum}`;
+    }
+    else {
+        key = `${prefix}_${entropy}`;
+    }
+    const keyHash = hashApiKey(key);
+    // Masked display representation (e.g. prop_...c4f910e2)
+    const suffix = key.slice(-6);
+    const display = `${prefix}_...${suffix}`;
+    return {
+        key,
+        keyHash,
+        prefix,
+        display,
+    };
+}
+/**
+ * Verifies whether a key string is syntactically valid and has an authentic checksum.
+ * Does not require a database lookup.
+ */
+function verifyApiKeyFormat(key, expectedPrefix) {
+    if (!key || typeof key !== 'string')
+        return false;
+    const parts = key.trim().split('_');
+    if (parts.length < 2)
+        return false;
+    const prefix = parts[0];
+    if (expectedPrefix && prefix !== expectedPrefix)
+        return false;
+    // Checksummed format: [prefix]_[entropy]_[checksum]
+    if (parts.length >= 3) {
+        const checksum = parts[parts.length - 1];
+        const content = parts.slice(0, parts.length - 1).join('_');
+        const expectedChecksum = calculateKeyChecksum(content);
+        return timingSafeEqual(checksum, expectedChecksum);
+    }
+    return true;
+}
+/**
+ * Validates a raw API key against a stored SHA-256 hash in constant time.
+ */
+function verifyApiKey(rawKey, storedHash, expectedPrefix) {
+    if (!verifyApiKeyFormat(rawKey, expectedPrefix)) {
+        return false;
+    }
+    const computedHash = hashApiKey(rawKey);
+    return timingSafeEqual(computedHash, storedHash);
+}

package/dist/keys/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './generator.js';
+export * from './signed-token.js';
+export * from './store.js';
+export * from './manager.js';

package/dist/keys/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./generator.js"), exports);
+__exportStar(require("./signed-token.js"), exports);
+__exportStar(require("./store.js"), exports);
+__exportStar(require("./manager.js"), exports);

package/dist/keys/manager.d.ts

@@ -0,0 +1,59 @@
+import { LocalDBAdapter } from '../adapters/local/index.js';
+import { ApiKeyManagerOptions, ApiKeyRecord, CreateSignedTokenOptions, GenerateApiKeyOptions, RenewSignedTokenOptions, VerifySignedTokenResult, VerifyStoredKeyResult } from './types.js';
+export declare class ApiKeyManager {
+    private db;
+    private tableName;
+    constructor(db: LocalDBAdapter, options?: ApiKeyManagerOptions);
+    /**
+     * Initializes the API keys database table and indexes.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Generates a new cryptographically secure API key and persists its hash to SQLite.
+     * Returns the plaintext key (to show to the user once) along with the stored record.
+     */
+    create(options?: GenerateApiKeyOptions): Promise<{
+        key: string;
+        record: ApiKeyRecord;
+    }>;
+    /**
+     * Verifies an incoming raw API key against stored hashes in SQLite.
+     * Checks format, checksum, expiration, and revocation status.
+     */
+    verify(rawKey: string, options?: {
+        updateLastUsed?: boolean;
+        expectedPrefix?: string;
+    }): Promise<VerifyStoredKeyResult>;
+    /**
+     * Revokes an existing API key by ID.
+     */
+    revoke(id: string): Promise<boolean>;
+    /**
+     * Lists stored API key records with optional filters.
+     */
+    list(filter?: {
+        revoked?: boolean;
+        prefix?: string;
+    }): Promise<ApiKeyRecord[]>;
+    /**
+     * Prunes revoked or expired key records.
+     */
+    prune(options?: {
+        revokedOlderThanMs?: number;
+        expiredOlderThanMs?: number;
+    }): Promise<number>;
+    /**
+     * Helper to create a signed, tamper-evident token with expiration.
+     */
+    createSignedToken<T = Record<string, any>>(options: CreateSignedTokenOptions<T>): string;
+    /**
+     * Helper to verify a signed token's signature and expiration.
+     */
+    verifySignedToken<T = Record<string, any>>(token: string, secret: string, options?: {
+        clockSkewSeconds?: number;
+    }): VerifySignedTokenResult<T>;
+    /**
+     * Helper to renew an existing signed token by extending its expiration.
+     */
+    renewSignedToken<T = Record<string, any>>(token: string, secret: string, options?: RenewSignedTokenOptions): string;
+}

package/dist/keys/manager.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiKeyManager = void 0;
+const uuid_js_1 = require("../utils/uuid.js");
+const generator_js_1 = require("./generator.js");
+const signed_token_js_1 = require("./signed-token.js");
+const store_js_1 = require("./store.js");
+class ApiKeyManager {
+    db;
+    tableName;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.tableName = options.tableName || store_js_1.DEFAULT_KEYS_TABLE;
+    }
+    /**
+     * Initializes the API keys database table and indexes.
+     */
+    async initialize() {
+        await store_js_1.KeyStore.ensureSchema(this.db, this.tableName);
+    }
+    /**
+     * Generates a new cryptographically secure API key and persists its hash to SQLite.
+     * Returns the plaintext key (to show to the user once) along with the stored record.
+     */
+    async create(options = {}) {
+        const generated = (0, generator_js_1.generateApiKey)(options);
+        const now = Date.now();
+        const expiresAt = options.expiresAt !== undefined
+            ? options.expiresAt
+            : options.expiresInMs !== undefined
+                ? now + options.expiresInMs
+                : null;
+        const record = {
+            id: (0, uuid_js_1.generateUUID)(),
+            name: options.name || `${generated.prefix} key`,
+            prefix: generated.prefix,
+            display: generated.display,
+            keyHash: generated.keyHash,
+            metadata: options.metadata,
+            createdAt: now,
+            expiresAt,
+            lastUsedAt: null,
+            revoked: false,
+            revokedAt: null,
+        };
+        await store_js_1.KeyStore.insertRecord(this.db, this.tableName, record);
+        return {
+            key: generated.key,
+            record,
+        };
+    }
+    /**
+     * Verifies an incoming raw API key against stored hashes in SQLite.
+     * Checks format, checksum, expiration, and revocation status.
+     */
+    async verify(rawKey, options = {}) {
+        if (!rawKey || typeof rawKey !== 'string') {
+            return { valid: false, status: 'MALFORMED', error: 'API key is missing or not a string' };
+        }
+        // 1. Instant syntactic & checksum format verification
+        if (!(0, generator_js_1.verifyApiKeyFormat)(rawKey, options.expectedPrefix)) {
+            return { valid: false, status: 'MALFORMED', error: 'Invalid API key format or checksum' };
+        }
+        // 2. Hash and lookup in database
+        const computedHash = (0, generator_js_1.hashApiKey)(rawKey);
+        const record = await store_js_1.KeyStore.findByHash(this.db, this.tableName, computedHash);
+        if (!record) {
+            return { valid: false, status: 'INVALID', error: 'API key not found' };
+        }
+        // 3. Check revocation
+        if (record.revoked) {
+            return { valid: false, status: 'REVOKED', record, error: 'API key has been revoked' };
+        }
+        // 4. Check expiration
+        if (record.expiresAt && record.expiresAt <= Date.now()) {
+            return { valid: false, status: 'EXPIRED', record, error: 'API key has expired' };
+        }
+        // 5. Update last_used_at timestamp
+        if (options.updateLastUsed !== false) {
+            const now = Date.now();
+            record.lastUsedAt = now;
+            store_js_1.KeyStore.updateLastUsed(this.db, this.tableName, record.id, now).catch(() => { });
+        }
+        return {
+            valid: true,
+            status: 'VALID',
+            record,
+        };
+    }
+    /**
+     * Revokes an existing API key by ID.
+     */
+    async revoke(id) {
+        return store_js_1.KeyStore.revoke(this.db, this.tableName, id);
+    }
+    /**
+     * Lists stored API key records with optional filters.
+     */
+    async list(filter) {
+        return store_js_1.KeyStore.list(this.db, this.tableName, filter);
+    }
+    /**
+     * Prunes revoked or expired key records.
+     */
+    async prune(options) {
+        return store_js_1.KeyStore.prune(this.db, this.tableName, options);
+    }
+    /**
+     * Helper to create a signed, tamper-evident token with expiration.
+     */
+    createSignedToken(options) {
+        return (0, signed_token_js_1.createSignedToken)(options);
+    }
+    /**
+     * Helper to verify a signed token's signature and expiration.
+     */
+    verifySignedToken(token, secret, options) {
+        return (0, signed_token_js_1.verifySignedToken)(token, secret, options);
+    }
+    /**
+     * Helper to renew an existing signed token by extending its expiration.
+     */
+    renewSignedToken(token, secret, options) {
+        return (0, signed_token_js_1.renewSignedToken)(token, secret, options);
+    }
+}
+exports.ApiKeyManager = ApiKeyManager;

package/dist/keys/signed-token.d.ts

@@ -0,0 +1,18 @@
+import { CreateSignedTokenOptions, RenewSignedTokenOptions, VerifySignedTokenResult } from './types.js';
+export declare function base64UrlEncode(bytes: Uint8Array): string;
+export declare function base64UrlDecode(str: string): Uint8Array;
+/**
+ * Creates a signed, tamper-evident token with optional expiration and token ID.
+ * Format: [base64urlHeader].[base64urlPayload].[signature]
+ */
+export declare function createSignedToken<T = Record<string, any>>(options: CreateSignedTokenOptions<T>): string;
+/**
+ * Verifies a signed token's cryptographic HMAC signature and expiration timestamp.
+ */
+export declare function verifySignedToken<T = Record<string, any>>(token: string, secret: string, options?: {
+    clockSkewSeconds?: number;
+}): VerifySignedTokenResult<T>;
+/**
+ * Renews an existing valid signed token by extending its expiration time with a fresh signature.
+ */
+export declare function renewSignedToken<T = Record<string, any>>(token: string, secret: string, options?: RenewSignedTokenOptions): string;

package/dist/keys/signed-token.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.base64UrlEncode = base64UrlEncode;
+exports.base64UrlDecode = base64UrlDecode;
+exports.createSignedToken = createSignedToken;
+exports.verifySignedToken = verifySignedToken;
+exports.renewSignedToken = renewSignedToken;
+const hmac_js_1 = require("@noble/hashes/hmac.js");
+const sha2_js_1 = require("@noble/hashes/sha2.js");
+const utils_js_1 = require("@noble/hashes/utils.js");
+const uuid_js_1 = require("../utils/uuid.js");
+const generator_js_1 = require("./generator.js");
+const B64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const B64URL_LOOKUP = new Uint8Array(256);
+for (let i = 0; i < B64URL_ALPHABET.length; i++) {
+    B64URL_LOOKUP[B64URL_ALPHABET.charCodeAt(i)] = i;
+}
+function base64UrlEncode(bytes) {
+    let result = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const first = bytes[i];
+        const second = bytes[i + 1];
+        const third = bytes[i + 2];
+        result += B64URL_ALPHABET[first >> 2];
+        result += B64URL_ALPHABET[((first & 3) << 4) | (second === undefined ? 0 : second >> 4)];
+        if (second !== undefined) {
+            result += B64URL_ALPHABET[((second & 15) << 2) | (third === undefined ? 0 : third >> 6)];
+        }
+        if (third !== undefined) {
+            result += B64URL_ALPHABET[third & 63];
+        }
+    }
+    return result;
+}
+function base64UrlDecode(str) {
+    // Normalize base64url padding
+    let clean = str.replace(/[^A-Za-z0-9\-_]/g, '');
+    const remainder = clean.length % 4;
+    if (remainder === 2)
+        clean += '==';
+    else if (remainder === 3)
+        clean += '=';
+    const len = clean.length;
+    let byteLen = (len * 3) / 4;
+    if (clean.endsWith('=='))
+        byteLen -= 2;
+    else if (clean.endsWith('='))
+        byteLen -= 1;
+    const bytes = new Uint8Array(byteLen);
+    let byteIndex = 0;
+    for (let i = 0; i < len; i += 4) {
+        const c0 = B64URL_LOOKUP[clean.charCodeAt(i)];
+        const c1 = B64URL_LOOKUP[clean.charCodeAt(i + 1)];
+        const c2 = clean[i + 2] === '=' ? 0 : B64URL_LOOKUP[clean.charCodeAt(i + 2)];
+        const c3 = clean[i + 3] === '=' ? 0 : B64URL_LOOKUP[clean.charCodeAt(i + 3)];
+        bytes[byteIndex++] = (c0 << 2) | (c1 >> 4);
+        if (clean[i + 2] !== '=' && byteIndex < byteLen) {
+            bytes[byteIndex++] = ((c1 & 15) << 4) | (c2 >> 2);
+        }
+        if (clean[i + 3] !== '=' && byteIndex < byteLen) {
+            bytes[byteIndex++] = ((c2 & 3) << 6) | c3;
+        }
+    }
+    return bytes;
+}
+function computeHmacSignature(content, secret) {
+    const sigBytes = (0, hmac_js_1.hmac)(sha2_js_1.sha256, (0, utils_js_1.utf8ToBytes)(secret), (0, utils_js_1.utf8ToBytes)(content));
+    return base64UrlEncode(sigBytes);
+}
+/**
+ * Creates a signed, tamper-evident token with optional expiration and token ID.
+ * Format: [base64urlHeader].[base64urlPayload].[signature]
+ */
+function createSignedToken(options) {
+    if (!options.secret) {
+        throw new Error('Signing secret is required to create a signed token.');
+    }
+    const now = Date.now();
+    const expiresAt = options.expiresAt !== undefined
+        ? options.expiresAt
+        : options.expiresInMs !== undefined
+            ? now + options.expiresInMs
+            : null;
+    const header = {
+        alg: 'HS256',
+        typ: 'LLT',
+    };
+    const payload = {
+        data: options.payload,
+        iat: now,
+        exp: expiresAt,
+        jti: options.tokenId || (0, uuid_js_1.generateUUID)(),
+    };
+    const headerB64 = base64UrlEncode((0, utils_js_1.utf8ToBytes)(JSON.stringify(header)));
+    const payloadB64 = base64UrlEncode((0, utils_js_1.utf8ToBytes)(JSON.stringify(payload)));
+    const content = `${headerB64}.${payloadB64}`;
+    const signature = computeHmacSignature(content, options.secret);
+    return `${content}.${signature}`;
+}
+/**
+ * Verifies a signed token's cryptographic HMAC signature and expiration timestamp.
+ */
+function verifySignedToken(token, secret, options = {}) {
+    if (!token || typeof token !== 'string') {
+        return { valid: false, error: 'Token is missing or empty' };
+    }
+    if (!secret) {
+        return { valid: false, error: 'Verification secret is required' };
+    }
+    const parts = token.trim().split('.');
+    if (parts.length !== 3) {
+        return { valid: false, error: 'Malformed token structure: expected 3 parts' };
+    }
+    const [headerB64, payloadB64, signature] = parts;
+    const content = `${headerB64}.${payloadB64}`;
+    // 1. Verify HMAC Signature
+    const expectedSignature = computeHmacSignature(content, secret);
+    if (!(0, generator_js_1.timingSafeEqual)(signature, expectedSignature)) {
+        return { valid: false, error: 'Invalid token signature' };
+    }
+    // 2. Decode Payload
+    let parsedPayload;
+    try {
+        const jsonStr = new TextDecoder().decode(base64UrlDecode(payloadB64));
+        parsedPayload = JSON.parse(jsonStr);
+    }
+    catch (err) {
+        return { valid: false, error: `Failed to decode token payload: ${err?.message || err}` };
+    }
+    // 3. Verify Expiration
+    const clockSkewMs = (options.clockSkewSeconds ?? 60) * 1000;
+    const now = Date.now();
+    const exp = parsedPayload.exp;
+    if (exp != null && typeof exp === 'number') {
+        if (now > exp + clockSkewMs) {
+            return {
+                valid: false,
+                expired: true,
+                expiresAt: exp,
+                tokenId: parsedPayload.jti,
+                payload: parsedPayload.data,
+                error: `Token expired at ${new Date(exp).toISOString()}`,
+            };
+        }
+    }
+    return {
+        valid: true,
+        expired: false,
+        payload: parsedPayload.data,
+        expiresAt: exp ?? null,
+        tokenId: parsedPayload.jti,
+    };
+}
+/**
+ * Renews an existing valid signed token by extending its expiration time with a fresh signature.
+ */
+function renewSignedToken(token, secret, options = {}) {
+    const verification = verifySignedToken(token, secret);
+    if (!verification.valid && !verification.expired) {
+        throw new Error(`Cannot renew token: ${verification.error}`);
+    }
+    const extendMs = options.extendMs ?? 7 * 24 * 60 * 60 * 1000; // default 7 days
+    const newSecret = options.secret || secret;
+    return createSignedToken({
+        payload: verification.payload,
+        secret: newSecret,
+        expiresAt: options.newExpiresAt,
+        expiresInMs: options.newExpiresAt ? undefined : extendMs,
+        tokenId: verification.tokenId,
+    });
+}

package/dist/keys/store.d.ts

@@ -0,0 +1,23 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { ApiKeyRecord } from './types.js';
+export declare const DEFAULT_KEYS_TABLE = "_local_api_keys";
+export declare function mapKeyRow(r: any): ApiKeyRecord;
+export declare class KeyStore {
+    /**
+     * Initializes the API keys schema and indexes if they do not exist.
+     */
+    static ensureSchema(db: DBExecutable, tableName?: string): Promise<void>;
+    static insertRecord(db: DBExecutable, tableName: string | undefined, record: ApiKeyRecord): Promise<void>;
+    static findByHash(db: DBExecutable, tableName: string | undefined, hash: string): Promise<ApiKeyRecord | null>;
+    static findById(db: DBExecutable, tableName: string | undefined, id: string): Promise<ApiKeyRecord | null>;
+    static updateLastUsed(db: DBExecutable, tableName: string | undefined, id: string, timestamp: number): Promise<void>;
+    static revoke(db: DBExecutable, tableName: string | undefined, id: string): Promise<boolean>;
+    static list(db: DBExecutable, tableName?: string, filter?: {
+        revoked?: boolean;
+        prefix?: string;
+    }): Promise<ApiKeyRecord[]>;
+    static prune(db: DBExecutable, tableName?: string, options?: {
+        revokedOlderThanMs?: number;
+        expiredOlderThanMs?: number;
+    }): Promise<number>;
+}

package/dist/keys/store.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KeyStore = exports.DEFAULT_KEYS_TABLE = void 0;
+exports.mapKeyRow = mapKeyRow;
+exports.DEFAULT_KEYS_TABLE = '_local_api_keys';
+function mapKeyRow(r) {
+    return {
+        id: r.id,
+        name: r.name,
+        prefix: r.prefix,
+        display: r.display,
+        keyHash: r.key_hash,
+        metadata: r.metadata ? (typeof r.metadata === 'string' ? JSON.parse(r.metadata) : r.metadata) : undefined,
+        createdAt: Number(r.created_at || 0),
+        expiresAt: r.expires_at != null ? Number(r.expires_at) : null,
+        lastUsedAt: r.last_used_at != null ? Number(r.last_used_at) : null,
+        revoked: Boolean(Number(r.revoked || 0)),
+        revokedAt: r.revoked_at != null ? Number(r.revoked_at) : null,
+    };
+}
+class KeyStore {
+    /**
+     * Initializes the API keys schema and indexes if they do not exist.
+     */
+    static async ensureSchema(db, tableName = exports.DEFAULT_KEYS_TABLE) {
+        await db.execute(`CREATE TABLE IF NOT EXISTS ${tableName} (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        prefix TEXT NOT NULL,
+        display TEXT NOT NULL,
+        key_hash TEXT NOT NULL UNIQUE,
+        metadata TEXT,
+        created_at INTEGER NOT NULL,
+        expires_at INTEGER,
+        last_used_at INTEGER,
+        revoked INTEGER NOT NULL DEFAULT 0,
+        revoked_at INTEGER
+      );`);
+        await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_hash ON ${tableName} (key_hash);`);
+        await db.execute(`CREATE INDEX IF NOT EXISTS idx_${tableName}_revoked ON ${tableName} (revoked, expires_at);`);
+    }
+    static async insertRecord(db, tableName = exports.DEFAULT_KEYS_TABLE, record) {
+        await db.execute(`INSERT INTO ${tableName} (
+        id, name, prefix, display, key_hash, metadata, created_at, expires_at, last_used_at, revoked, revoked_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?);`, [
+            record.id,
+            record.name,
+            record.prefix,
+            record.display,
+            record.keyHash,
+            record.metadata ? JSON.stringify(record.metadata) : null,
+            record.createdAt,
+            record.expiresAt ?? null,
+            record.lastUsedAt ?? null,
+            record.revoked ? 1 : 0,
+            record.revokedAt ?? null,
+        ]);
+    }
+    static async findByHash(db, tableName = exports.DEFAULT_KEYS_TABLE, hash) {
+        const rows = await db.execute(`SELECT * FROM ${tableName} WHERE key_hash = ? LIMIT 1;`, [hash]);
+        if (!rows || rows.length === 0)
+            return null;
+        return mapKeyRow(rows[0]);
+    }
+    static async findById(db, tableName = exports.DEFAULT_KEYS_TABLE, id) {
+        const rows = await db.execute(`SELECT * FROM ${tableName} WHERE id = ? LIMIT 1;`, [id]);
+        if (!rows || rows.length === 0)
+            return null;
+        return mapKeyRow(rows[0]);
+    }
+    static async updateLastUsed(db, tableName = exports.DEFAULT_KEYS_TABLE, id, timestamp) {
+        await db.execute(`UPDATE ${tableName} SET last_used_at = ? WHERE id = ?;`, [timestamp, id]);
+    }
+    static async revoke(db, tableName = exports.DEFAULT_KEYS_TABLE, id) {
+        const now = Date.now();
+        await db.execute(`UPDATE ${tableName} SET revoked = 1, revoked_at = ? WHERE id = ? AND revoked = 0;`, [now, id]);
+        const updated = await this.findById(db, tableName, id);
+        return updated?.revoked === true;
+    }
+    static async list(db, tableName = exports.DEFAULT_KEYS_TABLE, filter = {}) {
+        const conditions = [];
+        const params = [];
+        if (filter.revoked !== undefined) {
+            conditions.push('revoked = ?');
+            params.push(filter.revoked ? 1 : 0);
+        }
+        if (filter.prefix !== undefined) {
+            conditions.push('prefix = ?');
+            params.push(filter.prefix);
+        }
+        const whereClause = conditions.length > 0 ? ` WHERE ${conditions.join(' AND ')}` : '';
+        const rows = await db.execute(`SELECT * FROM ${tableName}${whereClause} ORDER BY created_at DESC;`, params);
+        return (rows || []).map(mapKeyRow);
+    }
+    static async prune(db, tableName = exports.DEFAULT_KEYS_TABLE, options = {}) {
+        const now = Date.now();
+        let deletedCount = 0;
+        if (options.revokedOlderThanMs !== undefined) {
+            const cutoff = now - options.revokedOlderThanMs;
+            await db.execute(`DELETE FROM ${tableName} WHERE revoked = 1 AND revoked_at IS NOT NULL AND revoked_at <= ?;`, [cutoff]);
+        }
+        if (options.expiredOlderThanMs !== undefined) {
+            const cutoff = now - options.expiredOlderThanMs;
+            await db.execute(`DELETE FROM ${tableName} WHERE expires_at IS NOT NULL AND expires_at <= ?;`, [cutoff]);
+        }
+        return deletedCount;
+    }
+}
+exports.KeyStore = KeyStore;