selfstore 1.0.0

package/dist/groups.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/persistence/identity.ts"],"names":[],"mappings":"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","file":"groups.js","sourcesContent":["// At-rest storage for a member identity (passwordless groups). Private keys\n// are sealed under a non-extractable device key in the same kv - defeats disk\n// forensics and partial exfiltration, not code running in the origin or a\n// copy of the whole profile (THREAT-MODEL.md).\n//\n// The opt-in passphrase lock reseals the identity under Argon2id(passphrase)\n// instead, closing the profile-copy gap at the cost of an unlock prompt. The\n// vault keeps no unlocked session state: unlock() returns the identity, the\n// caller holds it in memory, and at rest it stays sealed. A bare envelope\n// keeps meaning device mode, so pre-lock vaults load unchanged.\n//\n// The identity is one person's; move it between their devices over a trusted\n// channel (QR shown locally, encrypted note) - never through the group's\n// shared storage.\n\nimport { seal, unseal, isEnvelope, newDeviceKey, type EncEnvelope } from './cache-crypto';\nimport type { KV } from './cache';\nimport { generateIdentity, type GroupIdentity } from '../selfstore/group';\nimport { deriveKey, freshKdfParams, assertKdfBounds } from '../selfstore/crypto';\nimport type { KdfParams } from '../selfstore/types';\nimport { SelfstoreError } from '../selfstore/errors';\n\nconst VAULT_KEY = 'groupVaultKey';\nconst IDENTITY_KEY = 'groupIdentity';\n\nconst utf8 = { enc: new TextEncoder(), dec: new TextDecoder() };\n\n// Local kv bookkeeping only - not part of the interchange format (SPEC.md).\ninterface VaultLock {\n\tselfstoreVaultLock: 1;\n\tkdf: KdfParams;\n\tenvelope: EncEnvelope;\n}\n\nfunction isVaultLock(v: unknown): v is VaultLock {\n\treturn (\n\t\ttypeof v === 'object' && v !== null && (v as { selfstoreVaultLock?: unknown }).selfstoreVaultLock === 1\n\t);\n}\n\nconst encode = (identity: GroupIdentity): Uint8Array => utf8.enc.encode(JSON.stringify(identity));\nconst decode = (bytes: Uint8Array): GroupIdentity =>\n\tJSON.parse(utf8.dec.decode(bytes)) as GroupIdentity;\n\nexport interface IdentityVault {\n\t/** The stored identity, or null when none exists yet. On a protected\n\t *  vault this throws PASSWORD_REQUIRED rather than returning null - a\n\t *  locked identity exists, and null would invite loadOrCreate to mint a\n\t *  second one over it. */\n\tload(): Promise<GroupIdentity | null>;\n\t/** Seal and store an identity, overwriting any previous one. Throws\n\t *  PASSWORD_REQUIRED on a protected vault: a locked identity is never\n\t *  silently replaced (unprotect() or clear() first). */\n\tsave(identity: GroupIdentity): Promise<void>;\n\t/** load(), creating and storing a fresh identity when absent. Same\n\t *  PASSWORD_REQUIRED rule as load(). */\n\tloadOrCreate(): Promise<GroupIdentity>;\n\t/** Forget the identity on this device. Allowed even when protected -\n\t *  forgetting leaks nothing, and it is the honest lost-passphrase escape\n\t *  hatch (re-import from another device, or get re-invited). */\n\tclear(): Promise<void>;\n\tisProtected(): Promise<boolean>;\n\t/** Decrypt a protected vault and return the identity. Stateless: the\n\t *  caller holds it in memory, the stored value stays sealed. Wrong\n\t *  passphrase and tampered blob are one DECRYPT_FAILED; hostile KDF\n\t *  params are refused before any derivation. */\n\tunlock(passphrase: string): Promise<GroupIdentity>;\n\t/** Reseal the identity under Argon2id(passphrase); an empty vault gets a\n\t *  fresh identity, created-and-protected in one step. Changing the\n\t *  passphrase is unprotect(old) then protect(new) - an already-protected\n\t *  vault throws PASSWORD_REQUIRED, never a silent rekey. */\n\tprotect(passphrase: string): Promise<void>;\n\t/** Unlock with `passphrase`, then reseal under the device key. A wrong\n\t *  passphrase throws DECRYPT_FAILED and leaves the vault untouched. */\n\tunprotect(passphrase: string): Promise<void>;\n}\n\n/** An identity vault over the app's kv (e.g. `indexedDbCache(app).kv`). */\nexport function identityVault(kv: KV): IdentityVault {\n\tasync function vaultKey(): Promise<CryptoKey> {\n\t\tconst existing = await kv.get<CryptoKey>(VAULT_KEY);\n\t\tif (existing) return existing;\n\t\tconst fresh = await newDeviceKey();\n\t\tawait kv.set(VAULT_KEY, fresh);\n\t\treturn fresh;\n\t}\n\n\t/** Device mode's write path: a bare envelope under the device key. */\n\tasync function sealDevice(identity: GroupIdentity): Promise<void> {\n\t\tawait kv.set(IDENTITY_KEY, await seal(await vaultKey(), encode(identity)));\n\t}\n\n\tasync function load(): Promise<GroupIdentity | null> {\n\t\tconst stored = await kv.get(IDENTITY_KEY);\n\t\tif (isVaultLock(stored)) {\n\t\t\tthrow new SelfstoreError(\n\t\t\t\t'PASSWORD_REQUIRED',\n\t\t\t\t'The identity vault is passphrase-protected. Call unlock(passphrase) - ' +\n\t\t\t\t\t'load()/loadOrCreate() never open or replace a locked identity.'\n\t\t\t);\n\t\t}\n\t\tif (!isEnvelope(stored)) return null;\n\t\treturn decode(await unseal(await vaultKey(), stored));\n\t}\n\n\tasync function save(identity: GroupIdentity): Promise<void> {\n\t\tif (isVaultLock(await kv.get(IDENTITY_KEY))) {\n\t\t\tthrow new SelfstoreError(\n\t\t\t\t'PASSWORD_REQUIRED',\n\t\t\t\t'The identity vault is passphrase-protected; save() never overwrites a locked ' +\n\t\t\t\t\t'identity. unprotect(passphrase) first, or clear() to forget it.'\n\t\t\t);\n\t\t}\n\t\tawait sealDevice(identity);\n\t}\n\n\tasync function unlock(passphrase: string): Promise<GroupIdentity> {\n\t\tconst stored = await kv.get(IDENTITY_KEY);\n\t\tif (!isVaultLock(stored)) {\n\t\t\tthrow new TypeError('unlock(): the vault is not passphrase-protected (check isProtected()).');\n\t\t}\n\t\tif (!stored.kdf || !isEnvelope(stored.envelope)) {\n\t\t\tthrow new SelfstoreError('BAD_FORMAT', 'Missing or malformed vault lock parameters.');\n\t\t}\n\t\t// Same read-side ceiling as backup decrypts: a tampered kv must not make\n\t\t// unlock allocate gigabytes (memory-hard bomb) before any passphrase check.\n\t\tassertKdfBounds(stored.kdf);\n\t\ttry {\n\t\t\treturn decode(await unseal(await deriveKey(passphrase, stored.kdf), stored.envelope));\n\t\t} catch (e) {\n\t\t\tif (e instanceof SelfstoreError) throw e;\n\t\t\tthrow new SelfstoreError('DECRYPT_FAILED', 'Wrong passphrase or tampered identity vault.');\n\t\t}\n\t}\n\n\tasync function protect(passphrase: string): Promise<void> {\n\t\tif (!passphrase) throw new TypeError('protect(): a non-empty passphrase is required.');\n\t\tconst stored = await kv.get(IDENTITY_KEY);\n\t\tif (isVaultLock(stored)) {\n\t\t\tthrow new SelfstoreError(\n\t\t\t\t'PASSWORD_REQUIRED',\n\t\t\t\t'The identity vault is already passphrase-protected. To change the passphrase: ' +\n\t\t\t\t\t'unprotect(oldPassphrase), then protect(newPassphrase).'\n\t\t\t);\n\t\t}\n\t\tconst identity = isEnvelope(stored)\n\t\t\t? decode(await unseal(await vaultKey(), stored)) // reseal the existing identity\n\t\t\t: await generateIdentity(); // empty vault: create-and-protect in one step\n\t\tconst kdf = freshKdfParams();\n\t\tconst envelope = await seal(await deriveKey(passphrase, kdf), encode(identity));\n\t\tawait kv.set(IDENTITY_KEY, { selfstoreVaultLock: 1, kdf, envelope } satisfies VaultLock);\n\t}\n\n\treturn {\n\t\tload,\n\t\tsave,\n\t\tunlock,\n\t\tprotect,\n\t\tasync loadOrCreate(): Promise<GroupIdentity> {\n\t\t\tconst existing = await load(); // PASSWORD_REQUIRED when protected: never mint over a lock\n\t\t\tif (existing) return existing;\n\t\t\tconst fresh = await generateIdentity();\n\t\t\tawait save(fresh);\n\t\t\treturn fresh;\n\t\t},\n\t\tasync clear(): Promise<void> {\n\t\t\tawait kv.del(IDENTITY_KEY);\n\t\t},\n\t\tasync isProtected(): Promise<boolean> {\n\t\t\treturn isVaultLock(await kv.get(IDENTITY_KEY));\n\t\t},\n\t\tasync unprotect(passphrase: string): Promise<void> {\n\t\t\t// unlock() enforces \"protected\" and the passphrase; only then rewrite.\n\t\t\tawait sealDevice(await unlock(passphrase));\n\t\t}\n\t};\n}\n"]}

package/dist/households.d.ts

@@ -0,0 +1,214 @@
+import { B as BackupTarget, g as PeerSource, L as LocalStore } from './store-ChIGEOph.js';
+import { K as KV } from './cache-De5_sALA.js';
+import './sync.js';
+
+/** Why a code was refused. `malformed` covers bad transport, wrong structure or
+ *  a code decoded as the wrong kind of payload; `unsupported-version` is a
+ *  numeric `v` this build does not understand. */
+type HouseholdCodeErrorCode = 'malformed' | 'unsupported-version';
+/** The single typed error this module throws, so callers branch on `code`
+ *  instead of parsing messages. A decoder that throws never returns a partially
+ *  parsed object - it fails whole. */
+declare class HouseholdCodeError extends Error {
+    readonly code: HouseholdCodeErrorCode;
+    constructor(code: HouseholdCodeErrorCode, message: string);
+}
+/** Where a member published their encrypted copy. A discriminated union on
+ *  `provider` so a future transport (WebDAV, ...) slots in beside Drive without
+ *  changing the payload shapes. Today: Drive only. */
+type CopyLink = DriveCopyLink;
+/** A copy hosted on the owner's Google Drive. `fileId` is the Drive file id (a
+ *  public-link file, ciphertext under K); the owner fields are a cosmetic "on
+ *  X's Drive" hint, both optional. */
+interface DriveCopyLink {
+    provider: 'drive';
+    fileId: string;
+    ownerEmail?: string;
+    ownerName?: string;
+}
+/** The bulletin's control record (rides one reserved collection inside the
+ *  K-encrypted bulletin): where members announce their copy (`mailboxId`, a
+ *  secret only K-holders can read) and the roster of every known copy (the
+ *  admin's own first). */
+interface SharePayload {
+    v: 1;
+    mailboxId: string;
+    roster: CopyLink[];
+}
+/** Member -> admin, through the announce mailbox: "here is my copy, fold it".
+ *  No identity, no signature: knowing the mailboxId (which lives inside the
+ *  K-encrypted bulletin) already proves the sender holds K. */
+interface AnnouncePayload {
+    v: 1;
+    copy: CopyLink;
+}
+/** A short, url-safe, random id (9 bytes -> 12 base64url chars) from WebCrypto -
+ *  used for the announce mailbox id. This repo bans Math.random; getRandomValues
+ *  is the sanctioned entropy source and exists in every browser and Node 20+. */
+declare function randomId(): string;
+/** Rebuild a CopyLink field by field, so a decoded link carries exactly the
+ *  known keys (no smuggled extras) and every present field has the right type. */
+declare function toCopyLink(v: unknown): CopyLink;
+/** Every entry of a roster array validated as a CopyLink, de-duplicated by
+ *  fileId (first occurrence wins). An empty roster is structurally valid.
+ *  Exported for the backend, which revalidates the roster it re-publishes. */
+declare function toRoster(v: unknown): CopyLink[];
+declare function encodeShare(payload: SharePayload): string;
+declare function decodeShare(code: string): SharePayload;
+declare function encodeAnnounce(payload: AnnouncePayload): string;
+declare function decodeAnnounce(code: string): AnnouncePayload;
+
+/** What the bulletin holds once opened: the read-only projection (scrubbed
+ *  collections, empty when the share is revoked) and the control record. */
+interface IncomingShare {
+    projection: Record<string, unknown[]>;
+    share: SharePayload;
+}
+/**
+ * The sharing transport, the sole Drive/relay/mailbox-specific seam. A test
+ * provides an in-memory fake; the host app provides a real one (e.g. Drive).
+ * Everything here carries only public data - file ids and the roster.
+ */
+interface ShareBackend {
+    /** Create this member's dedicated copy file (link-readable, empty until the
+     *  mirror publishes into it) and return the link others read it through.
+     *  `existingFileId` reuses a known copy on restore instead of minting a
+     *  second file. */
+    createCopy(existingFileId?: string, shareLabel?: string): Promise<CopyLink>;
+    /** A write-capable target over a copy file, for the store MIRROR. Never
+     *  adopted as the store's own target - the store's own connection stays what
+     *  it is. */
+    copyTarget(fileId: string): BackupTarget;
+    /** Teardown: make a copy file private and delete it (best-effort). Only
+     *  ever called on MY own copy - the others' files are theirs. */
+    dropCopy(fileId: string): Promise<void>;
+    /** Admin: write (or rewrite) the bulletin - the encrypted file the invitation
+     *  link points at, holding the read-only projection plus the control record.
+     *  Idempotent per group; returns where it lives (the link's fileId + key). */
+    publishBulletin(key: string, payload: SharePayload): Promise<{
+        fileId: string;
+        key: string;
+    }>;
+    /** Admin: stop the invitation - the bulletin drops its projection and roster,
+     *  so the link no longer previews or admits. */
+    revokeBulletin(): Promise<void>;
+    /** Open an invitation link's bulletin (through the relay) and STASH it for the
+     *  join, returning its content for the read-only preview. Null when the link
+     *  is dead or the key wrong. */
+    openIncoming(fileId: string, key: string): Promise<IncomingShare | null>;
+    /** The invitation opened by openIncoming and stashed for the join, or null. */
+    takeStashedIncoming(): Promise<{
+        key: string;
+        fileId: string;
+        content: IncomingShare;
+    } | null>;
+    /** Re-read a joined share's bulletin (member): the freshest roster. The
+     *  engine passes the invitation capability it joined through, so every
+     *  membership rereads ITS bulletin. Null when unreachable or revoked. */
+    rereadJoined(fileId: string, key: string): Promise<SharePayload | null>;
+    /** Member: announce my copy to the group's mailbox so the admin folds it. */
+    announce(mailboxId: string, copy: CopyLink): Promise<void>;
+    /** Admin: drain the announce mailbox - the copies members published. */
+    takeAnnounces(mailboxId: string): Promise<CopyLink[]>;
+    /** A read-only PeerSource over another member's published copy. */
+    peerSource(link: CopyLink): PeerSource;
+}
+/** The default KV key the group lives under. Exported so a caller can wipe
+ *  it. Hosts with a pre-existing record under another key pass `storageKey`. */
+declare const HOUSEHOLD_GROUP_KEY = "selfstore:households:group:v1";
+/** One membership, as the UI lists them: which silo carries it and whose
+ *  share it is. */
+interface MembershipInfo {
+    /** The wallet file this membership is bound to (null = unbound legacy). */
+    walletFileId: string | null;
+    isAdmin: boolean;
+    /** My published copy's file id for this share. */
+    selfFileId: string;
+    /** Who shares it with me (the admin's roster label); null for my own share. */
+    sharedBy: string | null;
+    memberCount: number;
+}
+/** The reactive-friendly snapshot the UI reads (hosts wrap it in their own
+ *  reactivity - a Svelte rune, a React store, anything). The singular fields
+ *  describe the PRIMARY membership (the admin one when it exists, else the
+ *  first); `memberships` lists them all. */
+interface HouseholdGroupState {
+    /** A share exists on this device (admin or member). */
+    active: boolean;
+    isAdmin: boolean;
+    /** How many copies are in the roster (this device included). */
+    memberCount: number;
+    /** The roster's cosmetic owner labels, for a "who has access" list. */
+    members: {
+        fileId: string;
+        label: string;
+    }[];
+    /** My own copy's file id, so the UI can list everyone ELSE. */
+    selfFileId: string | null;
+    /** The wallet file the share is bound to, or null when unbound. The host
+     *  compares it to its own attached-file id to render "this silo carries the
+     *  share" and to gate its own publications the same way the engine does. */
+    walletFileId: string | null;
+    /** Admin: the live invitation's capability, so the panel can re-show the
+     *  link without republishing anything. */
+    inviteCapability: {
+        fileId: string;
+        key: string;
+    } | null;
+    /** Every membership on this device, admin and joined alike. */
+    memberships: MembershipInfo[];
+}
+interface HouseholdGroup {
+    readonly state: HouseholdGroupState;
+    /** Admin: start sharing. The member's own file is untouched - a dedicated
+     *  copy is created and mirrored under a fresh K, and the invitation
+     *  bulletin is published. Refused on a password-protected store: remove
+     *  the password to share, or keep it and do not. */
+    startShare(): Promise<{
+        fileId: string;
+        key: string;
+    }>;
+    /** Admin: re-show (and refresh) the standing invitation link. Idempotent. */
+    invite(): Promise<{
+        fileId: string;
+        key: string;
+    }>;
+    /** /share: open an invitation link's bulletin and remember it for the join. */
+    openIncoming(fileId: string, key: string): Promise<IncomingShare | null>;
+    /** Member: after openIncoming + own store connected, join read-write now.
+     *  Your own file stays yours: a dedicated copy is created and mirrored
+     *  under K, the others' copies attach as keyed peers (the next converge
+     *  folds the shared data into your own file), and my copy is announced.
+     *  Same honest rule as startShare: a password-protected store refuses.
+     *  With a `wallet` getter, one membership per share: joining another share
+     *  ADDS a membership (bound to the attached silo), and a re-join over the
+     *  same silo replaces its stale one. Without the getter, the historical
+     *  single-membership rule holds ('mismatch' on a different share). */
+    join(): Promise<'joined' | 'no-invite' | 'mismatch' | 'error'>;
+    /** Both: one convergence round (admin folds new announces + rebroadcasts;
+     *  everyone re-arms mirror/peers). Called on every converge. */
+    syncGroup(): Promise<void>;
+    /** End ONE share on this device - and, for the admin, this is the real
+     *  revocation (bearer link: the lock changes for everyone). The bulletin
+     *  is revoked, my copy file is dropped, mirror and peers detach. The
+     *  member's own file is untouched: everyone keeps what already converged into
+     *  their own file - the local-first reality. Re-sharing mints a fresh K
+     *  and a fresh link for whoever should stay. `walletFileId` names WHICH
+     *  membership; omitted, the primary one (admin first) goes. */
+    leave(walletFileId?: string | null): Promise<void>;
+    /** On boot: re-arm the mirror and peers of the current share. */
+    restore(): Promise<void>;
+}
+declare function createHouseholdGroup(deps: {
+    store: LocalStore;
+    kv: KV;
+    backend: ShareBackend;
+    /** KV key the group record lives under. Default HOUSEHOLD_GROUP_KEY. */
+    storageKey?: string;
+    /** The currently attached wallet file id, for multi-backup hosts. When
+     *  given, start/join bind the share to that file and the engine goes
+     *  dormant whenever another one is attached. Omit on single-wallet hosts. */
+    wallet?: () => Promise<string | null>;
+}): HouseholdGroup;
+
+export { type AnnouncePayload, type CopyLink, type DriveCopyLink, HOUSEHOLD_GROUP_KEY, HouseholdCodeError, type HouseholdCodeErrorCode, type HouseholdGroup, type HouseholdGroupState, type IncomingShare, type ShareBackend, type SharePayload, createHouseholdGroup, decodeAnnounce, decodeShare, encodeAnnounce, encodeShare, randomId, toCopyLink, toRoster };

package/dist/households.js

@@ -0,0 +1,410 @@
+// src/households/codec.ts
+var HouseholdCodeError = class _HouseholdCodeError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "HouseholdCodeError";
+    this.code = code;
+    Object.setPrototypeOf(this, _HouseholdCodeError.prototype);
+  }
+};
+var malformed = (message) => new HouseholdCodeError("malformed", message);
+var utf8Encoder = new TextEncoder();
+var utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+function bytesToBinary(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) out += String.fromCharCode(bytes[i]);
+  return out;
+}
+function binaryToBytes(binary) {
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+function bytesToBase64url(bytes) {
+  return btoa(bytesToBinary(bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64urlEncode(text) {
+  return bytesToBase64url(utf8Encoder.encode(text));
+}
+function base64urlDecode(code) {
+  const b64 = code.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+  return utf8Decoder.decode(binaryToBytes(atob(padded)));
+}
+function randomId() {
+  const bytes = new Uint8Array(9);
+  crypto.getRandomValues(bytes);
+  return bytesToBase64url(bytes);
+}
+function isRecord(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isString(v) {
+  return typeof v === "string";
+}
+function requireV1(v) {
+  if (v === 1) return;
+  if (typeof v === "number") {
+    throw new HouseholdCodeError("unsupported-version", `payload version ${v} is not supported (expected 1)`);
+  }
+  throw malformed("missing or non-numeric version field");
+}
+function decodeJson(code) {
+  if (typeof code !== "string" || code.length === 0) throw malformed("code must be a non-empty string");
+  let json;
+  try {
+    json = base64urlDecode(code);
+  } catch {
+    throw malformed("code is not valid base64url");
+  }
+  try {
+    return JSON.parse(json);
+  } catch {
+    throw malformed("code payload is not valid JSON");
+  }
+}
+function toCopyLink(v) {
+  if (!isRecord(v)) throw malformed("copy link is not an object");
+  if (v.provider === "drive") {
+    if (!isString(v.fileId)) throw malformed("drive copy link needs a string fileId");
+    if (v.ownerEmail !== void 0 && !isString(v.ownerEmail)) throw malformed("copy link ownerEmail must be a string");
+    if (v.ownerName !== void 0 && !isString(v.ownerName)) throw malformed("copy link ownerName must be a string");
+    const link = { provider: "drive", fileId: v.fileId };
+    if (isString(v.ownerEmail)) link.ownerEmail = v.ownerEmail;
+    if (isString(v.ownerName)) link.ownerName = v.ownerName;
+    return link;
+  }
+  throw malformed(`unknown copy-link provider ${JSON.stringify(v.provider)}`);
+}
+function toRoster(v) {
+  if (!Array.isArray(v)) throw malformed("roster is not an array");
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const entry of v) {
+    const link = toCopyLink(entry);
+    if (seen.has(link.fileId)) continue;
+    seen.add(link.fileId);
+    out.push(link);
+  }
+  return out;
+}
+function encodeShare(payload) {
+  return base64urlEncode(JSON.stringify(payload));
+}
+function decodeShare(code) {
+  const raw = decodeJson(code);
+  if (!isRecord(raw)) throw malformed("share payload is not an object");
+  requireV1(raw.v);
+  if (!isString(raw.mailboxId)) throw malformed("share payload needs a string mailboxId");
+  return { v: 1, mailboxId: raw.mailboxId, roster: toRoster(raw.roster) };
+}
+function encodeAnnounce(payload) {
+  return base64urlEncode(JSON.stringify(payload));
+}
+function decodeAnnounce(code) {
+  const raw = decodeJson(code);
+  if (!isRecord(raw)) throw malformed("announce is not an object");
+  requireV1(raw.v);
+  return { v: 1, copy: toCopyLink(raw.copy) };
+}
+
+// src/households/group.ts
+var HOUSEHOLD_GROUP_KEY = "selfstore:households:group:v1";
+var mirrorId = (group) => `household-copy:${group.myCopy.fileId}`;
+function createHouseholdGroup(deps) {
+  const { store, kv, backend, wallet } = deps;
+  const storageKey = deps.storageKey ?? HOUSEHOLD_GROUP_KEY;
+  let groups = null;
+  let loaded = false;
+  const rosterMisses = /* @__PURE__ */ new Map();
+  async function load() {
+    if (!loaded) {
+      const raw = await kv.get(storageKey);
+      if (!raw) groups = [];
+      else if (raw.v === 2) groups = raw.groups;
+      else groups = [raw];
+      loaded = true;
+    }
+    return groups;
+  }
+  async function persist() {
+    loaded = true;
+    if (!groups || groups.length === 0) {
+      groups = groups ?? [];
+      await kv.del(storageKey);
+      return;
+    }
+    await kv.set(storageKey, { v: 2, groups });
+  }
+  const adminGroup = (list) => list.find((g) => g.role === "admin") ?? null;
+  const primaryGroup = (list) => adminGroup(list) ?? list[0] ?? null;
+  const sharedByOf = (g) => g.role === "member" ? g.roster[0]?.ownerEmail ?? g.roster[0]?.ownerName ?? null : null;
+  function randomKey() {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    let s = "";
+    for (const b of bytes) s += String.fromCharCode(b);
+    return btoa(s).replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+  }
+  function refuseProtected() {
+    if (store.state.encrypted) {
+      throw new Error(
+        "household-group: a password-protected store cannot be shared - remove the password first"
+      );
+    }
+  }
+  async function inScope(group) {
+    if (!group.walletFileId || !wallet) return true;
+    return await wallet() === group.walletFileId;
+  }
+  function disarm(group) {
+    store.detachMirror(mirrorId(group));
+    for (const link of group.roster) {
+      if (link.fileId !== group.myCopy.fileId) store.detachPeer(link.fileId);
+    }
+  }
+  function ensureMirror(group) {
+    const id = mirrorId(group);
+    if (store.state.mirrors.some((m) => m.id === id)) return;
+    store.attachMirror(backend.copyTarget(group.myCopy.fileId), {
+      password: group.key,
+      id
+    });
+  }
+  function attachPeers(group) {
+    const already = new Set(store.state.peers.map((p) => p.id));
+    for (const link of group.roster) {
+      if (link.fileId === group.myCopy.fileId) continue;
+      if (already.has(link.fileId)) continue;
+      store.attachPeer(backend.peerSource(link), { id: link.fileId, password: group.key });
+    }
+  }
+  function mergeRoster(roster, incoming, selfFileId) {
+    const byId = new Map(roster.map((l) => [l.fileId, l]));
+    for (const link of incoming) {
+      if (link.fileId === selfFileId) continue;
+      byId.set(link.fileId, link);
+    }
+    return [...byId.values()];
+  }
+  return {
+    get state() {
+      const list = groups ?? [];
+      const memberships = list.map((g) => ({
+        walletFileId: g.walletFileId ?? null,
+        isAdmin: g.role === "admin",
+        selfFileId: g.myCopy.fileId,
+        sharedBy: sharedByOf(g),
+        memberCount: g.roster.length
+      }));
+      const group = primaryGroup(list);
+      if (!group) {
+        return {
+          active: false,
+          isAdmin: false,
+          memberCount: 0,
+          members: [],
+          selfFileId: null,
+          walletFileId: null,
+          inviteCapability: null,
+          memberships
+        };
+      }
+      return {
+        active: true,
+        isAdmin: group.role === "admin",
+        memberCount: group.roster.length,
+        members: group.roster.map((l) => ({
+          fileId: l.fileId,
+          label: l.ownerEmail ?? l.ownerName ?? l.fileId.slice(0, 8)
+        })),
+        selfFileId: group.myCopy.fileId,
+        walletFileId: group.walletFileId ?? null,
+        inviteCapability: group.role === "admin" && group.live === true && group.bulletin ? group.bulletin : null,
+        memberships
+      };
+    },
+    async startShare() {
+      const list = await load();
+      if (adminGroup(list)) {
+        throw new Error("household-group: a share already exists on this device");
+      }
+      refuseProtected();
+      const key = randomKey();
+      const mailboxId = randomId();
+      const walletFileId = await wallet?.() ?? void 0;
+      const link = await backend.createCopy();
+      const roster = [link];
+      const group = {
+        role: "admin",
+        walletFileId,
+        key,
+        mailboxId,
+        roster,
+        myCopy: link,
+        live: false
+      };
+      list.push(group);
+      await persist();
+      ensureMirror(group);
+      const where = await backend.publishBulletin(key, { v: 1, mailboxId, roster });
+      group.bulletin = where;
+      group.live = true;
+      await persist();
+      return where;
+    },
+    async invite() {
+      const group = adminGroup(await load());
+      if (!group) {
+        throw new Error("household-group: invite() requires an admin share");
+      }
+      const where = await backend.publishBulletin(group.key, {
+        v: 1,
+        mailboxId: group.mailboxId,
+        roster: group.roster
+      });
+      group.bulletin = where;
+      group.live = true;
+      await persist();
+      return where;
+    },
+    async openIncoming(fileId, key) {
+      return backend.openIncoming(fileId, key);
+    },
+    async join() {
+      const list = await load();
+      const incoming = await backend.takeStashedIncoming();
+      if (!incoming) return list.length > 0 ? "joined" : "no-invite";
+      const { key, fileId, content } = incoming;
+      if (list.some((g) => g.mailboxId === content.share.mailboxId)) return "joined";
+      if (!wallet && list.length > 0) return "mismatch";
+      refuseProtected();
+      const walletFileId = await wallet?.() ?? void 0;
+      if (walletFileId) {
+        const stale = list.find((g) => g.walletFileId === walletFileId);
+        if (stale) {
+          disarm(stale);
+          await backend.dropCopy(stale.myCopy.fileId).catch(() => void 0);
+          groups = list.filter((g) => g !== stale);
+        }
+      }
+      const link = await backend.createCopy(void 0, content.share.roster[0]?.ownerEmail);
+      const roster = mergeRoster(content.share.roster, [link], "");
+      const group = {
+        role: "member",
+        walletFileId,
+        key,
+        mailboxId: content.share.mailboxId,
+        roster,
+        myCopy: link,
+        // The invitation capability, kept so THIS membership rereads ITS
+        // bulletin on converge (roster removals, lost-announce self-heal).
+        bulletin: { fileId, key }
+      };
+      groups.push(group);
+      await persist();
+      ensureMirror(group);
+      attachPeers(group);
+      await backend.announce(content.share.mailboxId, link).catch(() => void 0);
+      return "joined";
+    },
+    async syncGroup() {
+      const list = await load();
+      for (const group of list) {
+        if (store.state.encrypted) {
+          store.detachMirror(mirrorId(group));
+          continue;
+        }
+        if (!await inScope(group)) {
+          disarm(group);
+          continue;
+        }
+        ensureMirror(group);
+        if (group.role === "admin") {
+          const announced = await backend.takeAnnounces(group.mailboxId);
+          const roster = mergeRoster(group.roster, announced, group.myCopy.fileId);
+          const grew = roster.length !== group.roster.length;
+          const needed = group.needsRebroadcast === true;
+          group.roster = roster;
+          await persist();
+          attachPeers(group);
+          if ((grew || needed) && group.live === true) {
+            try {
+              const where = await backend.publishBulletin(group.key, {
+                v: 1,
+                mailboxId: group.mailboxId,
+                roster
+              });
+              group.bulletin = where;
+              group.needsRebroadcast = void 0;
+            } catch {
+              group.needsRebroadcast = true;
+            }
+            await persist();
+          }
+        } else {
+          const share = group.bulletin ? await backend.rereadJoined(group.bulletin.fileId, group.bulletin.key) : null;
+          if (share) {
+            const byId = new Map(share.roster.map((l) => [l.fileId, l]));
+            if (!byId.has(group.myCopy.fileId)) {
+              byId.set(group.myCopy.fileId, group.myCopy);
+              await backend.announce(group.mailboxId, group.myCopy).catch(() => void 0);
+            }
+            for (const link of group.roster) {
+              if (link.fileId === group.myCopy.fileId) continue;
+              const missKey = `${group.mailboxId}:${link.fileId}`;
+              if (byId.has(link.fileId)) {
+                rosterMisses.delete(missKey);
+                continue;
+              }
+              const misses = (rosterMisses.get(missKey) ?? 0) + 1;
+              if (misses >= 2) {
+                rosterMisses.delete(missKey);
+                store.detachPeer(link.fileId);
+              } else {
+                rosterMisses.set(missKey, misses);
+                byId.set(link.fileId, link);
+              }
+            }
+            group.roster = [...byId.values()];
+            await persist();
+            attachPeers(group);
+          } else {
+            attachPeers(group);
+          }
+        }
+      }
+    },
+    async leave(walletFileId) {
+      const list = await load();
+      const group = walletFileId != null ? list.find((g) => g.walletFileId === walletFileId) ?? null : primaryGroup(list);
+      if (!group) return;
+      disarm(group);
+      if (group.role === "admin") {
+        try {
+          await backend.revokeBulletin();
+        } catch {
+        }
+      }
+      await backend.dropCopy(group.myCopy.fileId).catch(() => void 0);
+      groups = list.filter((g) => g !== group);
+      for (const k of [...rosterMisses.keys()]) {
+        if (k.startsWith(`${group.mailboxId}:`)) rosterMisses.delete(k);
+      }
+      await persist();
+    },
+    async restore() {
+      const list = await load();
+      if (store.state.encrypted) return;
+      for (const group of list) {
+        if (!await inScope(group)) continue;
+        ensureMirror(group);
+        attachPeers(group);
+      }
+    }
+  };
+}
+
+export { HOUSEHOLD_GROUP_KEY, HouseholdCodeError, createHouseholdGroup, decodeAnnounce, decodeShare, encodeAnnounce, encodeShare, randomId, toCopyLink, toRoster };
+//# sourceMappingURL=households.js.map
+//# sourceMappingURL=households.js.map