byok-vault 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# byok-vault
+
+Browser-native BYOK vault for serverless/local-first AI apps.
+
+## Security Reality Check (Read First)
+
+- This project has **not** been formally audited.
+- It protects against passive issues (plaintext keys in storage, accidental exposure, low-effort scraping).
+- It does **not** protect against active in-origin script injection (XSS). If malicious JS executes on your origin, it can still intercept decrypted keys in-flight.
+- `sessionStorage` caching is a UX optimization to reduce passphrase prompts, **not** a stronger security boundary.
+
+If your threat model requires resistance to active injection attacks, use a server-side proxy.
+
+## What It Provides
+
+- AES-GCM encryption at rest in `localStorage`.
+- PBKDF2 key derivation (default `200,000` iterations) with per-user random salt.
+- Scoped key access via `withKey(async (key) => { ... })`.
+- Optional token circuit breaker with:
+  - pre-flight soft check (`requestedTokens`)
+  - post-call hard accounting (`reportUsage(tokens)`)
+  - dev warning when `withKey` finishes without `reportUsage`.
+- `nuke()` reset flow to clear encrypted key and session state.
+
+## Why Use This
+
+Most BYOK apps choose between two bad defaults:
+
+- plaintext key entry in the browser (trust-killing UX), or
+- rolling custom client-side crypto where implementation mistakes are common.
+
+`byok-vault` is useful when you want browser-native key handling with opinionated defaults:
+
+- encrypted-at-rest storage with per-key random salt and AES-GCM,
+- scoped key access (`withKey`) instead of wide key plumbing through app code,
+- built-in token budget circuit breaker (`requestedTokens` + `reportUsage`).
+
+Use this if your threat model is client-side BYOK with passive exposure concerns.  
+Do not use this as an active-XSS defense; use a server-side proxy for that.
+
+## Install
+
+```bash
+npm install byok-vault
+```
+
+## Quick Start
+
+```ts
+import { BYOKVault } from "byok-vault";
+
+const vault = new BYOKVault({
+  maxTokens: 30_000,
+  minPassphraseLength: 8
+});
+
+await vault.setKey(userApiKey, userPassphrase);
+await vault.unlock(userPassphrase);
+
+await vault.withKey(
+  async (key) => {
+    const response = await fetch("https://api.example.com/llm", {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${key}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ prompt: "hello" })
+    }).then((r) => r.json());
+
+    const used = response.usage.total_tokens;
+    vault.reportUsage(used); // hard usage accounting
+  },
+  {
+    requestedTokens: 1200 // optional soft pre-flight estimate
+  }
+);
+```
+
+## Circuit Breaker Notes
+
+- `requestedTokens` check is a soft guardrail based on your estimate.
+- `reportUsage(tokens)` is the hard truth.
+- When limit is exceeded, the **next** request is blocked with a hard error.
+- In dev mode, vault warns if `withKey` returns successfully without `reportUsage`.
+
+## Provider Usage Parsing Snippets
+
+OpenAI-style:
+
+```ts
+const tokens = response.usage?.total_tokens ?? 0;
+vault.reportUsage(tokens);
+```
+
+Anthropic-style:
+
+```ts
+const input = response.usage?.input_tokens ?? 0;
+const output = response.usage?.output_tokens ?? 0;
+vault.reportUsage(input + output);
+```
+
+## API
+
+```ts
+new BYOKVault(options?)
+```
+
+Options:
+
+- `namespace?: string` storage key prefix (default `byok-vault`)
+- `minPassphraseLength?: number` default `8`
+- `pbkdf2Iterations?: number` default `200000`
+- `maxTokens?: number` enables circuit breaker
+- `devMode?: boolean` defaults to `NODE_ENV !== "production"` when available
+- `localStorage?: Storage` / `sessionStorage?: Storage` for testing/custom storage
+- `logger?: { warn(message: string): void }` custom warning sink
+
+Methods:
+
+- `setKey(apiKey, passphrase): Promise<void>`
+- `unlock(passphrase): Promise<void>`
+- `withKey(callback, { requestedTokens?, passphrase? }): Promise<T>`
+- `reportUsage(tokens): void`
+- `getUsage(): number`
+- `getRemainingTokens(): number`
+- `getMaxTokens(): number | null`
+- `hasStoredKey(): boolean`
+- `isLocked(): boolean`
+- `getEncryptedBlob(): EncryptedKeyBlob | null`
+- `lock(): void`
+- `nuke(): void`
+
+## Threat Model and Limitations
+
+- JavaScript cannot force immediate memory zeroization of strings; decrypted keys can remain in heap memory until GC.
+- Passphrase quality matters. A short PIN (for example 4 digits) is brute-forceable even with high PBKDF2 iteration counts.
+- PBKDF2 iteration count has a hard floor at `200000`; lower values throw at construction time.
+- This package intentionally has zero runtime dependencies, but still has normal dev dependencies for build/test tooling.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+npm run pack:check
+npm run demo
+```
+
+## Sample Project (Gemini)
+
+See `examples/local-first-byok-sample/README.md` for a separate sample app that uses this package with Gemini API calls.
+
+## Human + LLM Docs
+
+- Human integration guide: `docs/HUMANS.md`
+- LLM reference: `docs/LLMS.md`
+- LLM index file: `llms.txt`

package/dist/circuit-breaker.d.ts

@@ -0,0 +1,20 @@
+interface CircuitBreakerOptions {
+    maxTokens: number;
+    storage: Storage;
+    storageKey: string;
+}
+export declare class CircuitBreaker {
+    private usage;
+    private readonly maxTokens;
+    private readonly storage;
+    private readonly storageKey;
+    constructor(options: CircuitBreakerOptions);
+    assertCanProceed(requestedTokens?: number): void;
+    reportUsage(tokens: number): void;
+    getUsage(): number;
+    getMaxTokens(): number;
+    getRemainingTokens(): number;
+    reset(): void;
+}
+export {};
+//# sourceMappingURL=circuit-breaker.d.ts.map

package/dist/circuit-breaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.d.ts","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"AAEA,UAAU,qBAAqB;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAUD,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,OAAO,EAAE,qBAAqB;IAU1C,gBAAgB,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI;IAqBhD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQjC,QAAQ,IAAI,MAAM;IAIlB,YAAY,IAAI,MAAM;IAItB,kBAAkB,IAAI,MAAM;IAI5B,KAAK,IAAI,IAAI;CAId"}

package/dist/circuit-breaker.js

@@ -0,0 +1,58 @@
+import { CircuitBreakerLimitError, InvalidUsageReportError } from "./errors.js";
+function parseUsage(raw) {
+    if (!raw) {
+        return 0;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+}
+export class CircuitBreaker {
+    usage;
+    maxTokens;
+    storage;
+    storageKey;
+    constructor(options) {
+        if (!Number.isFinite(options.maxTokens) || options.maxTokens <= 0) {
+            throw new Error("maxTokens must be a finite number greater than zero.");
+        }
+        this.maxTokens = Math.floor(options.maxTokens);
+        this.storage = options.storage;
+        this.storageKey = options.storageKey;
+        this.usage = parseUsage(this.storage.getItem(this.storageKey));
+    }
+    assertCanProceed(requestedTokens) {
+        if (this.usage >= this.maxTokens) {
+            throw new CircuitBreakerLimitError(`Token limit reached (${this.usage}/${this.maxTokens}). Reset or nuke before sending another request.`);
+        }
+        if (requestedTokens === undefined) {
+            return;
+        }
+        if (!Number.isFinite(requestedTokens) || requestedTokens < 0) {
+            throw new InvalidUsageReportError();
+        }
+        if (this.usage + Math.floor(requestedTokens) > this.maxTokens) {
+            throw new CircuitBreakerLimitError(`Pre-flight estimate would exceed token limit (${this.usage} + ${Math.floor(requestedTokens)} > ${this.maxTokens}).`);
+        }
+    }
+    reportUsage(tokens) {
+        if (!Number.isFinite(tokens) || tokens < 0) {
+            throw new InvalidUsageReportError();
+        }
+        this.usage += Math.floor(tokens);
+        this.storage.setItem(this.storageKey, String(this.usage));
+    }
+    getUsage() {
+        return this.usage;
+    }
+    getMaxTokens() {
+        return this.maxTokens;
+    }
+    getRemainingTokens() {
+        return Math.max(this.maxTokens - this.usage, 0);
+    }
+    reset() {
+        this.usage = 0;
+        this.storage.removeItem(this.storageKey);
+    }
+}
+//# sourceMappingURL=circuit-breaker.js.map

package/dist/circuit-breaker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuit-breaker.js","sourceRoot":"","sources":["../src/circuit-breaker.ts"],"names":[],"mappings":"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"}

package/dist/crypto.d.ts

@@ -0,0 +1,19 @@
+export declare const DEFAULT_PBKDF2_ITERATIONS = 200000;
+export interface EncryptedKeyBlob {
+    version: 1;
+    iterations: number;
+    salt: string;
+    iv: string;
+    ciphertext: string;
+    createdAt: string;
+}
+interface EncryptOptions {
+    iterations?: number;
+    saltBytes?: number;
+}
+export declare function deriveKeyBits(passphrase: string, salt: Uint8Array, iterations?: number): Promise<Uint8Array>;
+export declare function decryptWithKeyBits(blob: EncryptedKeyBlob, keyBits: Uint8Array): Promise<string>;
+export declare function encryptKey(key: string, passphrase: string, options?: EncryptOptions): Promise<EncryptedKeyBlob>;
+export declare function decryptKey(blob: EncryptedKeyBlob, passphrase: string): Promise<string>;
+export {};
+//# sourceMappingURL=crypto.d.ts.map

package/dist/crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.d.ts","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAKjD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,CAAC,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,cAAc;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAoBD,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,UAAU,EAChB,UAAU,SAA4B,GACrC,OAAO,CAAC,UAAU,CAAC,CAoBrB;AA+BD,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,UAAU,GAClB,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED,wBAAsB,UAAU,CAC9B,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAa3B;AAED,wBAAsB,UAAU,CAC9B,IAAI,EAAE,gBAAgB,EACtB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/dist/crypto.js

@@ -0,0 +1,82 @@
+import { base64ToBytes, bytesToBase64, bytesToUtf8, utf8ToBytes } from "./encoding.js";
+import { WrongPassphraseError } from "./errors.js";
+export const DEFAULT_PBKDF2_ITERATIONS = 200_000;
+const DEFAULT_SALT_BYTES = 16;
+const IV_BYTES = 12;
+function assertWebCrypto() {
+    if (!globalThis.crypto?.subtle) {
+        throw new Error("Web Crypto API is not available in this environment.");
+    }
+    return globalThis.crypto;
+}
+function getRandomBytes(size) {
+    const cryptoProvider = assertWebCrypto();
+    const random = new Uint8Array(size);
+    cryptoProvider.getRandomValues(random);
+    return random;
+}
+function asBufferSource(bytes) {
+    return bytes;
+}
+export async function deriveKeyBits(passphrase, salt, iterations = DEFAULT_PBKDF2_ITERATIONS) {
+    const cryptoProvider = assertWebCrypto();
+    const passphraseKey = await cryptoProvider.subtle.importKey("raw", asBufferSource(utf8ToBytes(passphrase)), "PBKDF2", false, ["deriveBits"]);
+    const keyBits = await cryptoProvider.subtle.deriveBits({
+        name: "PBKDF2",
+        hash: "SHA-256",
+        salt: asBufferSource(salt),
+        iterations
+    }, passphraseKey, 256);
+    return new Uint8Array(keyBits);
+}
+async function importAesGcmKey(keyBits) {
+    const cryptoProvider = assertWebCrypto();
+    return cryptoProvider.subtle.importKey("raw", asBufferSource(keyBits), { name: "AES-GCM" }, false, ["encrypt", "decrypt"]);
+}
+async function encryptWithKeyBits(keyBits, plaintext) {
+    const cryptoProvider = assertWebCrypto();
+    const iv = getRandomBytes(IV_BYTES);
+    const key = await importAesGcmKey(keyBits);
+    const ciphertext = await cryptoProvider.subtle.encrypt({
+        name: "AES-GCM",
+        iv: asBufferSource(iv)
+    }, key, asBufferSource(utf8ToBytes(plaintext)));
+    return { iv, ciphertext: new Uint8Array(ciphertext) };
+}
+export async function decryptWithKeyBits(blob, keyBits) {
+    const cryptoProvider = assertWebCrypto();
+    const key = await importAesGcmKey(keyBits);
+    try {
+        const plaintext = await cryptoProvider.subtle.decrypt({
+            name: "AES-GCM",
+            iv: asBufferSource(base64ToBytes(blob.iv))
+        }, key, asBufferSource(base64ToBytes(blob.ciphertext)));
+        return bytesToUtf8(new Uint8Array(plaintext));
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === "OperationError") {
+            throw new WrongPassphraseError();
+        }
+        throw error;
+    }
+}
+export async function encryptKey(key, passphrase, options = {}) {
+    const salt = getRandomBytes(options.saltBytes ?? DEFAULT_SALT_BYTES);
+    const iterations = options.iterations ?? DEFAULT_PBKDF2_ITERATIONS;
+    const keyBits = await deriveKeyBits(passphrase, salt, iterations);
+    const encrypted = await encryptWithKeyBits(keyBits, key);
+    return {
+        version: 1,
+        iterations,
+        salt: bytesToBase64(salt),
+        iv: bytesToBase64(encrypted.iv),
+        ciphertext: bytesToBase64(encrypted.ciphertext),
+        createdAt: new Date().toISOString()
+    };
+}
+export async function decryptKey(blob, passphrase) {
+    const salt = base64ToBytes(blob.salt);
+    const keyBits = await deriveKeyBits(passphrase, salt, blob.iterations);
+    return decryptWithKeyBits(blob, keyBits);
+}
+//# sourceMappingURL=crypto.js.map

package/dist/crypto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"crypto.js","sourceRoot":"","sources":["../src/crypto.ts"],"names":[],"mappings":"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"}

package/dist/encoding.d.ts

@@ -0,0 +1,5 @@
+export declare function utf8ToBytes(value: string): Uint8Array;
+export declare function bytesToUtf8(value: Uint8Array): string;
+export declare function bytesToBase64(bytes: Uint8Array): string;
+export declare function base64ToBytes(value: string): Uint8Array;
+//# sourceMappingURL=encoding.d.ts.map

package/dist/encoding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"AAGA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAErD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAErD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAQvD;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAOvD"}

package/dist/encoding.js

@@ -0,0 +1,26 @@
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+export function utf8ToBytes(value) {
+    return encoder.encode(value);
+}
+export function bytesToUtf8(value) {
+    return decoder.decode(value);
+}
+export function bytesToBase64(bytes) {
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let index = 0; index < bytes.length; index += chunkSize) {
+        const chunk = bytes.subarray(index, index + chunkSize);
+        binary += String.fromCharCode(...chunk);
+    }
+    return btoa(binary);
+}
+export function base64ToBytes(value) {
+    const binary = atob(value);
+    const output = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        output[index] = binary.charCodeAt(index);
+    }
+    return output;
+}
+//# sourceMappingURL=encoding.js.map

package/dist/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../src/encoding.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAClC,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,OAAO,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,SAAS,GAAG,MAAM,CAAC;IACzB,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,IAAI,SAAS,EAAE,CAAC;QAC7D,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,CAAC,CAAC;QACvD,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC7C,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACtD,MAAM,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,29 @@
+export declare class BYOKVaultError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class PassphrasePolicyError extends BYOKVaultError {
+    constructor(minLength: number);
+}
+export declare class PBKDF2PolicyError extends BYOKVaultError {
+    constructor(minIterations: number);
+}
+export declare class KeyNotFoundError extends BYOKVaultError {
+    constructor();
+}
+export declare class VaultLockedError extends BYOKVaultError {
+    constructor();
+}
+export declare class WrongPassphraseError extends BYOKVaultError {
+    constructor();
+}
+export declare class InvalidUsageReportError extends BYOKVaultError {
+    constructor();
+}
+export declare class CircuitBreakerLimitError extends BYOKVaultError {
+    constructor(message: string);
+}
+export declare class CircuitBreakerDisabledError extends BYOKVaultError {
+    constructor();
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAED,qBAAa,qBAAsB,SAAQ,cAAc;gBAC3C,SAAS,EAAE,MAAM;CAM9B;AAED,qBAAa,iBAAkB,SAAQ,cAAc;gBACvC,aAAa,EAAE,MAAM;CAMlC;AAED,qBAAa,gBAAiB,SAAQ,cAAc;;CAInD;AAED,qBAAa,gBAAiB,SAAQ,cAAc;;CAOnD;AAED,qBAAa,oBAAqB,SAAQ,cAAc;;CAOvD;AAED,qBAAa,uBAAwB,SAAQ,cAAc;;CAO1D;AAED,qBAAa,wBAAyB,SAAQ,cAAc;gBAC9C,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,2BAA4B,SAAQ,cAAc;;CAO9D"}

package/dist/errors.js

@@ -0,0 +1,49 @@
+export class BYOKVaultError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = this.constructor.name;
+    }
+}
+export class PassphrasePolicyError extends BYOKVaultError {
+    constructor(minLength) {
+        super("PASSPHRASE_POLICY", `Passphrase must be at least ${minLength} characters.`);
+    }
+}
+export class PBKDF2PolicyError extends BYOKVaultError {
+    constructor(minIterations) {
+        super("PBKDF2_POLICY", `pbkdf2Iterations must be a finite integer greater than or equal to ${minIterations}.`);
+    }
+}
+export class KeyNotFoundError extends BYOKVaultError {
+    constructor() {
+        super("KEY_NOT_FOUND", "No encrypted API key is stored in the vault.");
+    }
+}
+export class VaultLockedError extends BYOKVaultError {
+    constructor() {
+        super("VAULT_LOCKED", "Vault is locked. Call unlock(passphrase) or pass a passphrase to withKey.");
+    }
+}
+export class WrongPassphraseError extends BYOKVaultError {
+    constructor() {
+        super("WRONG_PASSPHRASE", "Could not decrypt key. The passphrase appears to be incorrect.");
+    }
+}
+export class InvalidUsageReportError extends BYOKVaultError {
+    constructor() {
+        super("INVALID_USAGE_REPORT", "Token usage must be a finite number greater than or equal to zero.");
+    }
+}
+export class CircuitBreakerLimitError extends BYOKVaultError {
+    constructor(message) {
+        super("CIRCUIT_BREAKER_LIMIT", message);
+    }
+}
+export class CircuitBreakerDisabledError extends BYOKVaultError {
+    constructor() {
+        super("CIRCUIT_BREAKER_DISABLED", "Circuit breaker is disabled because maxTokens was not configured.");
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe;QACvC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,cAAc;IACvD,YAAY,SAAiB;QAC3B,KAAK,CACH,mBAAmB,EACnB,+BAA+B,SAAS,cAAc,CACvD,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IACnD,YAAY,aAAqB;QAC/B,KAAK,CACH,eAAe,EACf,sEAAsE,aAAa,GAAG,CACvF,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,cAAc;IAClD;QACE,KAAK,CAAC,eAAe,EAAE,8CAA8C,CAAC,CAAC;IACzE,CAAC;CACF;AAED,MAAM,OAAO,gBAAiB,SAAQ,cAAc;IAClD;QACE,KAAK,CACH,cAAc,EACd,2EAA2E,CAC5E,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,cAAc;IACtD;QACE,KAAK,CACH,kBAAkB,EAClB,gEAAgE,CACjE,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,cAAc;IACzD;QACE,KAAK,CACH,sBAAsB,EACtB,oEAAoE,CACrE,CAAC;IACJ,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,cAAc;IAC1D,YAAY,OAAe;QACzB,KAAK,CAAC,uBAAuB,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,OAAO,2BAA4B,SAAQ,cAAc;IAC7D;QACE,KAAK,CACH,0BAA0B,EAC1B,mEAAmE,CACpE,CAAC;IACJ,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { DEFAULT_PBKDF2_ITERATIONS, decryptKey, decryptWithKeyBits, deriveKeyBits, encryptKey } from "./crypto.js";
+export { CircuitBreaker } from "./circuit-breaker.js";
+export { BYOKVault } from "./vault.js";
+export { BYOKVaultError, CircuitBreakerDisabledError, CircuitBreakerLimitError, InvalidUsageReportError, KeyNotFoundError, PBKDF2PolicyError, PassphrasePolicyError, VaultLockedError, WrongPassphraseError } from "./errors.js";
+export type { EncryptedKeyBlob } from "./crypto.js";
+export type { BYOKVaultOptions, WithKeyOptions } from "./vault.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EACL,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { DEFAULT_PBKDF2_ITERATIONS, decryptKey, decryptWithKeyBits, deriveKeyBits, encryptKey } from "./crypto.js";
+export { CircuitBreaker } from "./circuit-breaker.js";
+export { BYOKVault } from "./vault.js";
+export { BYOKVaultError, CircuitBreakerDisabledError, CircuitBreakerLimitError, InvalidUsageReportError, KeyNotFoundError, PBKDF2PolicyError, PassphrasePolicyError, VaultLockedError, WrongPassphraseError } from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,yBAAyB,EACzB,UAAU,EACV,kBAAkB,EAClB,aAAa,EACb,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EACL,cAAc,EACd,2BAA2B,EAC3B,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,aAAa,CAAC"}

package/dist/storage.d.ts

@@ -0,0 +1,29 @@
+import type { EncryptedKeyBlob } from "./crypto.js";
+export interface StorageKeys {
+    encryptedKey: string;
+    sessionKey: string;
+    tokenUsage: string;
+}
+export declare function getStorageKeys(namespace: string): StorageKeys;
+export declare function resolveStorage(kind: "localStorage" | "sessionStorage", fallback?: Storage): Storage;
+export declare class EncryptedKeyStorage {
+    private readonly storage;
+    private readonly key;
+    constructor(storage: Storage, key: string);
+    get(): EncryptedKeyBlob | null;
+    set(blob: EncryptedKeyBlob): void;
+    clear(): void;
+}
+export declare class SessionKeyCache {
+    private readonly storage;
+    private readonly key;
+    constructor(storage: Storage, key: string);
+    load(salt: string, iterations: number): Uint8Array | null;
+    save(payload: {
+        salt: string;
+        iterations: number;
+        keyBits: Uint8Array;
+    }): void;
+    clear(): void;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAQpD,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,WAAW,CAM7D;AAiBD,wBAAgB,cAAc,CAAC,IAAI,EAAE,cAAc,GAAG,gBAAgB,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO,CASnG;AAED,qBAAa,mBAAmB;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAAW,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAtC,OAAO,EAAE,OAAO,EAAmB,GAAG,EAAE,MAAM;IAE3E,GAAG,IAAI,gBAAgB,GAAG,IAAI;IAa9B,GAAG,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI;IAIjC,KAAK,IAAI,IAAI;CAGd;AAED,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,OAAO;IAAW,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAtC,OAAO,EAAE,OAAO,EAAmB,GAAG,EAAE,MAAM;IAE3E,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAoBzD,IAAI,CAAC,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI;IAS9E,KAAK,IAAI,IAAI;CAGd"}

package/dist/storage.js

@@ -0,0 +1,95 @@
+import { base64ToBytes, bytesToBase64 } from "./encoding.js";
+export function getStorageKeys(namespace) {
+    return {
+        encryptedKey: `${namespace}:encrypted-key`,
+        sessionKey: `${namespace}:derived-key`,
+        tokenUsage: `${namespace}:token-usage`
+    };
+}
+function isEncryptedKeyBlob(input) {
+    if (!input || typeof input !== "object") {
+        return false;
+    }
+    const blob = input;
+    return (blob.version === 1 &&
+        typeof blob.iterations === "number" &&
+        typeof blob.salt === "string" &&
+        typeof blob.iv === "string" &&
+        typeof blob.ciphertext === "string" &&
+        typeof blob.createdAt === "string");
+}
+export function resolveStorage(kind, fallback) {
+    if (fallback) {
+        return fallback;
+    }
+    const candidate = globalThis[kind];
+    if (!candidate) {
+        throw new Error(`${kind} is not available. Provide it through constructor options.`);
+    }
+    return candidate;
+}
+export class EncryptedKeyStorage {
+    storage;
+    key;
+    constructor(storage, key) {
+        this.storage = storage;
+        this.key = key;
+    }
+    get() {
+        const raw = this.storage.getItem(this.key);
+        if (!raw) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return isEncryptedKeyBlob(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    set(blob) {
+        this.storage.setItem(this.key, JSON.stringify(blob));
+    }
+    clear() {
+        this.storage.removeItem(this.key);
+    }
+}
+export class SessionKeyCache {
+    storage;
+    key;
+    constructor(storage, key) {
+        this.storage = storage;
+        this.key = key;
+    }
+    load(salt, iterations) {
+        const raw = this.storage.getItem(this.key);
+        if (!raw) {
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed.salt !== salt ||
+                parsed.iterations !== iterations ||
+                typeof parsed.keyBits !== "string") {
+                return null;
+            }
+            return base64ToBytes(parsed.keyBits);
+        }
+        catch {
+            return null;
+        }
+    }
+    save(payload) {
+        const record = {
+            salt: payload.salt,
+            iterations: payload.iterations,
+            keyBits: bytesToBase64(payload.keyBits)
+        };
+        this.storage.setItem(this.key, JSON.stringify(record));
+    }
+    clear() {
+        this.storage.removeItem(this.key);
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/vault.d.ts

@@ -0,0 +1,43 @@
+import { type EncryptedKeyBlob } from "./crypto.js";
+export interface WithKeyOptions {
+    requestedTokens?: number;
+    passphrase?: string;
+}
+export interface BYOKVaultOptions {
+    namespace?: string;
+    minPassphraseLength?: number;
+    pbkdf2Iterations?: number;
+    maxTokens?: number;
+    devMode?: boolean;
+    localStorage?: Storage;
+    sessionStorage?: Storage;
+    logger?: Pick<Console, "warn">;
+}
+export declare class BYOKVault {
+    private readonly keyStorage;
+    private readonly sessionCache;
+    private readonly minPassphraseLength;
+    private readonly pbkdf2Iterations;
+    private readonly breaker?;
+    private readonly devMode;
+    private readonly logger;
+    private readonly scopes;
+    constructor(options?: BYOKVaultOptions);
+    setKey(apiKey: string, passphrase: string): Promise<void>;
+    unlock(passphrase: string): Promise<void>;
+    withKey<T>(callback: (decryptedKey: string) => Promise<T> | T, options?: WithKeyOptions): Promise<T>;
+    reportUsage(tokens: number): void;
+    getUsage(): number;
+    getRemainingTokens(): number;
+    getMaxTokens(): number | null;
+    hasStoredKey(): boolean;
+    isLocked(): boolean;
+    getEncryptedBlob(): EncryptedKeyBlob | null;
+    lock(): void;
+    nuke(): void;
+    private assertPassphrase;
+    private requireStoredBlob;
+    private resolveDecryptedKey;
+    private decryptOrThrowWrongPassphrase;
+}
+//# sourceMappingURL=vault.d.ts.map

package/dist/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,gBAAgB,EACtB,MAAM,aAAa,CAAC;AAuBrB,MAAM,WAAW,cAAc;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;CAChC;AAUD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAsB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkB;IAC/C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAiB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAE/B,OAAO,GAAE,gBAAqB;IAsCpC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0BzD,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAazC,OAAO,CAAC,CAAC,EACb,QAAQ,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAClD,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC;IAuBb,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAWjC,QAAQ,IAAI,MAAM;IAIlB,kBAAkB,IAAI,MAAM;IAI5B,YAAY,IAAI,MAAM,GAAG,IAAI;IAI7B,YAAY,IAAI,OAAO;IAIvB,QAAQ,IAAI,OAAO;IAQnB,gBAAgB,IAAI,gBAAgB,GAAG,IAAI;IAI3C,IAAI,IAAI,IAAI;IAKZ,IAAI,IAAI,IAAI;IAOZ,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,iBAAiB;YAQX,mBAAmB;YAkCnB,6BAA6B;CAa5C"}

package/dist/vault.js

@@ -0,0 +1,198 @@
+import { CircuitBreaker } from "./circuit-breaker.js";
+import { base64ToBytes } from "./encoding.js";
+import { DEFAULT_PBKDF2_ITERATIONS, decryptWithKeyBits, deriveKeyBits, encryptKey } from "./crypto.js";
+import { CircuitBreakerDisabledError, KeyNotFoundError, PBKDF2PolicyError, PassphrasePolicyError, VaultLockedError, WrongPassphraseError } from "./errors.js";
+import { EncryptedKeyStorage, SessionKeyCache, getStorageKeys, resolveStorage } from "./storage.js";
+const DEFAULT_NAMESPACE = "byok-vault";
+const DEFAULT_MIN_PASSPHRASE_LENGTH = 8;
+function inferDevMode() {
+    const processCandidate = globalThis.process;
+    if (!processCandidate?.env?.NODE_ENV) {
+        return true;
+    }
+    return processCandidate.env.NODE_ENV !== "production";
+}
+export class BYOKVault {
+    keyStorage;
+    sessionCache;
+    minPassphraseLength;
+    pbkdf2Iterations;
+    breaker;
+    devMode;
+    logger;
+    scopes = [];
+    constructor(options = {}) {
+        const namespace = options.namespace ?? DEFAULT_NAMESPACE;
+        const localStorage = resolveStorage("localStorage", options.localStorage);
+        const sessionStorage = resolveStorage("sessionStorage", options.sessionStorage);
+        const keys = getStorageKeys(namespace);
+        this.keyStorage = new EncryptedKeyStorage(localStorage, keys.encryptedKey);
+        this.sessionCache = new SessionKeyCache(sessionStorage, keys.sessionKey);
+        this.minPassphraseLength = options.minPassphraseLength ?? DEFAULT_MIN_PASSPHRASE_LENGTH;
+        if (!Number.isFinite(this.minPassphraseLength) ||
+            !Number.isInteger(this.minPassphraseLength) ||
+            this.minPassphraseLength < 1) {
+            throw new Error("minPassphraseLength must be an integer greater than or equal to 1.");
+        }
+        this.pbkdf2Iterations = options.pbkdf2Iterations ?? DEFAULT_PBKDF2_ITERATIONS;
+        if (!Number.isFinite(this.pbkdf2Iterations) ||
+            !Number.isInteger(this.pbkdf2Iterations) ||
+            this.pbkdf2Iterations < DEFAULT_PBKDF2_ITERATIONS) {
+            throw new PBKDF2PolicyError(DEFAULT_PBKDF2_ITERATIONS);
+        }
+        this.devMode = options.devMode ?? inferDevMode();
+        this.logger = options.logger ?? console;
+        if (options.maxTokens !== undefined) {
+            this.breaker = new CircuitBreaker({
+                maxTokens: options.maxTokens,
+                storage: sessionStorage,
+                storageKey: keys.tokenUsage
+            });
+        }
+    }
+    async setKey(apiKey, passphrase) {
+        this.assertPassphrase(passphrase);
+        if (!apiKey) {
+            throw new Error("apiKey cannot be empty.");
+        }
+        const blob = await encryptKey(apiKey, passphrase, {
+            iterations: this.pbkdf2Iterations
+        });
+        this.keyStorage.set(blob);
+        const keyBits = await deriveKeyBits(passphrase, base64ToBytes(blob.salt), blob.iterations);
+        // sessionStorage caching is only for passphrase UX; it is not an extra security boundary.
+        this.sessionCache.save({
+            salt: blob.salt,
+            iterations: blob.iterations,
+            keyBits
+        });
+        this.breaker?.reset();
+    }
+    async unlock(passphrase) {
+        this.assertPassphrase(passphrase);
+        const blob = this.requireStoredBlob();
+        const salt = base64ToBytes(blob.salt);
+        const keyBits = await deriveKeyBits(passphrase, salt, blob.iterations);
+        await this.decryptOrThrowWrongPassphrase(blob, keyBits);
+        this.sessionCache.save({
+            salt: blob.salt,
+            iterations: blob.iterations,
+            keyBits
+        });
+    }
+    async withKey(callback, options = {}) {
+        this.breaker?.assertCanProceed(options.requestedTokens);
+        const scope = { reported: false };
+        let callbackCompleted = false;
+        this.scopes.push(scope);
+        try {
+            // If malicious script runs in-origin (XSS), it can still read this value in-flight.
+            // This API narrows exposure windows; it does not eliminate active injection risk.
+            const decryptedKey = await this.resolveDecryptedKey(options.passphrase);
+            const result = await callback(decryptedKey);
+            callbackCompleted = true;
+            return result;
+        }
+        finally {
+            this.scopes.pop();
+            if (this.breaker && this.devMode && callbackCompleted && !scope.reported) {
+                this.logger.warn("[byok-vault] withKey completed without reportUsage(tokens). Circuit breaker accounting is incomplete.");
+            }
+        }
+    }
+    reportUsage(tokens) {
+        if (!this.breaker) {
+            throw new CircuitBreakerDisabledError();
+        }
+        this.breaker.reportUsage(tokens);
+        const activeScope = this.scopes.at(-1);
+        if (activeScope) {
+            activeScope.reported = true;
+        }
+    }
+    getUsage() {
+        return this.breaker?.getUsage() ?? 0;
+    }
+    getRemainingTokens() {
+        return this.breaker?.getRemainingTokens() ?? Number.POSITIVE_INFINITY;
+    }
+    getMaxTokens() {
+        return this.breaker ? this.breaker.getMaxTokens() : null;
+    }
+    hasStoredKey() {
+        return this.keyStorage.get() !== null;
+    }
+    isLocked() {
+        const blob = this.keyStorage.get();
+        if (!blob) {
+            return true;
+        }
+        return this.sessionCache.load(blob.salt, blob.iterations) === null;
+    }
+    getEncryptedBlob() {
+        return this.keyStorage.get();
+    }
+    lock() {
+        this.sessionCache.clear();
+        this.scopes.length = 0;
+    }
+    nuke() {
+        this.keyStorage.clear();
+        this.sessionCache.clear();
+        this.breaker?.reset();
+        this.scopes.length = 0;
+    }
+    assertPassphrase(passphrase) {
+        if (passphrase.length < this.minPassphraseLength) {
+            throw new PassphrasePolicyError(this.minPassphraseLength);
+        }
+    }
+    requireStoredBlob() {
+        const blob = this.keyStorage.get();
+        if (!blob) {
+            throw new KeyNotFoundError();
+        }
+        return blob;
+    }
+    async resolveDecryptedKey(passphrase) {
+        const blob = this.requireStoredBlob();
+        const cachedBits = this.sessionCache.load(blob.salt, blob.iterations);
+        if (cachedBits) {
+            try {
+                return await decryptWithKeyBits(blob, cachedBits);
+            }
+            catch (error) {
+                if (error instanceof WrongPassphraseError) {
+                    this.sessionCache.clear();
+                }
+                else {
+                    throw error;
+                }
+            }
+        }
+        if (!passphrase) {
+            throw new VaultLockedError();
+        }
+        this.assertPassphrase(passphrase);
+        const keyBits = await deriveKeyBits(passphrase, base64ToBytes(blob.salt), blob.iterations);
+        const decryptedKey = await this.decryptOrThrowWrongPassphrase(blob, keyBits);
+        this.sessionCache.save({
+            salt: blob.salt,
+            iterations: blob.iterations,
+            keyBits
+        });
+        return decryptedKey;
+    }
+    async decryptOrThrowWrongPassphrase(blob, keyBits) {
+        try {
+            return await decryptWithKeyBits(blob, keyBits);
+        }
+        catch (error) {
+            if (error instanceof WrongPassphraseError) {
+                throw error;
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=vault.js.map

package/dist/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../src/vault.ts"],"names":[],"mappings":"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"}

package/docs/HUMANS.md

@@ -0,0 +1,80 @@
+# Human Docs: byok-vault
+
+This guide is for developers integrating `byok-vault` into real apps.
+
+## What This Library Solves
+
+- Encrypts user API keys in-browser before writing to `localStorage`.
+- Lets you scope decrypted key access to one callback with `withKey(...)`.
+- Adds optional per-session token budget tracking via a circuit breaker.
+
+It is not a backend replacement for high-security threat models with active XSS risk.
+
+## Quick Integration Checklist
+
+1. Ask user for API key and passphrase.
+2. Save once with `await vault.setKey(apiKey, passphrase)`.
+3. For each request, call `vault.withKey(...)`.
+4. If breaker enabled, call `vault.reportUsage(tokens)` after each successful provider response.
+5. Add reset UI that calls `vault.nuke()`.
+
+## Minimal Usage Pattern
+
+```ts
+import { BYOKVault } from "byok-vault";
+
+const vault = new BYOKVault({
+  maxTokens: 30_000
+});
+
+await vault.setKey(userApiKey, userPassphrase);
+
+await vault.withKey(
+  async (key) => {
+    const response = await fetch("/your-provider-call", {
+      method: "POST",
+      headers: { Authorization: `Bearer ${key}` }
+    }).then((r) => r.json());
+
+    const used = response.usage?.total_tokens ?? 0;
+    vault.reportUsage(used);
+  },
+  { requestedTokens: 1200 }
+);
+```
+
+## UX Recommendations
+
+- Explain passphrase purpose clearly: protects key at rest in browser storage.
+- Enforce strong passphrase UX (default floor is 8 chars, consider stronger copy and meter).
+- Show current token usage and remaining budget if breaker is enabled.
+- Provide a visible "reset vault" control wired to `nuke()`.
+
+## Security Boundaries (Plain English)
+
+- `sessionStorage` caching is convenience only, not stronger security.
+- If hostile JS executes in your origin, it can still intercept keys in-flight.
+- Decrypted strings can remain in JS memory until garbage collection.
+- This package is not formally audited.
+
+## Common Mistakes
+
+- Enabling `maxTokens` but forgetting `reportUsage(tokens)`.
+- Treating `requestedTokens` pre-flight as exact accounting.
+- Assuming this protects against active XSS.
+- Lowering PBKDF2 iterations below `200000` (constructor throws).
+
+## Error Handling You Should Surface
+
+- `PASSPHRASE_POLICY`: passphrase too short.
+- `WRONG_PASSPHRASE`: user entered incorrect passphrase.
+- `VAULT_LOCKED`: no cached session key and no passphrase provided.
+- `CIRCUIT_BREAKER_LIMIT`: budget exhausted/pre-flight blocked.
+- `KEY_NOT_FOUND`: no stored key yet.
+
+## Production Readiness Checklist
+
+- Add CSP and strict input sanitization in your app to reduce XSS risk.
+- Instrument `reportUsage` code path and alert on missing usage reporting.
+- Use `pack:check` and CI before publishing changes.
+- Document threat model to users in product copy.

package/docs/LLMS.md

@@ -0,0 +1,114 @@
+# LLM Docs: byok-vault
+
+This file is a machine-oriented reference for code assistants and agents.
+
+## Package Identity
+
+- Name: `byok-vault`
+- Runtime deps: none
+- Environment: browser Web Crypto API (`crypto.subtle`), `localStorage`, `sessionStorage`
+- Primary class: `BYOKVault`
+
+## Core Guarantees
+
+- Stored API keys are encrypted at rest using AES-GCM.
+- Per-key salt is random and unique per encryption operation.
+- AES key material is derived via PBKDF2 (SHA-256), default and enforced floor: `200000` iterations.
+- Decrypted key is only provided inside `withKey(callback)`.
+
+## Non-Goals / Limits
+
+- No defense against active XSS in same origin.
+- No hard provider SDK integrations.
+- No authoritative token accounting without `reportUsage(tokens)`.
+
+## Canonical API Contracts
+
+### Constructor
+
+```ts
+new BYOKVault(options?)
+```
+
+Important options:
+
+- `namespace?: string` -> storage key prefix
+- `minPassphraseLength?: number` -> integer >= 1 (default 8)
+- `pbkdf2Iterations?: number` -> integer >= 200000
+- `maxTokens?: number` -> enables circuit breaker if set
+- `devMode?: boolean`
+- `localStorage?: Storage`, `sessionStorage?: Storage`
+- `logger?: { warn(message: string): void }`
+
+### Methods
+
+- `setKey(apiKey, passphrase): Promise<void>`
+- `unlock(passphrase): Promise<void>`
+- `withKey(callback, { requestedTokens?, passphrase? }): Promise<T>`
+- `reportUsage(tokens): void`
+- `getUsage(): number`
+- `getRemainingTokens(): number`
+- `getMaxTokens(): number | null`
+- `hasStoredKey(): boolean`
+- `isLocked(): boolean`
+- `getEncryptedBlob(): EncryptedKeyBlob | null`
+- `lock(): void`
+- `nuke(): void`
+
+## Circuit Breaker Semantics
+
+- `requestedTokens` is pre-flight estimate only.
+- `reportUsage(tokens)` is post-call hard accounting.
+- Breaker blocks the next request when usage already at/over budget.
+- In dev mode, warning is emitted if `withKey` returns successfully without `reportUsage`.
+- If callback throws, missing `reportUsage` warning is not emitted.
+
+## Error Codes
+
+- `PASSPHRASE_POLICY`
+- `PBKDF2_POLICY`
+- `KEY_NOT_FOUND`
+- `VAULT_LOCKED`
+- `WRONG_PASSPHRASE`
+- `INVALID_USAGE_REPORT`
+- `CIRCUIT_BREAKER_LIMIT`
+- `CIRCUIT_BREAKER_DISABLED`
+
+## Correct Usage Pattern (Agent Guidance)
+
+1. Construct `BYOKVault`.
+2. Save key once via `setKey(...)`.
+3. Use `withKey(...)` around each provider call.
+4. Parse provider usage from response and call `reportUsage(tokens)` if breaker enabled.
+5. Use `nuke()` for full reset; use `lock()` for session-only lock.
+
+## Anti-Patterns (Do Not Generate)
+
+- Do not store plaintext API keys in storage.
+- Do not call `withKey` and omit `reportUsage` when `maxTokens` is configured.
+- Do not claim this library mitigates active XSS.
+- Do not set `pbkdf2Iterations < 200000`.
+
+## Provider Usage Parsing Examples
+
+OpenAI style:
+
+```ts
+const tokens = response.usage?.total_tokens ?? 0;
+vault.reportUsage(tokens);
+```
+
+Anthropic style:
+
+```ts
+const tokens =
+  (response.usage?.input_tokens ?? 0) + (response.usage?.output_tokens ?? 0);
+vault.reportUsage(tokens);
+```
+
+Gemini style:
+
+```ts
+const tokens = response.usageMetadata?.totalTokenCount ?? 0;
+vault.reportUsage(tokens);
+```

package/llms.txt

@@ -0,0 +1,25 @@
+# byok-vault
+
+Browser-native BYOK vault for local-first/serverless AI apps.
+
+## Preferred Docs
+
+- README: `README.md`
+- Human integration guide: `docs/HUMANS.md`
+- LLM reference: `docs/LLMS.md`
+- Gemini sample app: `examples/local-first-byok-sample/README.md`
+
+## Stable Facts
+
+- Primary API surface is `BYOKVault`.
+- Encryption at rest: AES-GCM.
+- Key derivation: PBKDF2 SHA-256 with minimum `200000` iterations.
+- Circuit breaker is optional and requires `reportUsage(tokens)` to be meaningful.
+- Library is not a defense against active XSS in same-origin execution context.
+
+## Safe Generation Rules For Agents
+
+- Use `withKey(async (key) => { ... })` for provider calls.
+- If `maxTokens` is set, include `vault.reportUsage(tokens)` after successful responses.
+- Do not generate claims that this package is formally audited.
+- Do not claim it eliminates XSS risk.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "byok-vault",
+  "version": "0.1.0",
+  "description": "Browser-native BYOK vault with encrypted storage and token circuit breaker.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "llms.txt"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "npm run build:lib",
+    "build:lib": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "pack:check": "node ./scripts/check-pack.mjs",
+    "demo": "vite --config demo/vite.config.ts",
+    "demo:build": "vite build --config demo/vite.config.ts"
+  },
+  "keywords": [
+    "byok",
+    "vault",
+    "browser",
+    "aes-gcm",
+    "pbkdf2"
+  ],
+  "author": "Ra <ravicity999@gmail.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.15.19",
+    "jsdom": "^25.0.1",
+    "typescript": "^5.8.3",
+    "vite": "^5.4.19",
+    "vitest": "^2.1.9"
+  }
+}