selfstore 1.0.0

package/dist/local-2py_vGGy.d.ts

@@ -0,0 +1,47 @@
+import { n as Snapshot, E as EncodeOptions, H as Header } from './store-ChIGEOph.js';
+import { D as DriveAuth } from './drive-Bv94UM8b.js';
+
+/** Serialize a snapshot to a portable backup blob (compressed; encrypted if a password is given). */
+declare function exportSnapshot(snapshot: Snapshot, opts: EncodeOptions): Promise<Blob>;
+/** Read a backup blob (or raw bytes) back into a snapshot. */
+declare function importSnapshot(input: Blob | Uint8Array, opts?: {
+    password?: string;
+}): Promise<Snapshot>;
+/** Peek at a backup's cleartext metadata (app, date, whether it's encrypted) without decrypting. */
+declare function inspect(input: Blob | Uint8Array): Promise<Header>;
+/** True if the backup needs a password to import. */
+declare function isEncrypted(input: Blob | Uint8Array): Promise<boolean>;
+/** Re-encrypt under a new password. `from` opens the file, `to` protects the
+ *  result; omit `to` for an unencrypted backup. */
+declare function changePassword(input: Blob | Uint8Array, opts: {
+    from?: string;
+    to?: string;
+    readme?: string;
+}): Promise<Blob>;
+
+/**
+ * A client-only DriveAuth: the Google Identity Services token flow, no backend.
+ * The access token is cached in sessionStorage so a reload reuses it, and a
+ * silent re-acquisition is attempted when it lapses; if that fails (the Google
+ * session expired, or third-party cookies are blocked) the Drive target reports
+ * needs-attention and the user reconnects in one click. For a connection that
+ * never re-prompts, back the Drive target with a server that holds a refresh
+ * token instead (a broker implementing the same DriveAuth interface).
+ */
+
+/** Build a client-only DriveAuth for the given OAuth client id (no backend). */
+declare function gisDriveAuth(opts: {
+    clientId: string;
+    scope?: string;
+}): DriveAuth;
+
+/**
+ * Local-disk helpers: the DOM edge of selfstore, kept out of the core so the
+ * core stays environment-agnostic and testable.
+ */
+/** Save a backup blob to disk via the File System Access API, else a download. */
+declare function saveToDisk(blob: Blob, filename: string): Promise<void>;
+/** Prompt the user to pick a backup file from disk. Resolves null if cancelled. */
+declare function pickFromDisk(): Promise<File | null>;
+
+export { inspect as a, isEncrypted as b, changePassword as c, exportSnapshot as e, gisDriveAuth as g, importSnapshot as i, pickFromDisk as p, saveToDisk as s };

package/dist/local-AM22RWRR.js

@@ -0,0 +1,7 @@
+export { pickFromDisk, saveToDisk } from './chunk-BJ3RUMGI.js';
+import './chunk-JB4JHM7V.js';
+import './chunk-OWLX6PNT.js';
+import './chunk-FDPAKHQS.js';
+import './chunk-VBFMMR7Q.js';
+//# sourceMappingURL=local-AM22RWRR.js.map
+//# sourceMappingURL=local-AM22RWRR.js.map

package/dist/local-AM22RWRR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"local-AM22RWRR.js"}

package/dist/machine-ALMkT3mk.d.ts

@@ -0,0 +1,17 @@
+/** What every flow exposes: the current snapshot plus a subscription.
+ *  `subscribe` calls the listener IMMEDIATELY with the current snapshot and on
+ *  every change after - that is the Svelte store contract, so a flow works as
+ *  `$flow` in Svelte; React reads `useSyncExternalStore(flow.subscribe, () =>
+ *  flow.snapshot)`; everyone else just re-renders in the callback. */
+interface FlowStore<T> {
+    readonly snapshot: T;
+    subscribe(listener: (snapshot: T) => void): () => void;
+}
+/** Bound a network leg so a stuck destination surfaces as a retryable error
+ *  instead of a flow frozen on a spinner. The rejection is TARGET_UNAVAILABLE -
+ *  transient by contract - because "did not answer in time" says nothing about
+ *  access being lost. Never wrap a human step (a consent popup, a picker):
+ *  people are allowed to be slower than a deadline. */
+declare function withDeadline<T>(work: Promise<T>, ms: number, what: string): Promise<T>;
+
+export { type FlowStore as F, withDeadline as w };

package/dist/store-ChIGEOph.d.ts

@@ -0,0 +1,577 @@
+import { G as GroupIdentity, S as SignedManifest, L as LocalCache } from './cache-De5_sALA.js';
+import { CollectionChanges, Conflict, SyncConfig } from './sync.js';
+
+/** A binary attachment (image, PDF, any bytes). */
+interface SnapshotFile {
+    id: string;
+    name: string;
+    mime: string;
+    bytes: Uint8Array;
+}
+/**
+ * Collection names starting with `__` are reserved for library bookkeeping
+ * (createLocalStore keeps its sync metadata under `__store`). The fluent
+ * `backup()` rejects them and `read()` strips them.
+ */
+declare const RESERVED_COLLECTION_PREFIX = "__";
+/** Everything a backup carries. Collection names must not start with `__`. */
+interface Snapshot {
+    collections: Record<string, unknown[]>;
+    files: SnapshotFile[];
+}
+/** Key-derivation parameters. Stored cleartext so older files still decode. */
+interface KdfParams {
+    algo: 'argon2id';
+    salt: string;
+    m: number;
+    t: number;
+    p: number;
+}
+/**
+ * One wrap of the random data key under one password; any slot's password
+ * opens the backup. Adding or removing a slot leaves the data key alone.
+ * Changing a password rotates the data key (setEncryption) - that is the
+ * operation that actually revokes access.
+ */
+interface PasswordSlot {
+    /** Random id so an app can list or drop a slot without knowing its
+     *  password. Cleartext, not authenticated. */
+    id: string;
+    /** Absent on password slots, so files written before external keys
+     *  existed still parse. */
+    kind?: 'password';
+    kdf: KdfParams;
+    /** 96-bit IV of the wrap, base64. */
+    iv: string;
+    /** AES-256-GCM(KEK, dataKey) with tag appended: 48 bytes, base64. */
+    wrapped: string;
+}
+/**
+ * Data key wrapped under a caller-supplied 32-byte secret (passkey PRF,
+ * hardware token). The library never performs the WebAuthn or hardware
+ * exchange; the app derives the secret and hands it in. KEK is
+ * HKDF-SHA256 of the secret - no Argon2, the input is already
+ * high-entropy. Shares the `keys[]` table with password slots, so a
+ * backup can hold e.g. a passkey plus a recovery password.
+ */
+interface ExternalSlot {
+    id: string;
+    kind: 'external';
+    /** App-owned locator for re-deriving the secret (say, a WebAuthn
+     *  credential id). Cleartext, never a security input. */
+    keyRef: string;
+    /** 96-bit IV of the wrap, base64. */
+    iv: string;
+    /** AES-256-GCM(KEK, dataKey) with tag appended: 48 bytes, base64. */
+    wrapped: string;
+}
+type KeySlot = PasswordSlot | ExternalSlot;
+/**
+ * Group mode (format 2): the per-publication AES key wrapped for one
+ * recipient. `kid` = first 8 bytes of SHA-256(recipient X25519 public),
+ * base64 - a locator, not a name. `epk` is the ephemeral X25519 public;
+ * `wrap` is AES-256-GCM(dataKey) under HKDF of the ECDH shared secret.
+ */
+interface RecipientStanza {
+    kid: string;
+    epk: string;
+    iv: string;
+    wrap: string;
+}
+/**
+ * Cleartext metadata: the `meta.json` entry of the ZIP.
+ *
+ * app/appVersion/createdAt are cosmetic and unauthenticated - never base a
+ * security decision on them. In password-envelope mode the wrapped data key
+ * authenticates the payload; in group mode the author's Ed25519 signature
+ * (sig.bin) covers the exact meta.json and data.enc bytes.
+ */
+interface Header {
+    /** Format generation: 2 = plain ZIP, 3 = group, 4 = password envelope.
+     *  Absent means 2. */
+    format?: number;
+    app: string;
+    /** Writing app's release version, informational. */
+    appVersion?: string;
+    /** Writing app's data schema version (createLocalStore `version`).
+     *  Distinct from appVersion: this one drives migration. */
+    schemaVersion?: number;
+    createdAt: string;
+    encryption: 'none' | 'aes-256-gcm';
+    /** 96-bit IV of data.enc, base64. Present when encrypted. */
+    iv?: string;
+    /** Group mode: data-key envelope scheme ('x25519-hkdf-sha256'). */
+    keying?: string;
+    /** Group mode: author's Ed25519 public key. Trust only after verifying
+     *  sig.bin and membership in the group manifest. */
+    author?: string;
+    /** Group mode: one data-key envelope per recipient. */
+    recipients?: RecipientStanza[];
+    /** Password envelope only: the data key wrapped once per password.
+     *  Present iff format === 4. */
+    keys?: KeySlot[];
+}
+/** Options for writing a backup. */
+interface EncodeOptions {
+    app: string;
+    appVersion?: string;
+    schemaVersion?: number;
+    /** Omit or leave empty for an unencrypted backup (a plain, readable ZIP). */
+    password?: string;
+    /** Group mode: encrypt to these recipients (raw X25519 publics, base64)
+     *  under a fresh data key and sign with the author's Ed25519 key.
+     *  Mutually exclusive with `password`. */
+    group?: {
+        recipients: string[];
+        sign: {
+            pub: string;
+            priv: string;
+        };
+    };
+    /** README text shipped inside an encrypted backup, for whoever opens the
+     *  ZIP by hand. Defaults to a neutral note; apps should brand it. */
+    readme?: string;
+    /** Rewrite path: reuse this exact envelope (held data key + slot table
+     *  from the last read) so a writer that knows only one password keeps
+     *  every other slot. Mutually exclusive with `password` and `group`. */
+    envelope?: {
+        dataKey: Uint8Array;
+        slots: KeySlot[];
+    };
+}
+
+type SelfstoreErrorCode = 'BAD_FORMAT' | 'UNSUPPORTED_VERSION' | 'PASSWORD_REQUIRED' | 'DECRYPT_FAILED' | 'TOO_LARGE' | 'AUTH_EXPIRED' | 'TARGET_UNAVAILABLE' | 'TARGET_WRITE_FAILED' | 'TARGET_GONE' | 'NOT_CONNECTED' | 'WEAK_PASSWORD' | 'ENCRYPTION_REQUIRED' | 'UNEXPECTEDLY_UNENCRYPTED' | 'SCHEMA_TOO_NEW' | 'IDENTITY_REQUIRED' | 'SIGNATURE_INVALID' | 'NOT_A_RECIPIENT' | 'MANIFEST_ROLLBACK';
+/**
+ * i18n key for an error code: lower-camel-cased under `error.`, e.g.
+ * 'error.authExpired'. The library ships the key, the app owns the copy;
+ * consumers never have to show the raw developer message. Deterministic, so
+ * codes added later get a key for free - keep a fallback for unknown ones.
+ */
+declare function errorLabelKey(code: SelfstoreErrorCode): string;
+declare class SelfstoreError extends Error {
+    readonly code: SelfstoreErrorCode;
+    constructor(code: SelfstoreErrorCode, message: string);
+}
+/**
+ * Genuine loss of access to a destination (session gone, token revoked):
+ * only a user gesture fixes it. Anything else a target throws is treated as
+ * transient and retried, so a network hiccup never raises the blocking
+ * reconnect gate over a still-valid connection. Custom targets and DriveAuth
+ * implementations throw this to signal the genuine case.
+ */
+declare class AuthExpiredError extends SelfstoreError {
+    constructor(message?: string);
+}
+/**
+ * Shape check rather than instanceof, so it survives two bundled copies of
+ * the library. The name check keeps foreign coded errors (ENOENT...) out.
+ */
+declare function isSelfstoreError(e: unknown): e is SelfstoreError;
+/** True on genuine access loss, false on transient blips. */
+declare function isAuthExpired(e: unknown): boolean;
+
+interface PasswordPolicy {
+    /** Minimum length in code points (so an emoji counts as one). Default 0. */
+    minLength?: number;
+    /** Require at least one lowercase letter (any script with case). */
+    requireLowercase?: boolean;
+    /** Require at least one uppercase letter (any script with case). */
+    requireUppercase?: boolean;
+    /** Require at least one digit. */
+    requireDigit?: boolean;
+    /** Require at least one symbol: anything that is not a letter or a number. */
+    requireSymbol?: boolean;
+}
+/** A stable code for each unmet requirement, so the app maps it to its own copy
+ *  (like the error codes). `minLength` covers the length rule. */
+type PasswordRequirement = 'minLength' | 'lowercase' | 'uppercase' | 'digit' | 'symbol';
+interface PasswordCheck {
+    ok: boolean;
+    /** The requirements the password fails, in a stable order. Empty when ok. */
+    unmet: PasswordRequirement[];
+}
+/** Measure a password against a policy. Pure and synchronous: the same call
+ *  drives a live strength hint in the UI and the store's enforcement. An empty
+ *  or absent policy passes everything. */
+declare function checkPasswordPolicy(password: string, policy: PasswordPolicy): PasswordCheck;
+
+type Severity = 'ok' | 'info' | 'warn' | 'danger';
+type StorageState = 'ephemeral' | 'cache-only' | 'saving' | 'saved' | 'pending-download' | 'needs-attention';
+/** A suggested action the UI can wire to a button. */
+type StatusAction = 'choose-destination' | 'download' | 'reconnect' | 'unlock';
+/** The headless descriptor the UI renders. */
+interface StatusDescriptor {
+    state: StorageState;
+    severity: Severity;
+    actionable: boolean;
+    action?: StatusAction;
+    /** Stable i18n key; the app owns the actual copy. */
+    labelKey: string;
+}
+interface StatusInput {
+    /** False means ephemeral (the local cache is off). */
+    persistent: boolean;
+    /** Any BackupTarget kind, or a reserved store mode ('device', 'file-manual'). */
+    targetKind: string;
+    saving: boolean;
+    /** The durable home needs a user gesture (token expired, permission lapsed, locked). */
+    needsAttention: boolean;
+    /** The attention is a lock (password not in memory): the gesture is unlock, not reconnect. */
+    locked: boolean;
+    /** Degraded file mode has changes awaiting a manual download. */
+    pendingDownload: boolean;
+}
+/** Map the store's raw flags to a single, ranked status; the most important wins. */
+declare function deriveStatus(input: StatusInput): StatusDescriptor;
+
+type BuiltinTargetKind = 'file' | 'drive' | 'webdav';
+/**
+ * The two kinds the store keeps for itself: 'device' (cache-only) and
+ * 'file-manual' (degraded download-on-demand). attachTarget refuses a target
+ * claiming either - they name the absence of a target.
+ */
+declare const RESERVED_STORE_MODES: readonly ["device", "file-manual"];
+/** Single source of truth for "is this kind a store mode, not a durable target". */
+declare function isReservedStoreMode(kind: string): boolean;
+/**
+ * The read-only subset of BackupTarget a peer must provide. Any BackupTarget
+ * satisfies it structurally; its save() is simply never called. Peer failures
+ * follow the same protocol but are recorded per peer and never gate the store.
+ */
+interface PeerSource {
+    /** The peer's published copy, or null when none exists yet. */
+    load(): Promise<Blob | null>;
+    /** Cheap remote change marker, so unchanged copies can be skipped. Absent means "cannot tell". */
+    stat?(): Promise<string | null>;
+    /** Display name (defaults to the peer id). */
+    readonly label?: string;
+}
+interface BackupTarget {
+    /** Stable discriminator, persisted and handed back to restoreTarget(kind)
+     *  next session. Custom targets pick any string outside the built-ins and
+     *  RESERVED_STORE_MODES. */
+    readonly kind: string;
+    /** Human label for the connected destination (file name, "Google Drive"). */
+    readonly label: string;
+    /** Push the backup blob. May resolve to the remote's new version marker
+     *  when the write reports it atomically (else the store calls stat()). */
+    save(blob: Blob): Promise<string | null>;
+    /** Latest backup blob, or null if none exists / unavailable. */
+    load(): Promise<Blob | null>;
+    /** Cheap remote change marker (Drive version, file mtime): lets the store
+     *  spot another replica's writes without downloading. */
+    stat?(): Promise<string | null>;
+    /** Writable right now, without a user gesture? False for a transient blip
+     *  (retried later); AuthExpiredError for a genuine loss of access. */
+    isReady(): Promise<boolean>;
+    /** Re-acquire access (needs a user gesture); resolves to whether it worked. */
+    reconnect(): Promise<boolean>;
+    /** Forget the target locally. Never deletes the remote data. */
+    disconnect(): Promise<void>;
+}
+
+type Mode = 'persistent' | 'ephemeral';
+/** Any BackupTarget kind, or a reserved store mode ('device', 'file-manual').
+ *  Deliberately open: a custom target's kind flows through here. */
+type TargetKind = 'device' | 'file-manual' | (string & {});
+/** What triggered a converge with the remote (for the sync journal). */
+type SyncSource = 'boot' | 'focus' | 'online' | 'interval' | 'manual' | 'push' | 'connect';
+/** One journal line: a converge that actually changed local data. */
+interface SyncJournalEntry {
+    at: number;
+    source: SyncSource;
+    changes: Record<string, CollectionChanges>;
+    /** Concurrent same-record edits, auto-resolved latest-wins. Both values are
+     *  carried so the app can show or restore the overwritten one. */
+    conflicts?: Conflict[];
+}
+/** The last problem the store hit, as a stable code the app maps to its own wording. */
+interface StoreError {
+    code: SelfstoreErrorCode;
+    /** Stable i18n key for `code` (errorLabelKey). Show this, mapped to your copy. */
+    labelKey: string;
+    /** Developer detail for logs - English, may carry an HTTP status. Never display it. */
+    message: string;
+}
+/**
+ * Group mode: this member's identity, the admin key pinned at join time
+ * (TOFU, from the invite), and the manifest as it travels. The store verifies
+ * the manifest itself - signature, member-key shapes, group binding - so
+ * group security never depends on the app remembering to call openManifest.
+ */
+interface StoreGroupConfig {
+    identity: GroupIdentity;
+    /** The admin's Ed25519 public key (base64 raw), pinned from the invite. */
+    admin: string;
+    /** The admin-signed manifest exactly as distributed (signManifest output). */
+    manifest: SignedManifest;
+}
+/** One attached peer (another member's read-only copy - see attachPeer). */
+interface PeerState {
+    id: string;
+    label: string;
+    /** Last successful fold-in (ms epoch), or null. */
+    lastSyncAt: number | null;
+    /** Group mode: the manifest member whose signature the last folded copy carried. */
+    author: string | null;
+    /** Per-peer on purpose: a broken peer never gates the store itself. */
+    lastError: StoreError | null;
+}
+/** One write-only published copy of this store (see attachMirror). */
+interface MirrorState {
+    id: string;
+    label: string;
+    /** Last successful publish (ms epoch), or null. */
+    lastPublishAt: number | null;
+    /** Per-mirror on purpose: a broken mirror never gates the store itself. */
+    lastError: StoreError | null;
+}
+/** One secondary synced copy of this store (see attachReplica). */
+interface ReplicaState {
+    id: string;
+    label: string;
+    /** Last successful publish (ms epoch), or null. */
+    lastPublishAt: number | null;
+    /** Per-replica on purpose: a broken replica never gates the store itself. */
+    lastError: StoreError | null;
+}
+/** The read-only snapshot of the store the UI renders. */
+interface LocalStoreState {
+    ready: boolean;
+    mode: Mode;
+    targetKind: TargetKind;
+    label: string | null;
+    encrypted: boolean;
+    locked: boolean;
+    saving: boolean;
+    lastSavedAt: number | null;
+    status: StatusDescriptor;
+    /** The last durable-target problem (upload/refresh), or null. */
+    lastError: StoreError | null;
+    /** Recent converges that changed local data, newest first (device-local). */
+    journal: SyncJournalEntry[];
+    /** The last live converge that changed data (drives the "synced" toast). */
+    lastSync: SyncJournalEntry | null;
+    /** Attached peers, in attach order. */
+    peers: PeerState[];
+    /** Attached mirrors, in attach order. */
+    mirrors: MirrorState[];
+    /** Attached replicas (secondary synced copies), in attach order. */
+    replicas: ReplicaState[];
+}
+interface LocalStoreOptions {
+    /** App id; names the backup and scopes the default cache database. */
+    app: string;
+    /** Data schema version; bump when gather's shape changes. Stamped into every
+     *  backup, drives migrate() and the SCHEMA_TOO_NEW gate. */
+    schemaVersion: number;
+    /** Release version ("1.4.2"), stamped informationally into the header. */
+    appVersion?: string;
+    /** Branded README shipped inside encrypted backups. */
+    readme?: string;
+    /** Refuse to ever write or export a plaintext backup. attachTarget without a
+     *  password or group is rejected, setEncryption(null) is rejected, and
+     *  exportBlob refuses a cleartext copy - the backup that leaves the device is
+     *  always ciphertext. Scope is deliberately the travelling copy: the
+     *  on-device working cache stays governed by the browser profile, as ever.
+     *  Off by default. */
+    requireEncryption?: boolean;
+    /** Reject a backup password that fails this strength policy (length and
+     *  character classes): setEncryption, addEncryptionKey and a password given
+     *  to attachTarget throw WEAK_PASSWORD before touching anything. The app can
+     *  preview the same rules with checkPasswordPolicy so its UI blocks a weak
+     *  password before it is ever submitted. Omit for no policy. */
+    passwordPolicy?: PasswordPolicy;
+    /** Gather the app's live state into a portable snapshot. */
+    gather: () => Promise<Snapshot> | Snapshot;
+    /** Apply a snapshot into the app (replaces current state). */
+    apply: (snap: Snapshot) => void;
+    /** Upgrade a snapshot written by an older version to the current shape. */
+    migrate?: (fromVersion: number, snap: Snapshot) => Snapshot;
+    /** Per-collection merge strategies. Omit for everything lww-set. */
+    sync?: SyncConfig;
+    /** Derived collections whose merges are routine noise (recomputed data, not
+     *  user edits): converges touching only these skip the sync journal. */
+    journalSilent?: string[];
+    /** Prune delete-tombstones older than this many ms on each save. Safe only
+     *  when it comfortably exceeds the longest a device stays offline: a device
+     *  that never saw a delete resurrects the record once the tombstone is gone
+     *  everywhere. Omit to keep every tombstone; weeks is a reasonable value. */
+    tombstoneHorizonMs?: number;
+    /** Coordinate several tabs of the same app (default: on in browser
+     *  windows). Every save first folds what other tabs persisted, writes
+     *  serialize through a cross-tab Web Lock where available, and a
+     *  BroadcastChannel refreshes the other tabs after each write. Data and
+     *  bookkeeping only: a target's connection stays per tab (restoreTarget at
+     *  boot), and mode/target switches reach other tabs on reload. */
+    multiTab?: boolean;
+    /** The working store under the app. */
+    cache: LocalCache;
+    /** Rebuild a durable target connected in a past session. Receives the kind
+     *  persisted at attach time - built-in or custom. */
+    restoreTarget?: (kind: string) => Promise<BackupTarget | null>;
+    /** Debounce window for auto-save (ms). Default 800. */
+    debounceMs?: number;
+    /** Diagnostics sink, developer-facing (defaults to the console). */
+    logger?: {
+        warn(...args: unknown[]): void;
+        error(...args: unknown[]): void;
+    };
+}
+interface LocalStore {
+    readonly state: LocalStoreState;
+    subscribe(fn: () => void): () => void;
+    /** Hydrate from the cache, restore a saved durable target, converge with it. */
+    init(): Promise<void>;
+    /** Schedule a debounced save (call after each mutation). */
+    schedule(): void;
+    /** Save now, cancelling the debounce (use on tab hide). */
+    flush(): Promise<void>;
+    /** Converge with the remote only if it changed since the last sync (a cheap
+     *  stat, throttled). Call on tab focus, network return and a slow interval. */
+    syncIfStale(source: SyncSource): Promise<void>;
+    /** Converge with the remote now (user gesture). Resolves to what changed
+     *  locally, or null when already up to date. */
+    syncNow(): Promise<SyncJournalEntry | null>;
+    /** Inspect a target for an existing backup, without changing any state. */
+    inspectTarget(target: BackupTarget): Promise<{
+        hasBackup: boolean;
+        date: string | null;
+        encrypted: boolean;
+    }>;
+    /** Attach a durable home. `strategy` reconciles with what is already on the
+     *  target: 'merge' (default, multi-device), 'replace-local' (load the
+     *  target into the app) or 'replace-remote' (overwrite the target).
+     *  `keepSession` leaves the departing target's credentials untouched (a
+     *  backup switch behind one account). `wipe` starts the new home blank -
+     *  empty data, fresh sync meta, never seeded from the departing one. */
+    attachTarget(target: BackupTarget, opts?: {
+        password?: string | null;
+        /** Group mode: publish signed copies enveloped for every manifest
+         *  member, trust only member-signed copies back. The manifest is
+         *  verified here, against the pinned admin key, before anything
+         *  about the store changes. Mutually exclusive with `password`.
+         *  Not persisted: re-attach with the group config at boot. */
+        group?: StoreGroupConfig;
+        strategy?: 'merge' | 'replace-local' | 'replace-remote';
+        keepSession?: boolean;
+        wipe?: boolean;
+    }): Promise<void>;
+    /** Apply a newer membership manifest. Verified against the admin key and
+     *  group id pinned at attach (a swapped admin or foreign group never
+     *  lands), with seq monotonicity across sessions (MANIFEST_ROLLBACK on an
+     *  older one). The next publish re-envelopes for the new member list -
+     *  which is how removal takes effect: a removed member stops being a
+     *  recipient of anything published from now on. */
+    setGroup(manifest: SignedManifest): Promise<void>;
+    /** Attach another member's published copy as a read-only peer. Every
+     *  converge pulls each peer's copy and merges it as one more replica, then
+     *  publishes the merged state to this store's own target - crossed
+     *  read-only links are how read-write sharing emerges. A peer copy opens
+     *  with its own `password` when given, else the session password. Peer
+     *  problems land on `state.peers` and never gate the store. Not persisted:
+     *  re-attach at boot. Resolves to the peer id (pass `id` to pin it). */
+    attachPeer(source: PeerSource, opts?: {
+        id?: string;
+        password?: string;
+    }): string;
+    /** Detach a peer locally (never touches the member's copy). Unknown id: no-op. */
+    detachPeer(id: string): void;
+    /** Publish a write-only mirror: after every save or converge that moved
+     *  data, the current state is re-encoded under the mirror's own password
+     *  and saved to the mirror target. The store's own file is never re-keyed -
+     *  that is the point: your file stays yours, the copy others read travels
+     *  under the share key. The envelope is minted once (no KDF per publish);
+     *  mirror problems land on `state.mirrors` and never gate the store. Not
+     *  persisted: re-attach at boot. Resolves to the mirror id. */
+    attachMirror(target: BackupTarget, opts: {
+        password: string;
+        id?: string;
+    }): string;
+    /** Detach a mirror locally (the published copy stays where it is). */
+    detachMirror(id: string): void;
+    /** Attach a secondary synced copy: after every save or converge that moved
+     *  data, the CURRENT backup - same bytes, same key as the primary home - is
+     *  also written to this target. A resilience mirror of your own file (Drive
+     *  plus an S3 bucket, say), not a share: any device can later attach it as
+     *  its primary with the same password. Publishing reuses the primary's
+     *  envelope, so it costs no extra KDF; replica problems land on
+     *  `state.replicas` and never gate the store. Not persisted: re-attach at
+     *  boot. Resolves to the replica id (pass `id` to pin it). */
+    attachReplica(target: BackupTarget, opts?: {
+        id?: string;
+    }): string;
+    /** Detach a replica locally (the copy already written stays where it is). */
+    detachReplica(id: string): void;
+    /** Switch to degraded download-on-demand mode (non-Chromium file). */
+    setManualFile(): Promise<void>;
+    /** Unlock an encrypted target: the password is held in memory only, then a
+     *  converge runs. False on a wrong password (the gate re-raises) or when
+     *  the target is not locked (use `reconnect`). */
+    unlock(password: string): Promise<boolean>;
+    /** Re-acquire access after a genuine loss: run the target's reconnect
+     *  gesture, then converge. False when locked (use `unlock`) or absent. */
+    reconnect(): Promise<boolean>;
+    /** Re-lock now: drop the in-memory password (encrypted target). */
+    lock(): void;
+    /** Detach the durable home (does not delete it); back to cache-only.
+     *  `keepSession` skips the target's disconnect so its credentials survive -
+     *  for a caller that still needs the destination right after (deleting the
+     *  detached file, attaching another one on the same account). */
+    detachTarget(opts?: {
+        keepSession?: boolean;
+    }): Promise<void>;
+    /** Build the portable .selfstore blob (for a manual download or dated copy). */
+    exportBlob(): Promise<Blob>;
+    /** Mark the file-manual pending download as resolved. */
+    markDownloaded(): void;
+    /** Stop persisting (shared computer). */
+    setEphemeral(): void;
+    /** Resume persisting to the cache. */
+    leaveEphemeral(): Promise<void>;
+    /** Wipe all app data. With a destination connected, keep the connection and
+     *  empty its backup too; with none, forget locally and return to the
+     *  cache-only default. The UI empties immediately, no reload. */
+    forget(): Promise<void>;
+    /** Add, change or remove the backup password - reversible. A non-empty
+     *  string (re)encrypts; null decrypts. Needs a connected, unlocked target;
+     *  rewrites cache and remote. Setting a password rotates the data key
+     *  (fresh key, single slot), so every previously authorized password
+     *  stops opening the file. */
+    setEncryption(password: string | null): Promise<void>;
+    /** Add another password that opens this backup: the data key gains one
+     *  slot, nothing is re-encrypted, existing passwords keep working - how
+     *  sharing adds its key without clobbering the owner's. Verified against
+     *  the built bytes before the write lands. Resolves to the slot id. */
+    addEncryptionKey(password: string, id?: string): Promise<string>;
+    /** Remove one password slot by id. Refuses the last slot (that is
+     *  setEncryption(null)) and refuses to lock the current session out.
+     *  Bearer reality: whoever held that password may hold old bytes - only a
+     *  rotation makes new writes unreadable to them. */
+    removeEncryptionKey(id: string): Promise<void>;
+    /** Encrypt under an external key (passkey PRF, hardware token) instead of
+     *  a typed password: fresh data key, one external slot. `keyRef` is stored
+     *  verbatim so the app can re-derive the secret. Rotates like
+     *  setEncryption; the app owns the WebAuthn exchange and hands in the
+     *  32-byte secret. */
+    setExternalEncryption(secret: Uint8Array, keyRef: string): Promise<void>;
+    /** Add an external-key slot to an already-encrypted backup - a passkey
+     *  alongside a recovery password, or the reverse. Needs an unlocked
+     *  session; verified against the built bytes before the write lands. */
+    addExternalKey(secret: Uint8Array, keyRef: string, id?: string): Promise<string>;
+    /** unlock(), but trying the external slots with `secret`. */
+    unlockWithExternal(secret: Uint8Array): Promise<boolean>;
+    /** The current slot table (id + kind, so a passkey slot can be labelled).
+     *  Empty when unknown: plaintext, locked, or not read yet this session. */
+    listEncryptionKeys(): {
+        id: string;
+        kind: 'password' | 'external';
+    }[];
+    /** Cancel timers, close the cross-tab channel, drop subscribers - nothing
+     *  fires into a dead app after unmount. Persisted data is untouched; the
+     *  store is not usable afterwards. */
+    dispose(): void;
+}
+declare function createLocalStore(opts: LocalStoreOptions): LocalStore;
+
+export { AuthExpiredError as A, type BackupTarget as B, errorLabelKey as C, isAuthExpired as D, type EncodeOptions as E, isReservedStoreMode as F, isSelfstoreError as G, type Header as H, type KdfParams as K, type LocalStore as L, type MirrorState as M, type PasswordCheck as P, RESERVED_COLLECTION_PREFIX as R, SelfstoreError as S, type TargetKind as T, type BuiltinTargetKind as a, type LocalStoreOptions as b, type LocalStoreState as c, type Mode as d, type PasswordPolicy as e, type PasswordRequirement as f, type PeerSource as g, type PeerState as h, RESERVED_STORE_MODES as i, type RecipientStanza as j, type ReplicaState as k, type SelfstoreErrorCode as l, type Severity as m, type Snapshot as n, type SnapshotFile as o, type StatusAction as p, type StatusDescriptor as q, type StatusInput as r, type StorageState as s, type StoreError as t, type StoreGroupConfig as u, type SyncJournalEntry as v, type SyncSource as w, checkPasswordPolicy as x, createLocalStore as y, deriveStatus as z };