@fluixi/storage 0.1.0-alpha.0

package/dist/core/types.cjs

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/core/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/core/types.d.ts

@@ -0,0 +1,239 @@
+import type { EncryptionOptions } from '../encryption/types.js';
+/** The value types a typed storage holds, by key. */
+export type StorageSchema = Record<string, unknown>;
+/** The keys of a schema that can name a stored value. */
+export type StorageKey<S> = Extract<keyof S, string>;
+/**
+ * Where data lives and for how long. A lifecycle, not an implementation: `local` survives a
+ * browser restart, `session` the tab, `request` one server request, `memory` the process or
+ * page, `cookie` travels with each request, `persistent` a server-side store.
+ */
+export type StorageScope = 'local' | 'session' | 'request' | 'memory' | 'cookie' | 'persistent';
+/** What an adapter can actually guarantee. Nothing it cannot. */
+export interface StorageCapabilities {
+    /** Reads and writes return at once. */
+    synchronous: boolean;
+    /** Data outlives the page or process that wrote it. */
+    persistent: boolean;
+    /** The adapter reports changes made elsewhere (another tab, another writer). */
+    reactive: boolean;
+    /** Data is shared beyond this execution context (tabs, requests, devices). */
+    crossContext: boolean;
+    /** The adapter expires entries itself. The storage expires them either way. */
+    expiration: boolean;
+    /** Several writes can be applied together or not at all. */
+    transactions: boolean;
+}
+/** A change an adapter observed from outside this storage instance. `key: null` is a clear. */
+export interface AdapterChange {
+    key: string | null;
+    value: string | null;
+}
+/**
+ * A synchronous backend. It stores strings; serialization, namespaces and expiry belong to the
+ * storage around it, so an adapter stays small and every adapter gets them.
+ */
+/** What the storage tells an adapter about a write, for backends that can act on it. */
+export interface AdapterWriteOptions {
+    /** Epoch milliseconds when the entry expires. A cookie adapter makes the cookie last as long. */
+    expiresAt?: number;
+}
+export interface StorageAdapter {
+    readonly name: string;
+    readonly scope: StorageScope;
+    readonly capabilities: StorageCapabilities;
+    get(key: string): string | null;
+    set(key: string, value: string, options?: AdapterWriteOptions): void;
+    remove(key: string): void;
+    has(key: string): boolean;
+    keys(): string[];
+    clear(): void;
+    /** Changes made outside this instance, when the backend can report them. */
+    subscribe?(listener: (change: AdapterChange) => void): () => void;
+}
+/** A stored value and what is known about it. */
+export interface StorageEntry<T> {
+    value: T;
+    /** Epoch milliseconds when it was written; 0 when the value was written without metadata. */
+    createdAt: number;
+    /** Epoch milliseconds after which it reads as absent. */
+    expiresAt?: number;
+    /** The value's schema version, for migrations. */
+    version?: number;
+    /** Present when the value is stored encrypted. */
+    encrypted?: true;
+}
+export interface SetOptions {
+    /** Milliseconds until the entry expires. Checked on every read, so it survives reloads. */
+    ttl?: number;
+    /** The value's schema version. Defaults to the latest migration for the key, when any. */
+    version?: number;
+}
+export type StorageEventType = 'set' | 'remove' | 'clear' | 'expire';
+export interface StorageEvent<S = StorageSchema> {
+    type: StorageEventType;
+    /** The key, without the namespace; null for a clear. */
+    key: StorageKey<S> | null;
+    /** The new value, for `set`. */
+    value?: unknown;
+    /** True when the change came from outside this instance (another tab). */
+    external: boolean;
+}
+export interface StorageSerializer {
+    serialize(value: unknown): string;
+    deserialize<T = unknown>(text: string): T;
+}
+/** Per key, the function that brings a value up to each version. */
+export type StorageMigrations<S> = {
+    [K in StorageKey<S>]?: Record<number, (value: unknown) => unknown>;
+};
+export interface StorageOptions<S extends StorageSchema = StorageSchema> {
+    /** Where values live. Defaults to an in-memory adapter. */
+    adapter?: StorageAdapter;
+    /** Prefix for every key: `app` stores `theme` as `app:theme`. */
+    namespace?: string;
+    /** Defaults to the strict JSON serializer. */
+    serializer?: StorageSerializer;
+    migrations?: StorageMigrations<S>;
+    /** The clock for expiry; for tests. */
+    now?: () => number;
+}
+type Listener<S> = (event: StorageEvent<S>) => void;
+/** A stored value with its key, as `entries` and `search` return it. */
+export interface StoredItem<S extends StorageSchema, K extends StorageKey<S> = StorageKey<S>> {
+    key: K;
+    value: S[K];
+    entry: StorageEntry<S[K]>;
+}
+export interface StorageQuery<S extends StorageSchema> {
+    /** Keys starting with this. */
+    prefix?: string;
+    /** Keys matching a glob (`draft:*`, `user:?`) or a RegExp. */
+    match?: string | RegExp;
+    /** Keep the items this returns true for: by value, key or metadata. */
+    where?: (item: StoredItem<S>) => boolean;
+    /** At most this many, in key order. */
+    limit?: number;
+}
+/** What a storage holds, roughly: for quota decisions, not accounting. */
+export interface StorageUsage {
+    keys: number;
+    /** UTF-16 code units of keys and stored text, times two: what browsers count against quota. */
+    bytes: number;
+}
+/** Plain data for export and import: key to value, with optional metadata. */
+export type StorageSnapshot<S extends StorageSchema = StorageSchema> = {
+    [K in StorageKey<S>]?: StorageEntry<S[K]>;
+};
+/** One typed key/value API, whatever the adapter underneath. */
+export interface TypedStorage<S extends StorageSchema = StorageSchema> {
+    /**
+     * The value, or null when absent or expired. With a schema the type follows the key; without
+     * one, name it: `storage.get<User>('user')`.
+     */
+    get<T = never, K extends StorageKey<S> = StorageKey<S>>(key: K): ([T] extends [never] ? S[K] : T) | null;
+    /** The value with its metadata, or null when absent or expired. */
+    getEntry<T = never, K extends StorageKey<S> = StorageKey<S>>(key: K): StorageEntry<[T] extends [never] ? S[K] : T> | null;
+    set<K extends StorageKey<S>>(key: K, value: S[K], options?: SetOptions): void;
+    remove(key: StorageKey<S>): void;
+    /** True when a value is stored and not expired. */
+    has(key: StorageKey<S>): boolean;
+    /** The keys under this storage's namespace, without it. */
+    keys(): StorageKey<S>[];
+    /** Removes every key under this namespace (everything, without a namespace). */
+    clear(): void;
+    /** Every live item, in key order. Expired ones are removed on the way. */
+    entries(): StoredItem<S>[];
+    /** The live items a query selects, in key order. */
+    search(query: StorageQuery<S>): StoredItem<S>[];
+    /** How many live items there are. */
+    size(): number;
+    /** Removes every expired item now, rather than on its next read. Returns how many. */
+    prune(): number;
+    /** Keys and approximate bytes stored under this namespace. */
+    usage(): StorageUsage;
+    /** Reads, transforms and writes back one value; `fn` receives null when absent. Keeps the expiry. */
+    update<K extends StorageKey<S>>(key: K, fn: (current: S[K] | null) => S[K]): S[K];
+    /** The value, or the factory's result stored under the key when absent. */
+    getOrSet<K extends StorageKey<S>>(key: K, factory: () => S[K], options?: SetOptions): S[K];
+    /** Gives a stored value a new expiry, `ttl` from now. False when absent. */
+    touch(key: StorageKey<S>, ttl: number): boolean;
+    /** Every live item with its metadata, as plain data. */
+    snapshot(): StorageSnapshot<S>;
+    /** Writes items from a snapshot, keeping their metadata; existing keys are kept unless `overwrite`. */
+    restore(snapshot: StorageSnapshot<S>, options?: {
+        overwrite?: boolean;
+    }): number;
+    /** A storage whose keys live under `name` inside this one. */
+    namespace<S2 extends StorageSchema = StorageSchema>(name: string): TypedStorage<S2>;
+    /** Every change; returns the unsubscribe. */
+    subscribe(listener: Listener<S>): () => void;
+    /** Changes to one key; returns the unsubscribe. */
+    subscribe(key: StorageKey<S>, listener: Listener<S>): () => void;
+    readonly capabilities: StorageCapabilities;
+    readonly scope: StorageScope;
+    /** What this storage puts before every key in the adapter: `app:` for namespace `app`, else empty. */
+    readonly keyPrefix: string;
+}
+type MaybePromise<T> = T | Promise<T>;
+/** An adapter whose backend may answer later: IndexedDB, a remote store. Every sync adapter is one. */
+export interface AsyncStorageAdapter {
+    readonly name: string;
+    readonly scope: StorageScope;
+    readonly capabilities: StorageCapabilities;
+    get(key: string): MaybePromise<string | null>;
+    set(key: string, value: string, options?: AdapterWriteOptions): MaybePromise<void>;
+    remove(key: string): MaybePromise<void>;
+    has(key: string): MaybePromise<boolean>;
+    keys(): MaybePromise<string[]>;
+    clear(): MaybePromise<void>;
+    subscribe?(listener: (change: AdapterChange) => void): () => void;
+}
+export interface AsyncSetOptions extends SetOptions {
+    /** Store this value encrypted. Needs `encryption` on the storage. Reads detect it on their own. */
+    encrypt?: boolean;
+}
+export interface AsyncStorageOptions<S extends StorageSchema = StorageSchema> extends Omit<StorageOptions<S>, 'adapter'> {
+    adapter?: StorageAdapter | AsyncStorageAdapter;
+    encryption?: EncryptionOptions;
+}
+/** The storage API with every operation awaited. Encryption lives here. */
+export interface AsyncTypedStorage<S extends StorageSchema = StorageSchema> {
+    get<T = never, K extends StorageKey<S> = StorageKey<S>>(key: K): Promise<([T] extends [never] ? S[K] : T) | null>;
+    getEntry<T = never, K extends StorageKey<S> = StorageKey<S>>(key: K): Promise<StorageEntry<[T] extends [never] ? S[K] : T> | null>;
+    set<K extends StorageKey<S>>(key: K, value: S[K], options?: AsyncSetOptions): Promise<void>;
+    remove(key: StorageKey<S>): Promise<void>;
+    has(key: StorageKey<S>): Promise<boolean>;
+    keys(): Promise<StorageKey<S>[]>;
+    clear(): Promise<void>;
+    /** Every live item, decrypted, in key order. */
+    entries(): Promise<StoredItem<S>[]>;
+    search(query: StorageQuery<S>): Promise<StoredItem<S>[]>;
+    size(): Promise<number>;
+    /** Removes expired items without decrypting anything. */
+    prune(): Promise<number>;
+    usage(): Promise<StorageUsage>;
+    /** Keeps the expiry and the encryption state unless `options.encrypt` says otherwise. */
+    update<K extends StorageKey<S>>(key: K, fn: (current: S[K] | null) => MaybePromise<S[K]>, options?: {
+        encrypt?: boolean;
+    }): Promise<S[K]>;
+    getOrSet<K extends StorageKey<S>>(key: K, factory: () => MaybePromise<S[K]>, options?: AsyncSetOptions): Promise<S[K]>;
+    touch(key: StorageKey<S>, ttl: number): Promise<boolean>;
+    /** Decrypted values, each marked `encrypted` so `restore` encrypts it again. */
+    snapshot(): Promise<StorageSnapshot<S>>;
+    restore(snapshot: StorageSnapshot<S>, options?: {
+        overwrite?: boolean;
+    }): Promise<number>;
+    namespace<S2 extends StorageSchema = StorageSchema>(name: string): AsyncTypedStorage<S2>;
+    /** An external change to an encrypted entry arrives without `value`: decrypting is async. */
+    subscribe(listener: Listener<S>): () => void;
+    subscribe(key: StorageKey<S>, listener: Listener<S>): () => void;
+    readonly capabilities: StorageCapabilities;
+    readonly scope: StorageScope;
+    /** What this storage puts before every key in the adapter: `app:` for namespace `app`, else empty. */
+    readonly keyPrefix: string;
+    /** True when this storage can encrypt: `encryption` was configured. */
+    readonly encryption: boolean;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/core/types.d.ts.map

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

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/encryption/base64.cjs

@@ -0,0 +1,38 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/encryption/base64.ts
+var base64_exports = {};
+__export(base64_exports, {
+  fromBase64: () => fromBase64,
+  toBase64: () => toBase64
+});
+module.exports = __toCommonJS(base64_exports);
+function toBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 32768) binary += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(binary);
+}
+function fromBase64(text) {
+  if (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) throw new TypeError("Not base64.");
+  const binary = atob(text);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}

package/dist/encryption/base64.d.ts

@@ -0,0 +1,4 @@
+export declare function toBase64(bytes: Uint8Array): string;
+/** Throws a TypeError on anything that is not canonical base64. */
+export declare function fromBase64(text: string): Uint8Array;
+//# sourceMappingURL=base64.d.ts.map

package/dist/encryption/base64.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base64.d.ts","sourceRoot":"","sources":["../../src/encryption/base64.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIlD;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAMnD"}

package/dist/encryption/base64.js

@@ -0,0 +1,16 @@
+export function toBase64(bytes) {
+    let binary = '';
+    for (let i = 0; i < bytes.length; i += 0x8000)
+        binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+    return btoa(binary);
+}
+/** Throws a TypeError on anything that is not canonical base64. */
+export function fromBase64(text) {
+    if (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text))
+        throw new TypeError('Not base64.');
+    const binary = atob(text);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}

package/dist/encryption/base64.mjs

@@ -0,0 +1,17 @@
+// src/encryption/base64.ts
+function toBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 32768) binary += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  return btoa(binary);
+}
+function fromBase64(text) {
+  if (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) throw new TypeError("Not base64.");
+  const binary = atob(text);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+export {
+  fromBase64,
+  toBase64
+};

package/dist/encryption/keys.cjs

@@ -0,0 +1,77 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/encryption/keys.ts
+var keys_exports = {};
+__export(keys_exports, {
+  generateEncryptionKey: () => generateEncryptionKey,
+  importEncryptionKey: () => importEncryptionKey,
+  staticKeyProvider: () => staticKeyProvider
+});
+module.exports = __toCommonJS(keys_exports);
+
+// src/core/errors.ts
+var StorageError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.key = options.key;
+    if (options.cause !== void 0) this.cause = options.cause;
+  }
+};
+var StorageEncryptionError = class extends StorageError {
+};
+var StorageEncryptionUnavailableError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-unavailable", message, options);
+  }
+};
+
+// src/encryption/base64.ts
+function fromBase64(text) {
+  if (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) throw new TypeError("Not base64.");
+  const binary = atob(text);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+// src/encryption/keys.ts
+var subtleOf = (crypto) => {
+  const subtle = (crypto ?? globalThis.crypto)?.subtle;
+  if (!subtle) throw new StorageEncryptionUnavailableError("Web Crypto is not available in this runtime.");
+  return subtle;
+};
+async function generateEncryptionKey(options = {}) {
+  return subtleOf(options.crypto).generateKey({ name: "AES-GCM", length: 256 }, options.extractable ?? false, ["encrypt", "decrypt"]);
+}
+async function importEncryptionKey(raw, options = {}) {
+  const bytes = typeof raw === "string" ? fromBase64(raw) : raw;
+  if (bytes.length !== 32) throw new TypeError(`An AES-256 key is 32 bytes, got ${bytes.length}.`);
+  return subtleOf(options.crypto).importKey("raw", bytes, { name: "AES-GCM" }, options.extractable ?? false, ["encrypt", "decrypt"]);
+}
+function staticKeyProvider(key, id) {
+  return {
+    async getKey() {
+      const resolved = await key;
+      return id === void 0 ? resolved : { key: resolved, id };
+    }
+  };
+}

package/dist/encryption/keys.d.ts

@@ -0,0 +1,14 @@
+import type { EncryptionKeyProvider } from './types.js';
+/** A new AES-256-GCM key. Not extractable unless asked, so script cannot read it back. */
+export declare function generateEncryptionKey(options?: {
+    extractable?: boolean;
+    crypto?: Crypto;
+}): Promise<CryptoKey>;
+/** An AES-256-GCM key from 32 raw bytes, or their base64. */
+export declare function importEncryptionKey(raw: Uint8Array | string, options?: {
+    extractable?: boolean;
+    crypto?: Crypto;
+}): Promise<CryptoKey>;
+/** One key for every entry. Give it an id to rotate later: entries keep the id they were written with. */
+export declare function staticKeyProvider(key: CryptoKey | Promise<CryptoKey>, id?: string): EncryptionKeyProvider;
+//# sourceMappingURL=keys.d.ts.map

package/dist/encryption/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/encryption/keys.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAiB,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAQvE,0FAA0F;AAC1F,wBAAsB,qBAAqB,CAAC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAExH;AAED,6DAA6D;AAC7D,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,EAAE,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAIhJ;AAED,0GAA0G;AAC1G,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,qBAAqB,CAOzG"}

package/dist/encryption/keys.js

@@ -0,0 +1,28 @@
+import { StorageEncryptionUnavailableError } from '../core/errors.js';
+import { fromBase64 } from './base64.js';
+const subtleOf = (crypto) => {
+    const subtle = (crypto ?? globalThis.crypto)?.subtle;
+    if (!subtle)
+        throw new StorageEncryptionUnavailableError('Web Crypto is not available in this runtime.');
+    return subtle;
+};
+/** A new AES-256-GCM key. Not extractable unless asked, so script cannot read it back. */
+export async function generateEncryptionKey(options = {}) {
+    return subtleOf(options.crypto).generateKey({ name: 'AES-GCM', length: 256 }, options.extractable ?? false, ['encrypt', 'decrypt']);
+}
+/** An AES-256-GCM key from 32 raw bytes, or their base64. */
+export async function importEncryptionKey(raw, options = {}) {
+    const bytes = typeof raw === 'string' ? fromBase64(raw) : raw;
+    if (bytes.length !== 32)
+        throw new TypeError(`An AES-256 key is 32 bytes, got ${bytes.length}.`);
+    return subtleOf(options.crypto).importKey('raw', bytes, { name: 'AES-GCM' }, options.extractable ?? false, ['encrypt', 'decrypt']);
+}
+/** One key for every entry. Give it an id to rotate later: entries keep the id they were written with. */
+export function staticKeyProvider(key, id) {
+    return {
+        async getKey() {
+            const resolved = await key;
+            return id === undefined ? resolved : { key: resolved, id };
+        },
+    };
+}

package/dist/encryption/keys.mjs

@@ -0,0 +1,54 @@
+// src/core/errors.ts
+var StorageError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.key = options.key;
+    if (options.cause !== void 0) this.cause = options.cause;
+  }
+};
+var StorageEncryptionError = class extends StorageError {
+};
+var StorageEncryptionUnavailableError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-unavailable", message, options);
+  }
+};
+
+// src/encryption/base64.ts
+function fromBase64(text) {
+  if (text.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(text)) throw new TypeError("Not base64.");
+  const binary = atob(text);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+
+// src/encryption/keys.ts
+var subtleOf = (crypto) => {
+  const subtle = (crypto ?? globalThis.crypto)?.subtle;
+  if (!subtle) throw new StorageEncryptionUnavailableError("Web Crypto is not available in this runtime.");
+  return subtle;
+};
+async function generateEncryptionKey(options = {}) {
+  return subtleOf(options.crypto).generateKey({ name: "AES-GCM", length: 256 }, options.extractable ?? false, ["encrypt", "decrypt"]);
+}
+async function importEncryptionKey(raw, options = {}) {
+  const bytes = typeof raw === "string" ? fromBase64(raw) : raw;
+  if (bytes.length !== 32) throw new TypeError(`An AES-256 key is 32 bytes, got ${bytes.length}.`);
+  return subtleOf(options.crypto).importKey("raw", bytes, { name: "AES-GCM" }, options.extractable ?? false, ["encrypt", "decrypt"]);
+}
+function staticKeyProvider(key, id) {
+  return {
+    async getKey() {
+      const resolved = await key;
+      return id === void 0 ? resolved : { key: resolved, id };
+    }
+  };
+}
+export {
+  generateEncryptionKey,
+  importEncryptionKey,
+  staticKeyProvider
+};