@sovereignfs/sdk 1.25.0

package/dist/chunk-NQLGPAL6.js

@@ -0,0 +1,62 @@
+// src/e2ee-device.ts
+var DB_NAME = "sovereign-e2ee";
+var DB_VERSION = 1;
+var STORE_NAME = "device-keys";
+var DEVICE_ID_STORAGE_KEY = "sovereign:e2ee:deviceId";
+function openDb() {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, DB_VERSION);
+    request.onupgradeneeded = () => {
+      if (!request.result.objectStoreNames.contains(STORE_NAME)) {
+        request.result.createObjectStore(STORE_NAME);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("Failed to open IndexedDB."));
+  });
+}
+function getOrCreateDeviceId() {
+  const existing = localStorage.getItem(DEVICE_ID_STORAGE_KEY);
+  if (existing) return existing;
+  const id = crypto.randomUUID();
+  localStorage.setItem(DEVICE_ID_STORAGE_KEY, id);
+  return id;
+}
+async function storeDeviceKey(deviceId, key) {
+  const db = await openDb();
+  await new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readwrite");
+    tx.objectStore(STORE_NAME).put(key, deviceId);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error ?? new Error("Failed to store device key."));
+  });
+  db.close();
+}
+async function getDeviceKey(deviceId) {
+  const db = await openDb();
+  const result = await new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readonly");
+    const request = tx.objectStore(STORE_NAME).get(deviceId);
+    request.onsuccess = () => resolve(request.result ?? null);
+    request.onerror = () => reject(request.error ?? new Error("Failed to read device key."));
+  });
+  db.close();
+  return result;
+}
+async function forgetDeviceKey(deviceId) {
+  const db = await openDb();
+  await new Promise((resolve, reject) => {
+    const tx = db.transaction(STORE_NAME, "readwrite");
+    tx.objectStore(STORE_NAME).delete(deviceId);
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error ?? new Error("Failed to remove device key."));
+  });
+  db.close();
+}
+
+export {
+  getOrCreateDeviceId,
+  storeDeviceKey,
+  getDeviceKey,
+  forgetDeviceKey
+};

package/dist/e2ee-crypto.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Client-side Client Master Key (CMK) crypto (RFC 0060). Pure WebCrypto —
+ * runs in the browser (or any environment with a global `crypto.subtle`,
+ * which includes Node for testing). No plaintext key material or wrapped
+ * bytes ever need to leave this module's caller before being sent to the
+ * server as opaque ciphertext.
+ *
+ * Resolves RFC 0060 open question 2 (browser KDF choice): PBKDF2-HMAC-SHA256
+ * via native WebCrypto, not Argon2id — Argon2id has no native WebCrypto
+ * primitive, and pulling in a WASM implementation is out of scope for this
+ * pass. `kdfAlgorithm`/`kdfParams` are stored per-wrapper specifically so a
+ * future Argon2id upgrade doesn't require a schema change, only a new
+ * `kdfAlgorithm` value and a migration path for existing wrappers.
+ *
+ * Scope: CMK generation, master-key wrap/unwrap (recovery secret, device
+ * key), and per-object Data Encryption Key (DEK) generation/wrap/unwrap.
+ * Generic Blob/JSON encrypt/decrypt helpers that use a DEK live in
+ * `e2ee-object.ts`; this module only handles key material.
+ */
+declare const CMK_ALGORITHM = "AES-GCM-256";
+declare const KDF_ALGORITHM = "PBKDF2-SHA256";
+declare const WRAP_ALGORITHM_VERSION = "v1";
+/** Ciphertext + metadata needed to unwrap a CMK later. Safe to store server-side as-is. */
+interface WrappedCmk {
+    /** Base64url `iv || ciphertext`. */
+    wrappedCmk: string;
+    algorithmVersion: string;
+}
+/** A `WrappedCmk` plus the KDF metadata needed to re-derive the wrapping key from a secret. */
+interface RecoveryWrappedCmk extends WrappedCmk {
+    kdfAlgorithm: string;
+    /** JSON-encoded KDF parameters. */
+    kdfParams: string;
+    kdfSalt: string;
+}
+/** Ciphertext + metadata needed to unwrap a per-object DEK later. Safe to store server-side as-is. */
+interface WrappedDek {
+    /** Base64url `iv || ciphertext`. */
+    wrappedDek: string;
+    algorithmVersion: string;
+}
+/**
+ * A high-entropy, human-recordable recovery secret. Grouped base32
+ * (Crockford-ish alphabet, ambiguous characters removed) rather than a
+ * BIP39 word list — no wordlist dependency, ~160 bits of entropy in 32
+ * displayed characters across 6 groups (e.g. `AB3DE-FGH2J-...`).
+ */
+declare function generateRecoverySecret(): string;
+/**
+ * Generate a new, extractable Client Master Key. Includes `wrapKey`/
+ * `unwrapKey` usages (not just `encrypt`/`decrypt`) since the CMK wraps
+ * per-object DEKs (`wrapDekWithCmk`/`unwrapDekWithCmk` below) in addition to
+ * being itself wrapped by a recovery secret or device key.
+ */
+declare function generateCmk(): Promise<CryptoKey>;
+/** Wrap the CMK with a key derived from the user's recovery secret. */
+declare function wrapCmkWithRecoverySecret(cmk: CryptoKey, recoverySecret: string): Promise<RecoveryWrappedCmk>;
+/** Unwrap the CMK given the recovery secret. Throws if the secret is wrong. */
+declare function unwrapCmkWithRecoverySecret(wrapped: RecoveryWrappedCmk, recoverySecret: string): Promise<CryptoKey>;
+/**
+ * Generate a device-local wrapping key. Non-extractable — once created, no
+ * script (including a compromised page on this origin) can ever read its raw
+ * bytes back out via `exportKey`; it can only be used, via its `CryptoKey`
+ * handle, for wrap/unwrap. Must be persisted with IndexedDB (the only Web
+ * storage API that can hold a live `CryptoKey`) — see `e2ee-device.ts`.
+ */
+declare function generateDeviceKey(): Promise<CryptoKey>;
+/** Wrap the CMK with this device's own key. */
+declare function wrapCmkWithDeviceKey(cmk: CryptoKey, deviceKey: CryptoKey): Promise<WrappedCmk>;
+/** Unwrap the CMK using this device's own key. */
+declare function unwrapCmkWithDeviceKey(wrapped: WrappedCmk, deviceKey: CryptoKey): Promise<CryptoKey>;
+/**
+ * Generate a new, extractable per-object Data Encryption Key (DEK). One DEK
+ * per encrypted object/document — never reused across objects — so
+ * compromising a single object's key never exposes any other object (RFC
+ * 0060 key hierarchy: CMK wraps DEKs, DEKs encrypt object content).
+ */
+declare function generateDek(): Promise<CryptoKey>;
+/** Wrap a per-object DEK with the (unlocked) CMK. Safe to store server-side as-is. */
+declare function wrapDekWithCmk(dek: CryptoKey, cmk: CryptoKey): Promise<WrappedDek>;
+/** Unwrap a per-object DEK using the (unlocked) CMK. Throws if the CMK doesn't match. */
+declare function unwrapDekWithCmk(wrapped: WrappedDek, cmk: CryptoKey): Promise<CryptoKey>;
+
+export { CMK_ALGORITHM, KDF_ALGORITHM, type RecoveryWrappedCmk, WRAP_ALGORITHM_VERSION, type WrappedCmk, type WrappedDek, generateCmk, generateDek, generateDeviceKey, generateRecoverySecret, unwrapCmkWithDeviceKey, unwrapCmkWithRecoverySecret, unwrapDekWithCmk, wrapCmkWithDeviceKey, wrapCmkWithRecoverySecret, wrapDekWithCmk };

package/dist/e2ee-crypto.js

@@ -0,0 +1,162 @@
+import "./chunk-MLKGABMK.js";
+
+// src/e2ee-crypto.ts
+var AES_GCM_KEY_LENGTH = 256;
+var AES_GCM_IV_BYTES = 12;
+var PBKDF2_SALT_BYTES = 16;
+var PBKDF2_ITERATIONS = 6e5;
+var RECOVERY_SECRET_ENTROPY_BYTES = 20;
+var CMK_ALGORITHM = "AES-GCM-256";
+var KDF_ALGORITHM = "PBKDF2-SHA256";
+var WRAP_ALGORITHM_VERSION = "v1";
+var CMK_KEY_USAGES = ["encrypt", "decrypt", "wrapKey", "unwrapKey"];
+var DEK_KEY_USAGES = ["encrypt", "decrypt"];
+function toBase64Url(bytes) {
+  const arr = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let binary = "";
+  for (const byte of arr) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(value) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const withPadding = padded + "=".repeat((4 - padded.length % 4) % 4);
+  const binary = atob(withPadding);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function concatBytes(a, b) {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+function generateRecoverySecret() {
+  const alphabet = "ABCDEFGHJKMNPQRSTUVWXYZ23456789";
+  const bytes = crypto.getRandomValues(new Uint8Array(RECOVERY_SECRET_ENTROPY_BYTES));
+  let out = "";
+  for (const byte of bytes) out += alphabet[byte % alphabet.length];
+  return out.match(/.{1,5}/g)?.join("-") ?? out;
+}
+function generateCmk() {
+  return crypto.subtle.generateKey(
+    { name: "AES-GCM", length: AES_GCM_KEY_LENGTH },
+    true,
+    CMK_KEY_USAGES
+  );
+}
+async function deriveWrappingKeyFromSecret(secret, salt) {
+  const keyMaterial = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret.normalize("NFKC")),
+    "PBKDF2",
+    false,
+    ["deriveKey"]
+  );
+  return crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt, iterations: PBKDF2_ITERATIONS, hash: "SHA-256" },
+    keyMaterial,
+    { name: "AES-GCM", length: AES_GCM_KEY_LENGTH },
+    false,
+    ["wrapKey", "unwrapKey"]
+  );
+}
+async function wrapCmkWithRecoverySecret(cmk, recoverySecret) {
+  const salt = crypto.getRandomValues(new Uint8Array(PBKDF2_SALT_BYTES));
+  const wrappingKey = await deriveWrappingKeyFromSecret(recoverySecret, salt);
+  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
+  const wrapped = await crypto.subtle.wrapKey("raw", cmk, wrappingKey, {
+    name: "AES-GCM",
+    iv
+  });
+  return {
+    wrappedCmk: toBase64Url(concatBytes(iv, new Uint8Array(wrapped))),
+    kdfAlgorithm: KDF_ALGORITHM,
+    kdfParams: JSON.stringify({ iterations: PBKDF2_ITERATIONS, hash: "SHA-256" }),
+    kdfSalt: toBase64Url(salt),
+    algorithmVersion: WRAP_ALGORITHM_VERSION
+  };
+}
+async function unwrapCmkWithRecoverySecret(wrapped, recoverySecret) {
+  const salt = fromBase64Url(wrapped.kdfSalt);
+  const wrappingKey = await deriveWrappingKeyFromSecret(recoverySecret, salt);
+  const combined = fromBase64Url(wrapped.wrappedCmk);
+  const iv = combined.slice(0, AES_GCM_IV_BYTES);
+  const ciphertext = combined.slice(AES_GCM_IV_BYTES);
+  return crypto.subtle.unwrapKey(
+    "raw",
+    ciphertext,
+    wrappingKey,
+    { name: "AES-GCM", iv },
+    { name: "AES-GCM", length: AES_GCM_KEY_LENGTH },
+    true,
+    CMK_KEY_USAGES
+  );
+}
+function generateDeviceKey() {
+  return crypto.subtle.generateKey({ name: "AES-GCM", length: AES_GCM_KEY_LENGTH }, false, [
+    "wrapKey",
+    "unwrapKey"
+  ]);
+}
+async function wrapKeyWith(key, wrappingKey) {
+  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
+  const wrapped = await crypto.subtle.wrapKey("raw", key, wrappingKey, {
+    name: "AES-GCM",
+    iv
+  });
+  return {
+    value: toBase64Url(concatBytes(iv, new Uint8Array(wrapped))),
+    algorithmVersion: WRAP_ALGORITHM_VERSION
+  };
+}
+async function unwrapKeyWith(wrappedValue, wrappingKey, extractable, usages) {
+  const combined = fromBase64Url(wrappedValue);
+  const iv = combined.slice(0, AES_GCM_IV_BYTES);
+  const ciphertext = combined.slice(AES_GCM_IV_BYTES);
+  return crypto.subtle.unwrapKey(
+    "raw",
+    ciphertext,
+    wrappingKey,
+    { name: "AES-GCM", iv },
+    { name: "AES-GCM", length: AES_GCM_KEY_LENGTH },
+    extractable,
+    usages
+  );
+}
+async function wrapCmkWithDeviceKey(cmk, deviceKey) {
+  const { value, algorithmVersion } = await wrapKeyWith(cmk, deviceKey);
+  return { wrappedCmk: value, algorithmVersion };
+}
+function unwrapCmkWithDeviceKey(wrapped, deviceKey) {
+  return unwrapKeyWith(wrapped.wrappedCmk, deviceKey, true, CMK_KEY_USAGES);
+}
+function generateDek() {
+  return crypto.subtle.generateKey(
+    { name: "AES-GCM", length: AES_GCM_KEY_LENGTH },
+    true,
+    DEK_KEY_USAGES
+  );
+}
+async function wrapDekWithCmk(dek, cmk) {
+  const { value, algorithmVersion } = await wrapKeyWith(dek, cmk);
+  return { wrappedDek: value, algorithmVersion };
+}
+function unwrapDekWithCmk(wrapped, cmk) {
+  return unwrapKeyWith(wrapped.wrappedDek, cmk, true, DEK_KEY_USAGES);
+}
+export {
+  CMK_ALGORITHM,
+  KDF_ALGORITHM,
+  WRAP_ALGORITHM_VERSION,
+  generateCmk,
+  generateDek,
+  generateDeviceKey,
+  generateRecoverySecret,
+  unwrapCmkWithDeviceKey,
+  unwrapCmkWithRecoverySecret,
+  unwrapDekWithCmk,
+  wrapCmkWithDeviceKey,
+  wrapCmkWithRecoverySecret,
+  wrapDekWithCmk
+};

package/dist/e2ee-device.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Browser-only persistence for this device's local E2EE wrapping key
+ * (RFC 0060). The key itself is generated non-extractable
+ * (`e2ee-crypto.ts#generateDeviceKey`) so it must be persisted via
+ * IndexedDB — the only Web storage API that can hold a live `CryptoKey`
+ * across page loads (`localStorage`/cookies cannot serialize one).
+ *
+ * The device id is a random UUID, not sensitive on its own (it is just a
+ * label distinguishing this browser/device's enrollment row from others) and
+ * is stored in `localStorage` alongside the IndexedDB key entry.
+ */
+/** This browser/device's stable id — generated once, persisted in `localStorage`. */
+declare function getOrCreateDeviceId(): string;
+/** Persist this device's local wrapping key, keyed by device id. */
+declare function storeDeviceKey(deviceId: string, key: CryptoKey): Promise<void>;
+/** Read this device's local wrapping key, or `null` if never enrolled on this device/browser. */
+declare function getDeviceKey(deviceId: string): Promise<CryptoKey | null>;
+/** Remove this device's local wrapping key (e.g. after the user revokes it from another device). */
+declare function forgetDeviceKey(deviceId: string): Promise<void>;
+
+export { forgetDeviceKey, getDeviceKey, getOrCreateDeviceId, storeDeviceKey };

package/dist/e2ee-device.js

@@ -0,0 +1,13 @@
+import {
+  forgetDeviceKey,
+  getDeviceKey,
+  getOrCreateDeviceId,
+  storeDeviceKey
+} from "./chunk-NQLGPAL6.js";
+import "./chunk-MLKGABMK.js";
+export {
+  forgetDeviceKey,
+  getDeviceKey,
+  getOrCreateDeviceId,
+  storeDeviceKey
+};

package/dist/e2ee-object.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Encrypt/decrypt helpers for plugin object content under a per-object Data
+ * Encryption Key (DEK) (RFC 0060 step 4). Pure WebCrypto, browser-only in
+ * practice (also runs in Node for testing). Callers are responsible for
+ * generating the DEK (`generateDek` in `e2ee-crypto.ts`) and wrapping it
+ * under the unlocked CMK (`wrapDekWithCmk`) before storing the wrapped DEK
+ * alongside the ciphertext this module produces — this module only ever
+ * touches the unwrapped DEK, never the CMK.
+ *
+ * Two shapes are covered, matching RFC 0060's plaintext/encrypted metadata
+ * split:
+ * - `encryptBlob`/`decryptBlob` — binary payloads (document images, etc.)
+ *   meant to travel through `sdk.storage` as opaque ciphertext.
+ * - `encryptJson`/`decryptJson` — the "encrypted metadata" half of an
+ *   object's fields (human-readable title, notes, document number, etc.),
+ *   as opposed to the plaintext routing metadata (object id, plugin id,
+ *   storage key) plugins keep server-visible.
+ *
+ * Each result carries its own IV and `algorithmVersion` so a future cipher
+ * change is versioned per-object, not global — mirrors the wrapped-key shapes
+ * in `e2ee-crypto.ts`.
+ */
+declare const OBJECT_ALGORITHM_VERSION = "v1";
+/** Encrypted binary payload — the `ciphertext` Blob is safe to upload as opaque bytes. */
+interface EncryptedBlob {
+    ciphertext: Blob;
+    /** Base64url IV used for this encryption. */
+    iv: string;
+    algorithmVersion: string;
+    /** The original `Blob.type`, needed to reconstruct it on decrypt. */
+    contentType: string;
+}
+/** Encrypted JSON metadata — safe to store server-side as opaque ciphertext. */
+interface EncryptedJson {
+    /** Base64url ciphertext of the UTF-8 JSON-serialized value. */
+    ciphertext: string;
+    /** Base64url IV used for this encryption. */
+    iv: string;
+    algorithmVersion: string;
+}
+/** Encrypt a `Blob` (e.g. a document image) under the given DEK. */
+declare function encryptBlob(dek: CryptoKey, blob: Blob): Promise<EncryptedBlob>;
+/** Decrypt a `Blob` previously produced by `encryptBlob` with the matching DEK. */
+declare function decryptBlob(dek: CryptoKey, encrypted: EncryptedBlob): Promise<Blob>;
+/** Encrypt a JSON-serializable value (e.g. an object's human-readable metadata) under the given DEK. */
+declare function encryptJson<T>(dek: CryptoKey, value: T): Promise<EncryptedJson>;
+/** Decrypt a JSON value previously produced by `encryptJson` with the matching DEK. */
+declare function decryptJson<T>(dek: CryptoKey, encrypted: EncryptedJson): Promise<T>;
+
+export { type EncryptedBlob, type EncryptedJson, OBJECT_ALGORITHM_VERSION, decryptBlob, decryptJson, encryptBlob, encryptJson };

package/dist/e2ee-object.js

@@ -0,0 +1,75 @@
+import "./chunk-MLKGABMK.js";
+
+// src/e2ee-object.ts
+var AES_GCM_IV_BYTES = 12;
+var OBJECT_ALGORITHM_VERSION = "v1";
+function toBase64Url(bytes) {
+  const arr = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let binary = "";
+  for (const byte of arr) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromBase64Url(value) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  const withPadding = padded + "=".repeat((4 - padded.length % 4) % 4);
+  const binary = atob(withPadding);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+async function encryptBlob(dek, blob) {
+  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
+  const plaintext = await blob.arrayBuffer();
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    dek,
+    plaintext
+  );
+  return {
+    ciphertext: new Blob([ciphertext], { type: "application/octet-stream" }),
+    iv: toBase64Url(iv),
+    algorithmVersion: OBJECT_ALGORITHM_VERSION,
+    contentType: blob.type
+  };
+}
+async function decryptBlob(dek, encrypted) {
+  const iv = fromBase64Url(encrypted.iv);
+  const ciphertext = await encrypted.ciphertext.arrayBuffer();
+  const plaintext = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv },
+    dek,
+    ciphertext
+  );
+  return new Blob([plaintext], { type: encrypted.contentType });
+}
+async function encryptJson(dek, value) {
+  const iv = crypto.getRandomValues(new Uint8Array(AES_GCM_IV_BYTES));
+  const plaintext = new TextEncoder().encode(JSON.stringify(value));
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    dek,
+    plaintext
+  );
+  return {
+    ciphertext: toBase64Url(ciphertext),
+    iv: toBase64Url(iv),
+    algorithmVersion: OBJECT_ALGORITHM_VERSION
+  };
+}
+async function decryptJson(dek, encrypted) {
+  const iv = fromBase64Url(encrypted.iv);
+  const ciphertext = fromBase64Url(encrypted.ciphertext);
+  const plaintext = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv },
+    dek,
+    ciphertext
+  );
+  return JSON.parse(new TextDecoder().decode(plaintext));
+}
+export {
+  OBJECT_ALGORITHM_VERSION,
+  decryptBlob,
+  decryptJson,
+  encryptBlob,
+  encryptJson
+};