@fluixi/storage 0.1.0-alpha.0

package/dist/encryption/seal.cjs

@@ -0,0 +1,154 @@
+"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/seal.ts
+var seal_exports = {};
+__export(seal_exports, {
+  PAYLOAD_VERSION: () => PAYLOAD_VERSION,
+  open: () => open,
+  seal: () => seal
+});
+module.exports = __toCommonJS(seal_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 StorageEncryptionKeyError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-key", message, options);
+  }
+};
+var StorageEncryptionMetadataError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-metadata", message, options);
+  }
+};
+var StorageEncryptionVersionError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-version", message, options);
+  }
+};
+var StorageEncryptionAlgorithmError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-algorithm", message, options);
+  }
+};
+var StorageDecryptionError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("decryption", message, options);
+  }
+};
+var StorageEncryptedPayloadError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-payload", message, options);
+  }
+};
+
+// 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;
+}
+
+// src/encryption/seal.ts
+var PAYLOAD_VERSION = 1;
+var encoder = new TextEncoder();
+var decoder = new TextDecoder("utf-8", { fatal: true });
+var aad = (storedKey, alg, kid, meta) => encoder.encode(JSON.stringify(["fx-storage", PAYLOAD_VERSION, alg, storedKey, meta.createdAt, meta.expiresAt ?? null, meta.version ?? null, kid ?? null]));
+async function keyFor(sealer, context) {
+  if (!sealer.keyProvider) {
+    throw new StorageEncryptionKeyError(`${context.key} is encrypted, and this storage has no encryption key provider.`, { key: context.key });
+  }
+  let result;
+  try {
+    result = await sealer.keyProvider.getKey(context);
+  } catch (error) {
+    if (error instanceof StorageEncryptionError) throw error;
+    throw new StorageEncryptionKeyError(`The key provider failed for ${context.key}.`, { key: context.key, cause: error });
+  }
+  const pair = result && "key" in result && "id" in result ? result : { key: result };
+  const algorithm = pair.key?.algorithm;
+  if (!algorithm || algorithm.name !== "AES-GCM" || algorithm.length !== 256) {
+    throw new StorageEncryptionKeyError(`The key provider must return an AES-GCM 256-bit key for ${context.key}.`, { key: context.key });
+  }
+  if (!pair.key.usages.includes(context.operation)) {
+    throw new StorageEncryptionKeyError(`The key for ${context.key} does not allow ${context.operation}.`, { key: context.key });
+  }
+  return pair;
+}
+async function seal(sealer, context, storedKey, plaintext, meta) {
+  const { key, id } = await keyFor(sealer, { ...context, operation: "encrypt" });
+  const alg = sealer.provider.algorithm;
+  const out = await sealer.provider.encrypt(encoder.encode(plaintext), key, aad(storedKey, alg, id, meta));
+  const payload = { v: PAYLOAD_VERSION, alg, iv: toBase64(out.iv), data: toBase64(out.ciphertext), tag: toBase64(out.tag) };
+  if (id !== void 0) payload.kid = id;
+  return payload;
+}
+async function open(sealer, context, storedKey, payload, meta) {
+  const k = context.key;
+  const p = payload;
+  if (!p || typeof p !== "object" || typeof p.v !== "number") {
+    throw new StorageEncryptionMetadataError(`The encryption metadata of ${k} is missing its version.`, { key: k });
+  }
+  if (p.v !== PAYLOAD_VERSION) throw new StorageEncryptionVersionError(`${k} uses encryption format ${p.v}, which this release cannot read.`, { key: k });
+  if (typeof p.alg !== "string" || typeof p.iv !== "string" || typeof p.data !== "string" || typeof p.tag !== "string" || p.kid !== void 0 && typeof p.kid !== "string") {
+    throw new StorageEncryptionMetadataError(`The encryption metadata of ${k} is malformed.`, { key: k });
+  }
+  if (p.alg !== sealer.provider.algorithm) {
+    throw new StorageEncryptionAlgorithmError(`${k} is encrypted with ${p.alg}; the provider implements ${sealer.provider.algorithm}.`, { key: k });
+  }
+  let iv, ciphertext, tag;
+  try {
+    iv = fromBase64(p.iv);
+    ciphertext = fromBase64(p.data);
+    tag = fromBase64(p.tag);
+  } catch (error) {
+    throw new StorageEncryptedPayloadError(`The encrypted payload of ${k} is not valid base64.`, { key: k, cause: error });
+  }
+  if (iv.length !== 12 || tag.length !== 16) throw new StorageEncryptedPayloadError(`The encrypted payload of ${k} has a wrong IV or tag length.`, { key: k });
+  const { key } = await keyFor(sealer, { ...context, operation: "decrypt", keyId: p.kid });
+  let bytes;
+  try {
+    bytes = await sealer.provider.decrypt({ algorithm: p.alg, iv, ciphertext, tag }, key, aad(storedKey, p.alg, p.kid, meta));
+  } catch (error) {
+    throw new StorageDecryptionError(`${k} failed authentication: wrong key, or the stored entry was changed.`, { key: k, cause: error });
+  }
+  try {
+    return decoder.decode(bytes);
+  } catch (error) {
+    throw new StorageEncryptedPayloadError(`The decrypted value of ${k} is not UTF-8.`, { key: k, cause: error });
+  }
+}

package/dist/encryption/seal.d.ts

@@ -0,0 +1,24 @@
+import type { CryptoProvider, EncryptionContext, EncryptionKeyProvider } from './types.js';
+export declare const PAYLOAD_VERSION = 1;
+/** What an encrypted entry stores in place of its value. */
+export interface EncryptedPayload {
+    v: number;
+    alg: string;
+    iv: string;
+    data: string;
+    tag: string;
+    kid?: string;
+}
+/** Metadata stored in clear beside the payload. Authenticated, so editing it fails decryption. */
+export interface SealMeta {
+    createdAt: number;
+    expiresAt?: number;
+    version?: number;
+}
+export interface Sealer {
+    keyProvider?: EncryptionKeyProvider;
+    provider: CryptoProvider;
+}
+export declare function seal(sealer: Sealer, context: Omit<EncryptionContext, 'operation' | 'keyId'>, storedKey: string, plaintext: string, meta: SealMeta): Promise<EncryptedPayload>;
+export declare function open(sealer: Sealer, context: Omit<EncryptionContext, 'operation' | 'keyId'>, storedKey: string, payload: unknown, meta: SealMeta): Promise<string>;
+//# sourceMappingURL=seal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seal.d.ts","sourceRoot":"","sources":["../../src/encryption/seal.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE3F,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,kGAAkG;AAClG,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,MAAM;IACrB,WAAW,CAAC,EAAE,qBAAqB,CAAC;IACpC,QAAQ,EAAE,cAAc,CAAC;CAC1B;AA+BD,wBAAsB,IAAI,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,OAAO,CAAC,EACvD,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,gBAAgB,CAAC,CAO3B;AAED,wBAAsB,IAAI,CACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,WAAW,GAAG,OAAO,CAAC,EACvD,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,MAAM,CAAC,CAkCjB"}

package/dist/encryption/seal.js

@@ -0,0 +1,83 @@
+/**
+ * Encrypts serialized values into the stored payload and back. The payload is versioned on its
+ * own, apart from the envelope, so the scheme can change without touching plaintext entries.
+ */
+import { StorageDecryptionError, StorageEncryptedPayloadError, StorageEncryptionAlgorithmError, StorageEncryptionError, StorageEncryptionKeyError, StorageEncryptionMetadataError, StorageEncryptionVersionError, } from '../core/errors.js';
+import { fromBase64, toBase64 } from './base64.js';
+export const PAYLOAD_VERSION = 1;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+// The full stored key is bound, so a payload copied under another key does not decrypt.
+const aad = (storedKey, alg, kid, meta) => encoder.encode(JSON.stringify(['fx-storage', PAYLOAD_VERSION, alg, storedKey, meta.createdAt, meta.expiresAt ?? null, meta.version ?? null, kid ?? null]));
+async function keyFor(sealer, context) {
+    if (!sealer.keyProvider) {
+        throw new StorageEncryptionKeyError(`${context.key} is encrypted, and this storage has no encryption key provider.`, { key: context.key });
+    }
+    let result;
+    try {
+        result = await sealer.keyProvider.getKey(context);
+    }
+    catch (error) {
+        if (error instanceof StorageEncryptionError)
+            throw error;
+        throw new StorageEncryptionKeyError(`The key provider failed for ${context.key}.`, { key: context.key, cause: error });
+    }
+    const pair = result && 'key' in result && 'id' in result ? result : { key: result };
+    const algorithm = pair.key?.algorithm;
+    if (!algorithm || algorithm.name !== 'AES-GCM' || algorithm.length !== 256) {
+        throw new StorageEncryptionKeyError(`The key provider must return an AES-GCM 256-bit key for ${context.key}.`, { key: context.key });
+    }
+    if (!pair.key.usages.includes(context.operation)) {
+        throw new StorageEncryptionKeyError(`The key for ${context.key} does not allow ${context.operation}.`, { key: context.key });
+    }
+    return pair;
+}
+export async function seal(sealer, context, storedKey, plaintext, meta) {
+    const { key, id } = await keyFor(sealer, { ...context, operation: 'encrypt' });
+    const alg = sealer.provider.algorithm;
+    const out = await sealer.provider.encrypt(encoder.encode(plaintext), key, aad(storedKey, alg, id, meta));
+    const payload = { v: PAYLOAD_VERSION, alg, iv: toBase64(out.iv), data: toBase64(out.ciphertext), tag: toBase64(out.tag) };
+    if (id !== undefined)
+        payload.kid = id;
+    return payload;
+}
+export async function open(sealer, context, storedKey, payload, meta) {
+    const k = context.key;
+    const p = payload;
+    if (!p || typeof p !== 'object' || typeof p.v !== 'number') {
+        throw new StorageEncryptionMetadataError(`The encryption metadata of ${k} is missing its version.`, { key: k });
+    }
+    if (p.v !== PAYLOAD_VERSION)
+        throw new StorageEncryptionVersionError(`${k} uses encryption format ${p.v}, which this release cannot read.`, { key: k });
+    if (typeof p.alg !== 'string' || typeof p.iv !== 'string' || typeof p.data !== 'string' || typeof p.tag !== 'string' || (p.kid !== undefined && typeof p.kid !== 'string')) {
+        throw new StorageEncryptionMetadataError(`The encryption metadata of ${k} is malformed.`, { key: k });
+    }
+    if (p.alg !== sealer.provider.algorithm) {
+        throw new StorageEncryptionAlgorithmError(`${k} is encrypted with ${p.alg}; the provider implements ${sealer.provider.algorithm}.`, { key: k });
+    }
+    let iv, ciphertext, tag;
+    try {
+        iv = fromBase64(p.iv);
+        ciphertext = fromBase64(p.data);
+        tag = fromBase64(p.tag);
+    }
+    catch (error) {
+        throw new StorageEncryptedPayloadError(`The encrypted payload of ${k} is not valid base64.`, { key: k, cause: error });
+    }
+    if (iv.length !== 12 || tag.length !== 16)
+        throw new StorageEncryptedPayloadError(`The encrypted payload of ${k} has a wrong IV or tag length.`, { key: k });
+    const { key } = await keyFor(sealer, { ...context, operation: 'decrypt', keyId: p.kid });
+    let bytes;
+    try {
+        bytes = await sealer.provider.decrypt({ algorithm: p.alg, iv, ciphertext, tag }, key, aad(storedKey, p.alg, p.kid, meta));
+    }
+    catch (error) {
+        throw new StorageDecryptionError(`${k} failed authentication: wrong key, or the stored entry was changed.`, { key: k, cause: error });
+    }
+    try {
+        return decoder.decode(bytes);
+    }
+    catch (error) {
+        throw new StorageEncryptedPayloadError(`The decrypted value of ${k} is not UTF-8.`, { key: k, cause: error });
+    }
+}

package/dist/encryption/seal.mjs

@@ -0,0 +1,131 @@
+// 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 StorageEncryptionKeyError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-key", message, options);
+  }
+};
+var StorageEncryptionMetadataError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-metadata", message, options);
+  }
+};
+var StorageEncryptionVersionError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-version", message, options);
+  }
+};
+var StorageEncryptionAlgorithmError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-algorithm", message, options);
+  }
+};
+var StorageDecryptionError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("decryption", message, options);
+  }
+};
+var StorageEncryptedPayloadError = class extends StorageEncryptionError {
+  constructor(message, options = {}) {
+    super("encryption-payload", message, options);
+  }
+};
+
+// 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;
+}
+
+// src/encryption/seal.ts
+var PAYLOAD_VERSION = 1;
+var encoder = new TextEncoder();
+var decoder = new TextDecoder("utf-8", { fatal: true });
+var aad = (storedKey, alg, kid, meta) => encoder.encode(JSON.stringify(["fx-storage", PAYLOAD_VERSION, alg, storedKey, meta.createdAt, meta.expiresAt ?? null, meta.version ?? null, kid ?? null]));
+async function keyFor(sealer, context) {
+  if (!sealer.keyProvider) {
+    throw new StorageEncryptionKeyError(`${context.key} is encrypted, and this storage has no encryption key provider.`, { key: context.key });
+  }
+  let result;
+  try {
+    result = await sealer.keyProvider.getKey(context);
+  } catch (error) {
+    if (error instanceof StorageEncryptionError) throw error;
+    throw new StorageEncryptionKeyError(`The key provider failed for ${context.key}.`, { key: context.key, cause: error });
+  }
+  const pair = result && "key" in result && "id" in result ? result : { key: result };
+  const algorithm = pair.key?.algorithm;
+  if (!algorithm || algorithm.name !== "AES-GCM" || algorithm.length !== 256) {
+    throw new StorageEncryptionKeyError(`The key provider must return an AES-GCM 256-bit key for ${context.key}.`, { key: context.key });
+  }
+  if (!pair.key.usages.includes(context.operation)) {
+    throw new StorageEncryptionKeyError(`The key for ${context.key} does not allow ${context.operation}.`, { key: context.key });
+  }
+  return pair;
+}
+async function seal(sealer, context, storedKey, plaintext, meta) {
+  const { key, id } = await keyFor(sealer, { ...context, operation: "encrypt" });
+  const alg = sealer.provider.algorithm;
+  const out = await sealer.provider.encrypt(encoder.encode(plaintext), key, aad(storedKey, alg, id, meta));
+  const payload = { v: PAYLOAD_VERSION, alg, iv: toBase64(out.iv), data: toBase64(out.ciphertext), tag: toBase64(out.tag) };
+  if (id !== void 0) payload.kid = id;
+  return payload;
+}
+async function open(sealer, context, storedKey, payload, meta) {
+  const k = context.key;
+  const p = payload;
+  if (!p || typeof p !== "object" || typeof p.v !== "number") {
+    throw new StorageEncryptionMetadataError(`The encryption metadata of ${k} is missing its version.`, { key: k });
+  }
+  if (p.v !== PAYLOAD_VERSION) throw new StorageEncryptionVersionError(`${k} uses encryption format ${p.v}, which this release cannot read.`, { key: k });
+  if (typeof p.alg !== "string" || typeof p.iv !== "string" || typeof p.data !== "string" || typeof p.tag !== "string" || p.kid !== void 0 && typeof p.kid !== "string") {
+    throw new StorageEncryptionMetadataError(`The encryption metadata of ${k} is malformed.`, { key: k });
+  }
+  if (p.alg !== sealer.provider.algorithm) {
+    throw new StorageEncryptionAlgorithmError(`${k} is encrypted with ${p.alg}; the provider implements ${sealer.provider.algorithm}.`, { key: k });
+  }
+  let iv, ciphertext, tag;
+  try {
+    iv = fromBase64(p.iv);
+    ciphertext = fromBase64(p.data);
+    tag = fromBase64(p.tag);
+  } catch (error) {
+    throw new StorageEncryptedPayloadError(`The encrypted payload of ${k} is not valid base64.`, { key: k, cause: error });
+  }
+  if (iv.length !== 12 || tag.length !== 16) throw new StorageEncryptedPayloadError(`The encrypted payload of ${k} has a wrong IV or tag length.`, { key: k });
+  const { key } = await keyFor(sealer, { ...context, operation: "decrypt", keyId: p.kid });
+  let bytes;
+  try {
+    bytes = await sealer.provider.decrypt({ algorithm: p.alg, iv, ciphertext, tag }, key, aad(storedKey, p.alg, p.kid, meta));
+  } catch (error) {
+    throw new StorageDecryptionError(`${k} failed authentication: wrong key, or the stored entry was changed.`, { key: k, cause: error });
+  }
+  try {
+    return decoder.decode(bytes);
+  } catch (error) {
+    throw new StorageEncryptedPayloadError(`The decrypted value of ${k} is not UTF-8.`, { key: k, cause: error });
+  }
+}
+export {
+  PAYLOAD_VERSION,
+  open,
+  seal
+};

package/dist/encryption/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/encryption/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/encryption/types.d.ts

@@ -0,0 +1,50 @@
+/** Ciphertext and what decrypting it needs, apart from the key. */
+export interface EncryptedData {
+    algorithm: string;
+    iv: Uint8Array;
+    ciphertext: Uint8Array;
+    /** The authentication tag. */
+    tag: Uint8Array;
+}
+/**
+ * The cryptographic backend. The storage only talks to this, so Web Crypto, Node's crypto or a
+ * WASM build can sit underneath without the storage knowing.
+ */
+export interface CryptoProvider {
+    /** The algorithm it implements, as stored with each entry: `AES-256-GCM`. */
+    readonly algorithm: string;
+    /** Encrypts under a fresh random IV. `aad` is authenticated, not encrypted. */
+    encrypt(data: Uint8Array, key: CryptoKey, aad?: Uint8Array): Promise<EncryptedData>;
+    /** Rejects when authentication fails. */
+    decrypt(data: EncryptedData, key: CryptoKey, aad?: Uint8Array): Promise<Uint8Array>;
+}
+export interface EncryptionContext {
+    /** The entry's key, without the namespace. */
+    key: string;
+    namespace?: string;
+    operation: 'encrypt' | 'decrypt';
+    /** On decrypt, the id the key provider gave when the entry was written. */
+    keyId?: string;
+}
+/** A key, or a key with an id that is stored with the entry so rotation can find it again. */
+export type EncryptionKey = CryptoKey | {
+    key: CryptoKey;
+    id: string;
+};
+export interface EncryptionKeyProvider {
+    getKey(context: EncryptionContext): Promise<EncryptionKey>;
+}
+/**
+ * Per-item encryption for a storage. It keeps a value confidential and detects tampering from
+ * anyone without the key; it does not replace authentication, authorization, HTTPS or secure
+ * cookies, and a key that lives next to the data protects nothing.
+ */
+export interface EncryptionOptions {
+    keyProvider: EncryptionKeyProvider;
+    /**
+     * Defaults to Web Crypto (`globalThis.crypto.subtle`): the browser's, or Node's native one,
+     * global since Node 19. A WASM provider can go here for runtimes without either.
+     */
+    provider?: CryptoProvider;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/encryption/types.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,UAAU,CAAC;IACf,UAAU,EAAE,UAAU,CAAC;IACvB,8BAA8B;IAC9B,GAAG,EAAE,UAAU,CAAC;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,OAAO,CAAC,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACpF,yCAAyC;IACzC,OAAO,CAAC,IAAI,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;CACrF;AAED,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,SAAS,GAAG,SAAS,CAAC;IACjC,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,8FAA8F;AAC9F,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC5D;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,qBAAqB,CAAC;IACnC;;;OAGG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC3B"}

package/dist/encryption/types.js

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

package/dist/encryption/web-crypto.cjs

@@ -0,0 +1,81 @@
+"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/web-crypto.ts
+var web_crypto_exports = {};
+__export(web_crypto_exports, {
+  webCryptoProvider: () => webCryptoProvider
+});
+module.exports = __toCommonJS(web_crypto_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/web-crypto.ts
+var IV_BYTES = 12;
+var TAG_BYTES = 16;
+function webCryptoProvider(crypto) {
+  const resolve = () => {
+    const c = crypto ?? globalThis.crypto;
+    if (!c?.subtle || !c.getRandomValues) {
+      throw new StorageEncryptionUnavailableError("Web Crypto is not available in this runtime; pass a provider in the encryption options.");
+    }
+    return c;
+  };
+  return {
+    algorithm: "AES-256-GCM",
+    async encrypt(data, key, aad) {
+      const c = resolve();
+      const iv = c.getRandomValues(new Uint8Array(IV_BYTES));
+      const params = { name: "AES-GCM", iv, tagLength: TAG_BYTES * 8 };
+      if (aad) params.additionalData = aad;
+      const sealed = new Uint8Array(await c.subtle.encrypt(params, key, data));
+      return {
+        algorithm: "AES-256-GCM",
+        iv,
+        ciphertext: sealed.slice(0, sealed.length - TAG_BYTES),
+        tag: sealed.slice(sealed.length - TAG_BYTES)
+      };
+    },
+    async decrypt(data, key, aad) {
+      const c = resolve();
+      const sealed = new Uint8Array(data.ciphertext.length + data.tag.length);
+      sealed.set(data.ciphertext);
+      sealed.set(data.tag, data.ciphertext.length);
+      const params = { name: "AES-GCM", iv: data.iv, tagLength: TAG_BYTES * 8 };
+      if (aad) params.additionalData = aad;
+      return new Uint8Array(await c.subtle.decrypt(params, key, sealed));
+    }
+  };
+}

package/dist/encryption/web-crypto.d.ts

@@ -0,0 +1,9 @@
+import type { CryptoProvider } from './types.js';
+/**
+ * AES-256-GCM over Web Crypto. Each call draws a new 96-bit random IV, so an IV is never
+ * deliberately reused; keep one key under about 2^32 writes before rotating it.
+ *
+ * `crypto` defaults to the global, read on first use so the module imports anywhere.
+ */
+export declare function webCryptoProvider(crypto?: Crypto): CryptoProvider;
+//# sourceMappingURL=web-crypto.d.ts.map

package/dist/encryption/web-crypto.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-crypto.d.ts","sourceRoot":"","sources":["../../src/encryption/web-crypto.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAKjD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,cAAc,CAiCjE"}

package/dist/encryption/web-crypto.js

@@ -0,0 +1,45 @@
+import { StorageEncryptionUnavailableError } from '../core/errors.js';
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+/**
+ * AES-256-GCM over Web Crypto. Each call draws a new 96-bit random IV, so an IV is never
+ * deliberately reused; keep one key under about 2^32 writes before rotating it.
+ *
+ * `crypto` defaults to the global, read on first use so the module imports anywhere.
+ */
+export function webCryptoProvider(crypto) {
+    const resolve = () => {
+        const c = crypto ?? globalThis.crypto;
+        if (!c?.subtle || !c.getRandomValues) {
+            throw new StorageEncryptionUnavailableError('Web Crypto is not available in this runtime; pass a provider in the encryption options.');
+        }
+        return c;
+    };
+    return {
+        algorithm: 'AES-256-GCM',
+        async encrypt(data, key, aad) {
+            const c = resolve();
+            const iv = c.getRandomValues(new Uint8Array(IV_BYTES));
+            const params = { name: 'AES-GCM', iv, tagLength: TAG_BYTES * 8 };
+            if (aad)
+                params.additionalData = aad;
+            const sealed = new Uint8Array(await c.subtle.encrypt(params, key, data));
+            return {
+                algorithm: 'AES-256-GCM',
+                iv,
+                ciphertext: sealed.slice(0, sealed.length - TAG_BYTES),
+                tag: sealed.slice(sealed.length - TAG_BYTES),
+            };
+        },
+        async decrypt(data, key, aad) {
+            const c = resolve();
+            const sealed = new Uint8Array(data.ciphertext.length + data.tag.length);
+            sealed.set(data.ciphertext);
+            sealed.set(data.tag, data.ciphertext.length);
+            const params = { name: 'AES-GCM', iv: data.iv, tagLength: TAG_BYTES * 8 };
+            if (aad)
+                params.additionalData = aad;
+            return new Uint8Array(await c.subtle.decrypt(params, key, sealed));
+        },
+    };
+}