selfstore 1.0.0

package/dist/cache-De5_sALA.d.ts

@@ -0,0 +1,129 @@
+/** The `keying` header value for group-mode boxes (see SPEC.md section 12). */
+declare const GROUP_KEYING = "x25519-hkdf-sha256";
+/**
+ * A member's full identity: private halves PKCS#8 DER, public halves raw 32
+ * bytes, all base64. Treat the *Priv fields like a password - seal them at
+ * rest (identityVault) and move them only over a trusted channel.
+ */
+interface GroupIdentity {
+    sigPub: string;
+    sigPriv: string;
+    encPub: string;
+    encPriv: string;
+}
+/** One member as the manifest lists them: public keys only. */
+interface GroupMember {
+    id: string;
+    label?: string;
+    /** Ed25519 public key (base64 raw): verifies the copies this member signs. */
+    sig: string;
+    /** X25519 public key (base64 raw): receives the data-key envelopes. */
+    enc: string;
+}
+/**
+ * The membership document, single-writer (the admin), carried as a
+ * SignedManifest. `seq` grows on every change; consumers refuse a lower seq
+ * than one already applied (the store persists the high-water mark).
+ */
+interface GroupManifest {
+    v: 1;
+    /** Random group id (base64), so seq high-water marks never collide. */
+    group: string;
+    seq: number;
+    /** The admin's Ed25519 public key. Members pin it at join time (TOFU). */
+    admin: string;
+    members: GroupMember[];
+}
+/**
+ * A manifest as it travels: the exact signed payload bytes plus the admin's
+ * signature. Signing bytes rather than re-serialized JSON sidesteps
+ * canonicalization entirely.
+ */
+interface SignedManifest {
+    selfstoreManifest: 1;
+    payload: string;
+    sig: string;
+}
+/** Whether WebCrypto implements Ed25519 + X25519 here. Password mode never needs this. */
+declare function groupCryptoAvailable(): Promise<boolean>;
+/** Generate a fresh member identity (two keypairs). */
+declare function generateIdentity(): Promise<GroupIdentity>;
+/** The shareable half of an identity: what the admin puts in the manifest. */
+declare function publicIdentity(id: GroupIdentity): {
+    sig: string;
+    enc: string;
+};
+/** A fresh random group id for a new manifest. */
+declare function newGroupId(): string;
+/** First 8 bytes of SHA-256(raw X25519 public), base64: finds a reader's stanza while naming nobody. */
+declare function keyId(encPubB64: string): Promise<string>;
+/** Sign a manifest with the admin key, over the exact payload bytes. */
+declare function signManifest(manifest: GroupManifest, adminSigPrivB64: string): Promise<SignedManifest>;
+/**
+ * Verify and parse a signed manifest against the pinned admin key (TOFU from
+ * the invite). Rollback (seq) is enforced by the store, which persists the
+ * high-water mark.
+ */
+declare function openManifest(signed: SignedManifest, adminSigPubB64: string, expectedGroupB64?: string): Promise<GroupManifest>;
+
+/** A binary attachment kept as a real Blob. */
+interface CachedFile {
+    id: string;
+    name: string;
+    mime: string;
+    blob: Blob;
+}
+/** A tiny async key/value space for the store's bookkeeping. */
+interface KV {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    del(key: string): Promise<void>;
+}
+interface LocalCache {
+    readonly kv: KV;
+    /** Load the persisted collections + files, or null if nothing was ever saved. */
+    load(): Promise<{
+        collections: Record<string, unknown[]>;
+        files: CachedFile[];
+    } | null>;
+    /** Overwrite the collections snapshot (small; written on every change). */
+    saveCollections(collections: Record<string, unknown[]>): Promise<void>;
+    /** Reconcile the file store: add new blobs, drop removed ones (immutable by id). */
+    saveFiles(files: CachedFile[]): Promise<void>;
+    /** Wipe every locally-stored byte (the "forget me on this device" action). */
+    clear(): Promise<void>;
+    /** Ask the platform to make storage persistent (not evicted). Best-effort;
+     *  optional because only browser-backed caches have the concept. */
+    requestPersistent?(): Promise<boolean>;
+}
+/** A cache whose payload seal key is not on disk but supplied per session from
+ *  a secret held in memory (a password, or an app-provided key such as a passkey
+ *  PRF). Until unlock() succeeds each session, load()/save*() reject with
+ *  PASSWORD_REQUIRED. Defeats a full-profile copy, which a device key cannot -
+ *  see indexedDbCache(name, { lock: true }). */
+interface LockableCache extends LocalCache {
+    /** Supply the session secret. A string is Argon2id-derived (the salt is
+     *  persisted in the clear); a CryptoKey is used as-is. Returns false when it
+     *  does not open existing data - the cache stays locked. The first secret on
+     *  an empty cache sets the lock. */
+    unlock(secret: string | CryptoKey): Promise<boolean>;
+    /** Drop the in-memory key: reads and writes lock until unlock() is called. */
+    lockNow(): void;
+    /** Whether no seal key is currently held. */
+    readonly locked: boolean;
+}
+/** Narrow a cache to its lockable shape (created with { lock: true }). */
+declare function isLockableCache(cache: LocalCache): cache is LockableCache;
+/** In-memory LocalCache for tests and SSR paths where IndexedDB does not
+ *  exist. Not encrypted - nothing is at rest. */
+declare function memoryCache(): LocalCache;
+/** The default browser cache. `name` scopes the database to one app, so two
+ *  apps on the same origin never collide. */
+declare function indexedDbCache(name: string, opts: {
+    lock: true;
+}): LockableCache;
+declare function indexedDbCache(name: string, opts?: {
+    lock?: boolean;
+}): LocalCache;
+
+export { type CachedFile as C, type GroupIdentity as G, type KV as K, type LocalCache as L, type SignedManifest as S, GROUP_KEYING as a, type GroupManifest as b, type GroupMember as c, groupCryptoAvailable as d, type LockableCache as e, isLockableCache as f, generateIdentity as g, indexedDbCache as i, keyId as k, memoryCache as m, newGroupId as n, openManifest as o, publicIdentity as p, signManifest as s };

package/dist/cache-lock-LZILZNLP.js

@@ -0,0 +1,23 @@
+import { unseal } from './chunk-QBCU7OOP.js';
+import { freshKdfParams, deriveKey } from './chunk-FDPAKHQS.js';
+import './chunk-VBFMMR7Q.js';
+
+// src/persistence/cache-lock.ts
+function freshCacheKdf() {
+  return freshKdfParams();
+}
+function keyFromPassword(password, kdf) {
+  return deriveKey(password, kdf);
+}
+async function opens(key, probe) {
+  try {
+    await unseal(key, probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export { freshCacheKdf, keyFromPassword, opens };
+//# sourceMappingURL=cache-lock-LZILZNLP.js.map
+//# sourceMappingURL=cache-lock-LZILZNLP.js.map

package/dist/cache-lock-LZILZNLP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/persistence/cache-lock.ts"],"names":[],"mappings":";;;;;AAeO,SAAS,aAAA,GAA0B;AACzC,EAAA,OAAO,cAAA,EAAe;AACvB;AAGO,SAAS,eAAA,CAAgB,UAAkB,GAAA,EAAmC;AACpF,EAAA,OAAO,SAAA,CAAU,UAAU,GAAG,CAAA;AAC/B;AAIA,eAAsB,KAAA,CAAM,KAAgB,KAAA,EAAsC;AACjF,EAAA,IAAI;AACH,IAAA,MAAM,MAAA,CAAO,KAAK,KAAK,CAAA;AACvB,IAAA,OAAO,IAAA;AAAA,EACR,CAAA,CAAA,MAAQ;AACP,IAAA,OAAO,KAAA;AAAA,EACR;AACD","file":"cache-lock-LZILZNLP.js","sourcesContent":["// Seal-key material for a lock-mode cache. The key is derived from a password\n// (the backup's Argon2id KDF) or supplied by the app (e.g. a passkey PRF key),\n// and is held in memory only - never written next to the data. That is what a\n// device-key seal (cache-crypto) cannot give: a copy of the whole browser\n// profile carries the device key, but not a secret kept in RAM. Only the KDF\n// salt is persisted, and a salt is not secret.\n\nimport { unseal, type EncEnvelope } from './cache-crypto';\nimport { deriveKey, freshKdfParams } from '../selfstore/crypto';\nimport type { KdfParams } from '../selfstore/types';\n\n/** Argon2id parameters for a password-locked cache; persisted in the clear. */\nexport type CacheKdf = KdfParams;\n\n/** Fresh Argon2id parameters (random salt, current default cost). */\nexport function freshCacheKdf(): CacheKdf {\n\treturn freshKdfParams();\n}\n\n/** Derive the AES-GCM seal key from a password and its stored parameters. */\nexport function keyFromPassword(password: string, kdf: CacheKdf): Promise<CryptoKey> {\n\treturn deriveKey(password, kdf);\n}\n\n/** True if `key` decrypts `probe`. A wrong key fails AES-GCM authentication;\n *  that is a wrong-secret answer, never an error to surface. */\nexport async function opens(key: CryptoKey, probe: EncEnvelope): Promise<boolean> {\n\ttry {\n\t\tawait unseal(key, probe);\n\t\treturn true;\n\t} catch {\n\t\treturn false;\n\t}\n}\n"]}

package/dist/chunk-ATUPHVLG.js

@@ -0,0 +1,441 @@
+import { connect4, connect3, isSupported, connect, openExisting, connect2 } from './chunk-CUWB5EWF.js';
+import { restore } from './chunk-JB4JHM7V.js';
+import { makeMachine, withDeadline, toStoreError } from './chunk-SGISYMT5.js';
+import { SelfstoreError, isSelfstoreError } from './chunk-VBFMMR7Q.js';
+
+// src/flows/connect.ts
+var DEFAULT_DEADLINE_MS = 3e4;
+function planFor(how) {
+  if (how === "resume") return { strategy: "replace-local", outcome: "resumed" };
+  if (how === "replace") return { strategy: "replace-remote", outcome: "replaced" };
+  return { strategy: "merge", outcome: "merged" };
+}
+function connectFlow(store, targets, options = {}) {
+  const host = "flowHost" in store ? store.flowHost : store;
+  const deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS;
+  const kinds = Object.keys(targets).filter(
+    (k) => (k === "drive" || k === "file" || k === "webdav" || k === "s3") && targets[k] != null
+  );
+  const m = makeMachine({
+    step: "choose",
+    kinds,
+    kind: null,
+    outcome: null,
+    hasBackup: false,
+    encrypted: false,
+    passwordError: false,
+    busy: false,
+    error: null
+  });
+  let generation = 0;
+  let target = null;
+  let password = null;
+  const backToChoose = () => {
+    generation++;
+    target = null;
+    password = null;
+    m.set({
+      step: "choose",
+      kind: null,
+      outcome: null,
+      hasBackup: false,
+      encrypted: false,
+      passwordError: false,
+      busy: false,
+      error: null
+    });
+  };
+  const fail = (e) => {
+    password = null;
+    m.set({ step: "error", busy: false, error: toStoreError(e) });
+  };
+  function connectorFor(kind, variant = "create") {
+    const spec = targets[kind];
+    if (spec == null) return null;
+    if (typeof spec === "function") return spec;
+    if (kind === "drive") {
+      const auth = spec;
+      return () => connect({ auth, kv: host.kv, fileName: host.backupName });
+    }
+    if (kind === "file") {
+      if (typeof spec === "object" && !("url" in spec)) {
+        const sub = spec[variant];
+        if (sub == null) return null;
+        if (typeof sub === "function") return sub;
+        return variant === "open" ? () => openExisting({ kv: host.kv }) : () => connect2({ kv: host.kv, fileName: host.backupName });
+      }
+      return () => connect2({ kv: host.kv, fileName: host.backupName });
+    }
+    if (kind === "s3") {
+      const config2 = spec;
+      return () => connect4({ kv: host.kv, config: config2 });
+    }
+    const config = spec;
+    return () => connect3({ kv: host.kv, config });
+  }
+  async function inspectAndRoute(gen, t) {
+    const info = await withDeadline(host.engine.inspectTarget(t), deadlineMs, "The destination");
+    if (gen !== generation) return;
+    target = t;
+    m.set({ hasBackup: info.hasBackup, encrypted: info.encrypted });
+    if (!info.hasBackup) {
+      await attach(gen, "replace-remote", "started");
+      return;
+    }
+    if (info.encrypted) {
+      if (options.deferUnlock) {
+        await attach(gen, "replace-local", "resumed");
+        return;
+      }
+      m.set({ step: "password", busy: false, passwordError: false });
+      return;
+    }
+    routeAfterUnlock(gen);
+  }
+  function routeAfterUnlock(gen) {
+    if (gen !== generation) return;
+    if (options.hasLocalData?.() === true) {
+      m.set({ step: "conflict", busy: false });
+      return;
+    }
+    const plan = planFor(options.defaultResolution ?? "merge");
+    void attach(gen, plan.strategy, plan.outcome);
+  }
+  async function attach(gen, strategy, outcome, wipe = false) {
+    if (gen !== generation || !target) return;
+    m.set({ busy: true });
+    try {
+      await withDeadline(
+        host.engine.attachTarget(target, { password, strategy, wipe }),
+        deadlineMs,
+        "The destination"
+      );
+      if (gen !== generation) return;
+      password = null;
+      m.set({ step: "connected", outcome, busy: false, error: null });
+    } catch (e) {
+      if (gen !== generation) return;
+      fail(e);
+    }
+  }
+  return {
+    get snapshot() {
+      return m.snapshot;
+    },
+    subscribe: m.subscribe,
+    choose(kind, variant = "create") {
+      const { step, busy } = m.snapshot;
+      if (busy || step !== "choose" && step !== "error") return;
+      const connector = connectorFor(kind, variant);
+      if (!connector) return;
+      if (kind === "webdav" && targets.webdav === true || kind === "s3" && targets.s3 === true) {
+        m.set({ step: "form", kind, error: null });
+        return;
+      }
+      const builtinCreate = targets.file === true || typeof targets.file === "object" && targets.file.create !== void 0 && typeof targets.file.create !== "function";
+      if (kind === "file" && variant === "create" && builtinCreate && !isSupported()) {
+        const gen2 = ++generation;
+        m.set({ step: "authorizing", kind, busy: true, error: null });
+        void host.engine.setManualFile().then(() => {
+          if (gen2 !== generation) return;
+          m.set({ step: "connected", outcome: "manual", busy: false });
+        }).catch((e) => {
+          if (gen2 !== generation) return;
+          fail(e);
+        });
+        return;
+      }
+      const gen = ++generation;
+      m.set({ step: "authorizing", kind, busy: true, error: null });
+      void connector().then(async (t) => {
+        if (gen !== generation) return;
+        if (!t) {
+          if (kind === "webdav" || kind === "s3") {
+            fail(
+              new SelfstoreError(
+                "TARGET_UNAVAILABLE",
+                "The server did not answer (address, credentials or CORS)."
+              )
+            );
+          } else {
+            backToChoose();
+          }
+          return;
+        }
+        await inspectAndRoute(gen, t);
+      }).catch((e) => {
+        if (gen !== generation) return;
+        fail(e);
+      });
+    },
+    submitWebdav(config) {
+      const { step, busy } = m.snapshot;
+      if (busy || step !== "form") return;
+      const gen = ++generation;
+      m.set({ step: "authorizing", busy: true });
+      void withDeadline(connect3({ kv: host.kv, config }), deadlineMs, "The WebDAV server").then(async (t) => {
+        if (gen !== generation) return;
+        if (!t) {
+          fail(
+            new SelfstoreError(
+              "TARGET_UNAVAILABLE",
+              "The WebDAV server did not answer (URL, credentials or CORS)."
+            )
+          );
+          return;
+        }
+        await inspectAndRoute(gen, t);
+      }).catch((e) => {
+        if (gen !== generation) return;
+        fail(e);
+      });
+    },
+    submitS3(config) {
+      const { step, busy } = m.snapshot;
+      if (busy || step !== "form") return;
+      const gen = ++generation;
+      m.set({ step: "authorizing", busy: true });
+      void withDeadline(connect4({ kv: host.kv, config }), deadlineMs, "The S3 endpoint").then(async (t) => {
+        if (gen !== generation) return;
+        if (!t) {
+          fail(
+            new SelfstoreError(
+              "TARGET_UNAVAILABLE",
+              "The S3 endpoint did not answer (endpoint, credentials or CORS)."
+            )
+          );
+          return;
+        }
+        await inspectAndRoute(gen, t);
+      }).catch((e) => {
+        if (gen !== generation) return;
+        fail(e);
+      });
+    },
+    submitPassword(pw) {
+      const { step, busy } = m.snapshot;
+      if (busy || step !== "password" || !target) return;
+      const gen = generation;
+      m.set({ busy: true, passwordError: false });
+      void (async () => {
+        try {
+          const blob = await withDeadline(target.load(), deadlineMs, "The destination");
+          if (gen !== generation) return;
+          if (!blob) {
+            throw new SelfstoreError("TARGET_UNAVAILABLE", "The backup could not be downloaded.");
+          }
+          await restore(blob).withPassword(pw).read();
+          if (gen !== generation) return;
+          password = pw;
+          m.set({ busy: false });
+          routeAfterUnlock(gen);
+        } catch (e) {
+          if (gen !== generation) return;
+          if (isSelfstoreError(e) && e.code === "DECRYPT_FAILED") {
+            m.set({ busy: false, passwordError: true });
+            return;
+          }
+          fail(e);
+        }
+      })();
+    },
+    overwrite() {
+      const { step, busy } = m.snapshot;
+      if (busy || step !== "password" || !target) return;
+      password = null;
+      void attach(generation, "replace-remote", "replaced", true);
+    },
+    resolveConflict(how) {
+      const { step, busy } = m.snapshot;
+      if (busy || step !== "conflict") return;
+      const plan = planFor(how);
+      void attach(generation, plan.strategy, plan.outcome);
+    },
+    cancel() {
+      if (m.snapshot.step === "connected") return;
+      backToChoose();
+    },
+    retry() {
+      if (m.snapshot.step !== "error") return;
+      backToChoose();
+    }
+  };
+}
+
+// src/flows/share.ts
+var DEFAULT_DEADLINE_MS2 = 3e4;
+function shareFlow(engine, options = {}) {
+  const deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS2;
+  const m = makeMachine({
+    links: [],
+    members: [],
+    busy: "refresh",
+    stale: false,
+    error: null,
+    canRemoveMembers: typeof engine.removeMember === "function",
+    canRevokeAll: typeof engine.revokeAll === "function"
+  });
+  function begin(op) {
+    if (m.snapshot.busy !== null && !(op === "refresh" && m.snapshot.busy === "refresh")) {
+      return false;
+    }
+    m.set({ busy: op });
+    return true;
+  }
+  async function doRefresh() {
+    try {
+      const { links, members } = await withDeadline(engine.list(), deadlineMs, "The share listing");
+      m.set({ links, members, busy: null, stale: false, error: null });
+    } catch (e) {
+      m.set({ busy: null, stale: true, error: toStoreError(e) });
+    }
+  }
+  const flow = {
+    get snapshot() {
+      return m.snapshot;
+    },
+    subscribe: m.subscribe,
+    async refresh() {
+      if (m.snapshot.busy !== null && m.snapshot.busy !== "refresh") return;
+      m.set({ busy: "refresh" });
+      await doRefresh();
+    },
+    async createLink(opts) {
+      if (!begin("create")) return null;
+      try {
+        const link = await withDeadline(engine.createLink(opts), deadlineMs, "Creating the link");
+        m.set({ links: [...m.snapshot.links, link], busy: null, error: null });
+        return link;
+      } catch (e) {
+        m.set({ busy: null, error: toStoreError(e) });
+        return null;
+      }
+    },
+    async revokeLink(id) {
+      if (!begin("revoke")) return false;
+      try {
+        await withDeadline(engine.revokeLink(id), deadlineMs, "Revoking the link");
+        m.set({ links: m.snapshot.links.filter((l) => l.id !== id), busy: null, error: null });
+        return true;
+      } catch (e) {
+        m.set({ busy: null, error: toStoreError(e) });
+        return false;
+      }
+    },
+    async removeMember(id) {
+      const remove = engine.removeMember?.bind(engine);
+      if (!remove) {
+        throw new TypeError("shareFlow: this engine does not manage members (no removeMember).");
+      }
+      const row = m.snapshot.members.find((mb) => mb.id === id);
+      if (row?.self) {
+        throw new TypeError(
+          "shareFlow: refusing to remove yourself - leaving a share is its own journey, not a row action."
+        );
+      }
+      if (!begin("remove")) return false;
+      try {
+        await withDeadline(remove(id), deadlineMs, "Removing the member");
+        m.set({
+          members: m.snapshot.members.filter((mb) => mb.id !== id),
+          busy: null,
+          error: null
+        });
+        return true;
+      } catch (e) {
+        m.set({ busy: null, error: toStoreError(e) });
+        return false;
+      }
+    },
+    async revokeAll() {
+      const revoke = engine.revokeAll?.bind(engine);
+      if (!revoke) {
+        throw new TypeError("shareFlow: this engine does not end the share (no revokeAll).");
+      }
+      if (!begin("revoke-all")) return false;
+      try {
+        await withDeadline(revoke(), deadlineMs, "Ending the share");
+        m.set({ links: [], members: [], busy: null, error: null });
+        return true;
+      } catch (e) {
+        m.set({ busy: null, error: toStoreError(e) });
+        return false;
+      }
+    }
+  };
+  void doRefresh();
+  return flow;
+}
+
+// src/flows/join.ts
+var DEFAULT_DEADLINE_MS3 = 3e4;
+function joinFlow(link, engine, options = {}) {
+  const deadlineMs = options.deadlineMs ?? DEFAULT_DEADLINE_MS3;
+  const m = makeMachine({
+    link,
+    step: "previewing",
+    preview: null,
+    canSwitchAccount: typeof engine.switchAccount === "function",
+    busy: true,
+    error: null
+  });
+  let generation = 0;
+  function preview() {
+    const gen = ++generation;
+    m.set({ step: "previewing", busy: true, error: null });
+    void withDeadline(engine.preview(link), deadlineMs, "The invitation").then((p) => {
+      if (gen !== generation) return;
+      m.set({ step: "ready", preview: p, busy: false });
+    }).catch((e) => {
+      if (gen !== generation) return;
+      m.set({ step: "error", busy: false, error: toStoreError(e) });
+    });
+  }
+  preview();
+  return {
+    get snapshot() {
+      return m.snapshot;
+    },
+    subscribe: m.subscribe,
+    accept() {
+      const { step, busy } = m.snapshot;
+      if (busy || step !== "ready") return;
+      const gen = ++generation;
+      m.set({ step: "joining", busy: true, error: null });
+      void withDeadline(engine.join(link), deadlineMs, "Joining").then((outcome) => {
+        if (gen !== generation) return;
+        if (outcome === null) {
+          m.set({ step: "ready", busy: false });
+          return;
+        }
+        m.set({ step: outcome, busy: false });
+      }).catch((e) => {
+        if (gen !== generation) return;
+        m.set({ step: "error", busy: false, error: toStoreError(e) });
+      });
+    },
+    switchAccount() {
+      const switcher = engine.switchAccount?.bind(engine);
+      if (!switcher) return;
+      const { step, busy } = m.snapshot;
+      if (busy || step !== "ready" && step !== "no-invite" && step !== "error") return;
+      const gen = ++generation;
+      m.set({ busy: true, error: null });
+      void switcher().then(() => {
+        if (gen !== generation) return;
+        preview();
+      }).catch((e) => {
+        if (gen !== generation) return;
+        m.set({ step: "error", busy: false, error: toStoreError(e) });
+      });
+    },
+    retry() {
+      if (m.snapshot.step !== "error") return;
+      preview();
+    }
+  };
+}
+
+export { connectFlow, joinFlow, shareFlow };
+//# sourceMappingURL=chunk-ATUPHVLG.js.map
+//# sourceMappingURL=chunk-ATUPHVLG.js.map