local-lite 0.0.18 → 0.0.20

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;

package/dist/keys/types.d.ts

@@ -0,0 +1,95 @@
+export interface GenerateApiKeyOptions {
+    /**
+     * Prefix for the API key (e.g. 'prop', 'sk_live', 'pk_test').
+     * Default: 'key'
+     */
+    prefix?: string;
+    /**
+     * Number of random entropy bytes (higher is more secure).
+     * Default: 24 bytes (192 bits of entropy)
+     */
+    byteLength?: number;
+    /**
+     * Whether to embed a 4-byte checksum at the end of the key for instant validation.
+     * Default: true
+     */
+    withChecksum?: boolean;
+    /**
+     * Human-readable label or description for this key.
+     */
+    name?: string;
+    /**
+     * Arbitrary metadata (e.g. { businessId, scopes, ownerId }).
+     */
+    metadata?: Record<string, any>;
+    /**
+     * Expiration window in milliseconds from creation time.
+     */
+    expiresInMs?: number;
+    /**
+     * Explicit expiration timestamp in milliseconds.
+     */
+    expiresAt?: number;
+}
+export interface GeneratedApiKey {
+    /**
+     * The raw plaintext key string to return to the user (only shown once!).
+     * e.g. "prop_a7F9x..._c4b2"
+     */
+    key: string;
+    /**
+     * Cryptographic SHA-256 hash of the key for secure database storage.
+     */
+    keyHash: string;
+    /**
+     * Key prefix.
+     */
+    prefix: string;
+    /**
+     * Masked display string safe to show in UI (e.g. "prop_...c4b2").
+     */
+    display: string;
+}
+export interface ApiKeyRecord {
+    id: string;
+    name: string;
+    prefix: string;
+    display: string;
+    keyHash: string;
+    metadata?: Record<string, any>;
+    createdAt: number;
+    expiresAt?: number | null;
+    lastUsedAt?: number | null;
+    revoked: boolean;
+    revokedAt?: number | null;
+}
+export type KeyVerificationStatus = 'VALID' | 'INVALID' | 'EXPIRED' | 'REVOKED' | 'MALFORMED';
+export interface VerifyStoredKeyResult {
+    valid: boolean;
+    status: KeyVerificationStatus;
+    record?: ApiKeyRecord;
+    error?: string;
+}
+export interface CreateSignedTokenOptions<T = Record<string, any>> {
+    payload: T;
+    secret: string;
+    expiresInMs?: number;
+    expiresAt?: number;
+    tokenId?: string;
+}
+export interface VerifySignedTokenResult<T = Record<string, any>> {
+    valid: boolean;
+    expired?: boolean;
+    payload?: T;
+    expiresAt?: number | null;
+    tokenId?: string;
+    error?: string;
+}
+export interface RenewSignedTokenOptions {
+    extendMs?: number;
+    newExpiresAt?: number;
+    secret?: string;
+}
+export interface ApiKeyManagerOptions {
+    tableName?: string;
+}

package/dist/keys/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/kv/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types.js';
+export * from './store.js';
+export * from './manager.js';

package/dist/kv/index.js

@@ -0,0 +1,19 @@
+"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("./store.js"), exports);
+__exportStar(require("./manager.js"), exports);

package/dist/kv/manager.d.ts

@@ -0,0 +1,52 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { EventEmitter } from '../reactive/event-emitter.js';
+import { KVRecord, KVSetOptions, KVSetSecretOptions, KVStoreOptions } from './types.js';
+export declare class KVManager {
+    private db;
+    private tableName;
+    private events?;
+    constructor(db: DBExecutable, eventsOrOptions?: EventEmitter | KVStoreOptions, options?: KVStoreOptions);
+    initialize(): Promise<void>;
+    /**
+     * Sets a value in the key-value store with optional TTL.
+     * Emits an event on the event emitter if configured.
+     */
+    set(key: string, value: any, options?: KVSetOptions): Promise<void>;
+    /**
+     * Retrieves the value for a key, returning defaultValue if not found or expired.
+     */
+    get<T = any>(key: string, defaultValue?: T): Promise<T | undefined>;
+    /**
+     * Retrieves the full KVRecord metadata for a key.
+     */
+    getRecord(key: string): Promise<KVRecord | null>;
+    /**
+     * Checks whether a non-expired key exists in the store.
+     */
+    has(key: string): Promise<boolean>;
+    /**
+     * Removes a key from the store.
+     * Emits an event on the event emitter if configured.
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Lists all non-expired keys, optionally filtered by a prefix.
+     */
+    keys(prefix?: string): Promise<string[]>;
+    /**
+     * Clears all stored key-value pairs.
+     */
+    clear(): Promise<void>;
+    /**
+     * Stores an encrypted secret using AES-256-GCM + PBKDF2 passphrase encryption.
+     */
+    setSecret(key: string, secretValue: any, options: KVSetSecretOptions): Promise<void>;
+    /**
+     * Decrypts and retrieves a stored secret.
+     */
+    getSecret<T = any>(key: string, passphrase: string, defaultValue?: T): Promise<T | undefined>;
+    /**
+     * Purges all expired keys immediately.
+     */
+    pruneExpired(): Promise<number>;
+}

package/dist/kv/manager.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KVManager = void 0;
+const encryption_js_1 = require("../backups/encryption.js");
+const signed_token_js_1 = require("../keys/signed-token.js");
+const store_js_1 = require("./store.js");
+class KVManager {
+    db;
+    tableName;
+    events;
+    constructor(db, eventsOrOptions, options) {
+        this.db = db;
+        let opts = {};
+        if (eventsOrOptions && typeof eventsOrOptions.emit === 'function') {
+            this.events = eventsOrOptions;
+            opts = options || {};
+        }
+        else if (eventsOrOptions) {
+            opts = eventsOrOptions;
+        }
+        this.tableName = opts.tableName ?? store_js_1.DEFAULT_KV_TABLE;
+    }
+    async initialize() {
+        await store_js_1.KVStore.ensureSchema(this.db, this.tableName);
+    }
+    /**
+     * Sets a value in the key-value store with optional TTL.
+     * Emits an event on the event emitter if configured.
+     */
+    async set(key, value, options = {}) {
+        const now = Date.now();
+        const expiresAt = options.expiresAt !== undefined
+            ? options.expiresAt
+            : options.ttlMs !== undefined
+                ? now + options.ttlMs
+                : null;
+        let type;
+        let valueStr;
+        if (typeof value === 'string') {
+            type = 'string';
+            valueStr = value;
+        }
+        else if (typeof value === 'number') {
+            type = 'number';
+            valueStr = String(value);
+        }
+        else if (typeof value === 'boolean') {
+            type = 'boolean';
+            valueStr = value ? '1' : '0';
+        }
+        else {
+            type = 'json';
+            valueStr = JSON.stringify(value ?? null);
+        }
+        await store_js_1.KVStore.set(this.db, this.tableName, key, valueStr, type, now, expiresAt);
+        this.events?.emit(this.tableName, { operation: 'SET', key, value });
+    }
+    /**
+     * Retrieves the value for a key, returning defaultValue if not found or expired.
+     */
+    async get(key, defaultValue) {
+        const record = await store_js_1.KVStore.get(this.db, this.tableName, key);
+        if (!record)
+            return defaultValue;
+        if (record.expiresAt && record.expiresAt <= Date.now()) {
+            // Lazy deletion of expired key
+            store_js_1.KVStore.delete(this.db, this.tableName, key).catch(() => { });
+            return defaultValue;
+        }
+        return record.value;
+    }
+    /**
+     * Retrieves the full KVRecord metadata for a key.
+     */
+    async getRecord(key) {
+        const record = await store_js_1.KVStore.get(this.db, this.tableName, key);
+        if (!record)
+            return null;
+        if (record.expiresAt && record.expiresAt <= Date.now()) {
+            store_js_1.KVStore.delete(this.db, this.tableName, key).catch(() => { });
+            return null;
+        }
+        return record;
+    }
+    /**
+     * Checks whether a non-expired key exists in the store.
+     */
+    async has(key) {
+        const val = await this.get(key);
+        return val !== undefined;
+    }
+    /**
+     * Removes a key from the store.
+     * Emits an event on the event emitter if configured.
+     */
+    async delete(key) {
+        await store_js_1.KVStore.delete(this.db, this.tableName, key);
+        this.events?.emit(this.tableName, { operation: 'DELETE', key });
+    }
+    /**
+     * Lists all non-expired keys, optionally filtered by a prefix.
+     */
+    async keys(prefix) {
+        return store_js_1.KVStore.listKeys(this.db, this.tableName, prefix);
+    }
+    /**
+     * Clears all stored key-value pairs.
+     */
+    async clear() {
+        await store_js_1.KVStore.clear(this.db, this.tableName);
+        this.events?.emit(this.tableName, { operation: 'CLEAR' });
+    }
+    /**
+     * Stores an encrypted secret using AES-256-GCM + PBKDF2 passphrase encryption.
+     */
+    async setSecret(key, secretValue, options) {
+        if (!options.passphrase) {
+            throw new Error('Passphrase is required to store encrypted secret.');
+        }
+        const strValue = typeof secretValue === 'string' ? secretValue : JSON.stringify(secretValue);
+        const plainBytes = new TextEncoder().encode(strValue);
+        const encryptedBytes = await (0, encryption_js_1.encryptBackupData)(plainBytes, options.passphrase);
+        const encryptedBase64 = (0, signed_token_js_1.base64UrlEncode)(encryptedBytes);
+        const now = Date.now();
+        const expiresAt = options.expiresAt !== undefined
+            ? options.expiresAt
+            : options.ttlMs !== undefined
+                ? now + options.ttlMs
+                : null;
+        await store_js_1.KVStore.set(this.db, this.tableName, key, encryptedBase64, 'encrypted', now, expiresAt);
+        this.events?.emit(this.tableName, { operation: 'SET_SECRET', key });
+    }
+    /**
+     * Decrypts and retrieves a stored secret.
+     */
+    async getSecret(key, passphrase, defaultValue) {
+        const record = await store_js_1.KVStore.get(this.db, this.tableName, key);
+        if (!record)
+            return defaultValue;
+        if (record.expiresAt && record.expiresAt <= Date.now()) {
+            store_js_1.KVStore.delete(this.db, this.tableName, key).catch(() => { });
+            return defaultValue;
+        }
+        if (record.type !== 'encrypted') {
+            return record.value;
+        }
+        const encryptedBytes = (0, signed_token_js_1.base64UrlDecode)(record.value);
+        const decryptedBytes = await (0, encryption_js_1.decryptBackupData)(encryptedBytes, passphrase);
+        const text = new TextDecoder().decode(decryptedBytes);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return text;
+        }
+    }
+    /**
+     * Purges all expired keys immediately.
+     */
+    async pruneExpired() {
+        return store_js_1.KVStore.pruneExpired(this.db, this.tableName);
+    }
+}
+exports.KVManager = KVManager;

package/dist/kv/store.d.ts

@@ -0,0 +1,13 @@
+import { DBExecutable } from '../core/schema-manager.js';
+import { KVRecord } from './types.js';
+export declare const DEFAULT_KV_TABLE = "_local_kv";
+export declare function mapKVRow(r: any): KVRecord;
+export declare class KVStore {
+    static ensureSchema(db: DBExecutable, tableName?: string): Promise<void>;
+    static set(db: DBExecutable, tableName: string | undefined, key: string, valueStr: string, type: string, now: number, expiresAt: number | null): Promise<void>;
+    static get(db: DBExecutable, tableName: string | undefined, key: string): Promise<KVRecord | null>;
+    static delete(db: DBExecutable, tableName: string | undefined, key: string): Promise<boolean>;
+    static listKeys(db: DBExecutable, tableName?: string, prefix?: string): Promise<string[]>;
+    static clear(db: DBExecutable, tableName?: string): Promise<void>;
+    static pruneExpired(db: DBExecutable, tableName?: string): Promise<number>;
+}