@drakkar.software/octospaces-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,972 @@
+import { WrappedKeyEntry } from '@drakkar.software/starfish-keyring';
+import { StarfishClient, Encryptor, StarfishCapProvider, PullCache } from '@drakkar.software/starfish-client';
+import { CapCert, Base64Provider } from '@drakkar.software/starfish-protocol';
+import { BootstrapOrigin, ScopePreset } from '@drakkar.software/starfish-identities';
+
+/**
+ * Runtime configuration for the OctoSpaces SDK — the Starfish sync server URL,
+ * optional namespace, events-stream URL, and public web origin.
+ *
+ * The SDK is headless and platform-agnostic, so it does NOT read environment
+ * variables itself. The host app reads its own env (e.g. Expo `EXPO_PUBLIC_*`) and
+ * calls {@link configureOctoSpaces} once at boot, before any sync/identity API runs.
+ * Getters throw a clear error if called before configuration so a misconfigured
+ * host fails fast rather than silently signing the wrong path.
+ */
+interface OctoSpacesConfig {
+    /** Starfish sync server base URL (e.g. `http://localhost:8787`). */
+    syncBase: string;
+    /** Bare namespace name; the SDK prepends `/v1/<namespace>` to signed paths.
+     *  Unset for a root-mounted (local dev) server. */
+    syncNamespace?: string;
+    /**
+     * Optional SEPARATE namespace for cross-app shared-spaces storage. When set,
+     * space registry ops use this namespace instead of `syncNamespace`, enabling a
+     * single shared space list across multiple app namespaces (e.g. OctoChat and
+     * OctoVault sharing spaces at `/v1/shared`). If unset, falls back to the default
+     * namespace for all operations (single-app behavior).
+     */
+    sharedSpacesNamespace?: string;
+    /** Override the live change-event SSE endpoint. Defaults to
+     *  `${syncBase}${syncPrefix}/events`. */
+    eventsUrl?: string;
+    /** Public origin of the web app, used to build shareable invite links on
+     *  platforms without `window.location` (native). Empty by default. */
+    webBase?: string;
+    /**
+     * Called when a background Starfish revalidation succeeds after a 429/5xx
+     * cache-fallback (stale-while-revalidate). Use it to signal that the server
+     * is reachable again so any stale views re-pull and recover.
+     */
+    onServerReachable?: () => void;
+}
+/** Configure the SDK. Call once at app boot before any sync/identity API. */
+declare function configureOctoSpaces(config: OctoSpacesConfig): void;
+/** Starfish sync server base URL. */
+declare const getSyncBase: () => string;
+/** Bare namespace name (or `undefined` for a root-mounted server). */
+declare const getSyncNamespace: () => string | undefined;
+/** Namespaced path prefix (`/v1/<namespace>`, or `''` locally). */
+declare const getSyncPrefix: () => string;
+/** Optional separate namespace for shared-spaces storage. `undefined` means use the default namespace. */
+declare const getSharedSpacesNamespace: () => string | undefined;
+
+/**
+ * Platform adapters the headless SDK needs the host app to provide.
+ *
+ * The SDK can't do Metro `.native.ts` file-extension resolution and must not bind
+ * to localStorage / AsyncStorage / SecureStore directly, so the host injects a
+ * key/value store at boot via {@link configureKv}. This holds account-scoped state
+ * the SDK persists offline (joined-space member caps, the public-space access map,
+ * read marks, mutes, profile/pull caches).
+ */
+/** Async key/value store — web `localStorage`, native `AsyncStorage`, etc. */
+interface KvAdapter {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+/** Install the host's key/value store. Call once at app boot. */
+declare function configureKv(adapter: KvAdapter): void;
+declare const kvGet: (key: string) => Promise<string | null>;
+declare const kvSet: (key: string, value: string) => Promise<void>;
+declare const kvRemove: (key: string) => Promise<void>;
+
+/**
+ * Starfish client construction + space keyring/encryptor helpers.
+ */
+
+interface DeviceKeys {
+    edPriv: string;
+    edPub: string;
+    kemPriv: string;
+    kemPub: string;
+}
+declare function capProviderFor(cap: unknown, devEdPrivHex: string): StarfishCapProvider;
+/**
+ * Build a Starfish client. `namespaceOverride` overrides the configured namespace,
+ * enabling the shared-spaces feature (a separate namespace for cross-app registry ops).
+ */
+declare function makeClient(cap: unknown, devEdPrivHex: string, namespaceOverride?: string): StarfishClient;
+/**
+ * Open a SPACE's decryptor, throwing a descriptive error per failure mode
+ * (unreachable server / no keyring yet / not a recipient).
+ *
+ * A `SpaceAccessError` is a hard access denial; any other thrown error is a
+ * transient offline state.
+ */
+declare function openEncryptor(client: StarfishClient, keys: DeviceKeys, spaceId: string, trustedAdders: string[]): Promise<Encryptor>;
+/** Soft variant of {@link openEncryptor}: returns null instead of throwing. */
+declare function buildEncryptor(client: StarfishClient, keys: DeviceKeys, spaceId: string, trustedAdders: string[]): Promise<Encryptor | null>;
+/**
+ * Owner-side: create the SPACE keyring if missing, return an encryptor.
+ */
+declare function ownerEnsureKeyring(client: StarfishClient, keys: DeviceKeys, spaceId: string, trustedAdders?: string[]): Promise<Encryptor>;
+/** A user's public profile: display pseudo + optional inline avatar + public identity keys. */
+interface PublicProfile {
+    pseudo: string | null;
+    avatar: string | null;
+    edPub: string | null;
+    kemPub: string | null;
+}
+/** Read any user's public profile. */
+declare function readProfile(userId: string): Promise<PublicProfile>;
+/** Read any user's public profile pseudo. */
+declare function readPseudo(userId: string): Promise<string | null>;
+/**
+ * Read MANY users' public profiles in one /batch/pull round-trip per chunk.
+ */
+declare function readProfiles(ids: string[]): Promise<Map<string, PublicProfile>>;
+/**
+ * Merge a patch into the caller's own profile doc.
+ */
+declare function writeProfile(client: StarfishClient, userId: string, patch: {
+    pseudo?: string;
+    avatar?: string | null;
+    edPub?: string;
+    kemPub?: string;
+}): Promise<void>;
+/** Write the caller's own profile pseudo. */
+declare function writePseudo(client: StarfishClient, userId: string, pseudo: string): Promise<void>;
+/**
+ * Publish this identity's PUBLIC keys in its profile so a peer can start an E2EE DM.
+ * One-time + idempotent. ROOT-DEVICE ONLY — `profile` is `device:root`-write.
+ */
+declare function ensureProfileKeys(client: StarfishClient, userId: string, keys: {
+    edPub: string;
+    kemPub: string;
+}): Promise<void>;
+/**
+ * Build cap-cert auth headers for a raw `fetch` outside the StarfishClient.
+ */
+declare function buildAuthHeaders(cap: unknown, devEdPrivHex: string, method: string, pathAndQuery: string): Promise<Record<string, string>>;
+/**
+ * Seed the caller's profile pseudo only if none exists yet, returning the
+ * authoritative server value.
+ */
+declare function ensurePseudo(client: StarfishClient, userId: string, fallback: string): Promise<string>;
+
+/**
+ * Shared types for the persisted-session storage layer. Both platform variants
+ * (`storage.ts` web, `storage.native.ts` native) implement the same contract so
+ * the session context stays platform-agnostic.
+ */
+
+/**
+ * The root identity already derived from the seed (userId + device keys). Caching
+ * it lets unlock/cold-start skip the heavy `bootstrapRootIdentity` Argon2id.
+ * Equivalent in sensitivity to the seed, so it lives inside the same sealed blob.
+ */
+interface DerivedIdentity {
+    userId: string;
+    keys: DeviceKeys;
+}
+/** The recovery seed + display name — the minimum needed to re-derive an identity. */
+interface PersistedSession {
+    /** BIP-39 recovery seed. Absent for non-seed origins. */
+    seed?: string[];
+    name: string;
+    /** Cached root identity so restore skips the bootstrap Argon2id. */
+    derived?: DerivedIdentity;
+    /** How this identity was bootstrapped. Absent for seed-derived identities. */
+    bootstrapOrigin?: BootstrapOrigin;
+    /** Root-signed cap-cert for a PAIRED (linked) device. */
+    capCert?: CapCert;
+}
+/**
+ * Every account held on this device plus which one is active. The whole vault is
+ * sealed as a unit (web: under one app-lock via a vault master key; native: a
+ * single secure-store entry).
+ */
+interface Vault {
+    accounts: PersistedSession[];
+    activeId: string;
+}
+/** Ways the web-persisted seed can be unlocked. */
+type UnlockMethod = 'pin' | 'passkey';
+/** A registered passkey + the PRF secret used to seal the seed for it. */
+interface PasskeyEnrollment {
+    credentialId: string;
+    salt: string;
+    secretHex: string;
+}
+/** How to lock the seed when persisting it (web only). */
+interface SeedLock {
+    pin: string;
+    passkey?: PasskeyEnrollment;
+}
+/**
+ * Result of probing storage at launch:
+ * - `none`   — nothing stored; start signed-out.
+ * - `ready`  — vault available immediately (native Keychain path).
+ * - `locked` — a sealed vault exists; unlock with one of `methods` (web path).
+ * - `error`  — storage read failed.
+ */
+type VaultLoad = {
+    kind: 'none';
+} | {
+    kind: 'ready';
+    vault: Vault;
+} | {
+    kind: 'locked';
+    methods: UnlockMethod[];
+} | {
+    kind: 'error';
+    error: unknown;
+};
+
+interface Session {
+    userId: string;
+    name: string;
+    keys: DeviceKeys;
+    chatCap: unknown;
+    accountCap: unknown;
+    /**
+     * The primary Starfish client for space content (keyring, channels, objects).
+     * Uses the app's default namespace.
+     */
+    chatClient: StarfishClient;
+    /**
+     * The Starfish client for account-scoped content (profile, _spaces registry).
+     * Uses the app's default namespace.
+     */
+    accountClient: StarfishClient;
+    /**
+     * Starfish client for cross-app shared-spaces registry operations.
+     * When `sharedSpacesNamespace` is configured, uses that namespace override so
+     * the spaces list lives in a separate namespace shared across multiple apps.
+     * Falls back to `accountClient` when no shared namespace is configured.
+     */
+    spacesRegistryClient: StarfishClient;
+    /**
+     * Starfish client for cross-app shared-spaces keyring operations.
+     * Same namespace logic as `spacesRegistryClient`, scoped to space content.
+     * Falls back to `chatClient` when no shared namespace is configured.
+     */
+    spacesKeyringClient: StarfishClient;
+    fingerprint: string;
+    /**
+     * The Ed25519 pubkey that signs this identity's OWNED-space keyring entries —
+     * the trusted-adder provenance anchor for opening them.
+     */
+    ownerEdPub: string;
+}
+/**
+ * Trusted-adder allow-list for opening an OWNED space's keyring.
+ */
+declare function ownerTrustedAdders(session: Session): string[];
+/** Fresh 12-word recovery seed. */
+declare function generateSeedWords(): string[];
+declare function isValidSeed(words: string[]): boolean;
+/** Human-readable fingerprint derived from the identity's user id. */
+declare function fingerprintFromUserId(userId: string): string;
+/**
+ * Build a full owner session (caps + clients + pseudo) from an already-derived
+ * root identity. No Argon2id — only fast Ed25519 cap-minting plus a profile fetch.
+ */
+declare function buildSession({ userId, keys }: DerivedIdentity, name?: string): Promise<Session>;
+/** A paired device's credentials: its own keypair + the root-signed cap-cert. */
+interface LinkedIdentity {
+    userId: string;
+    keys: DeviceKeys;
+    capCert: CapCert;
+}
+/**
+ * Build a session for a PAIRED (linked) device. Unlike {@link buildSession}, the
+ * device keypair is NOT the root, so it cannot self-mint caps — both clients are
+ * driven by the single root-signed `capCert` from the pairing bundle.
+ */
+declare function buildLinkedSession({ userId, keys, capCert }: LinkedIdentity, name?: string): Promise<Session>;
+/** Derive a full owner session (identity + caps + clients) from a seed. */
+declare function deriveSession(seedWords: string[], name?: string): Promise<Session>;
+/** The cached root identity (userId + keys) carried by a built session. */
+declare function rootIdentityOf(s: Session): DerivedIdentity;
+
+/** A payload sealed to a KEM key: the wrapped CEK + hex(iv ‖ AES-GCM ct). */
+interface SealedBlob {
+    entry: WrappedKeyEntry;
+    ct: string;
+}
+/** Seal `plaintext` so only this account (its seed) can open it. */
+declare function sealToSelf(session: Session, plaintext: string): Promise<SealedBlob>;
+/** Open a {@link SealedBlob} sealed by {@link sealToSelf} for this account. */
+declare function unsealFromSelf(session: Session, blob: SealedBlob): Promise<string>;
+/** Seal `plaintext` to ANOTHER user's published KEM key, signed by this session. */
+declare function sealToRecipient(session: Session, recipientKemPub: string, plaintext: string): Promise<SealedBlob>;
+/** Open a {@link SealedBlob} sealed to THIS account by some (arbitrary) sender. */
+declare function unsealFromRecipient(session: Session, blob: SealedBlob): Promise<string>;
+
+type ID = string;
+/** Maps a joined private space's id → its owner-issued member cap-cert (serialized
+ *  JSON). Persisted both in device-local kv (`member-caps.ts`) and, for durability,
+ *  in the user's own synced `_spaces` doc so a fresh device re-hydrates it. */
+type CapMap = Record<string, string>;
+/** Maps a joined PUBLIC space's id → its invitation credential (the owner-signed cap
+ *  plus the link's ephemeral private key) SEALED to the account's own key. Unlike a
+ *  member cap (safe in the clear — see {@link CapMap}), a public-join credential
+ *  embeds a bearer secret, so it is sealed before riding in the plaintext `_spaces`
+ *  doc. Recovered on any device with the same seed. See `account-seal.ts` and
+ *  `space-access-store.ts`. */
+type PubAccessMap = Record<string, SealedBlob>;
+/** Maps a DM peer's userId → the private DM-space id shared with them. */
+type DmMap = Record<string, string>;
+/** The set of DM-space ids the user has archived (hidden from the DM list). */
+type ArchivedDms = Record<string, true>;
+/** A mute entry. `true` = muted indefinitely; a number = muted UNTIL that epoch-ms instant. */
+type MuteValue = true | number;
+/** Per-user mute preferences: which rooms and which whole spaces are silenced. */
+interface MutePrefs {
+    rooms: Record<string, MuteValue>;
+    spaces: Record<string, MuteValue>;
+}
+/** A per-room read mark: the epoch-ms instant the viewer last read that room. */
+type ReadValue = number;
+/** Per-user read marks — the timestamp each room was last read. */
+interface ReadPrefs {
+    rooms: Record<string, ReadValue>;
+}
+/** Whether a space encrypts its content client-side. */
+type SpaceVisibility = 'private' | 'public';
+interface Space {
+    id: ID;
+    name: string;
+    /** 2-letter monogram used in the space rail. */
+    short: string;
+    /** Uploaded space image as a data URI; absent → render the `short` monogram. */
+    image?: string;
+    members: number;
+    unread?: number;
+    /** 'private' (E2EE keyring, the default) or 'public' (plaintext, joined via a
+     *  space-wide invitation link). Absent ⇒ treat as 'private' (back-compat). */
+    visibility?: SpaceVisibility;
+    /** Public spaces only: the owner's userId (derived from the cap issuer). */
+    ownerId?: string;
+    /** Public spaces only (joiner side): whether this identity's invite link grants write. */
+    write?: boolean;
+}
+/** Legacy room kind — used while apps migrate their content onto objects.
+ *  New code should use {@link RoomSubtype} directly. */
+type RoomKind = 'channel' | 'dm' | 'automated';
+/** Scheduled-fetch cadence for automated rooms. */
+type AutomationSchedule = {
+    kind: 'interval';
+    everyMin: number;
+} | {
+    kind: 'daily';
+    hour: number;
+    minute: number;
+} | {
+    kind: 'weekly';
+    weekday: number;
+    hour: number;
+    minute: number;
+} | {
+    kind: 'cron';
+    expression: string;
+};
+/** Stored, synced configuration of an `automated` room. */
+interface AutomationMeta {
+    providerId: string;
+    params: Record<string, unknown>;
+    intervalMin: number;
+    schedule?: AutomationSchedule;
+    onOpen?: boolean;
+    enabled: boolean;
+    credential: SealedBlob;
+    botUserId?: string;
+    runOnDeviceId: string | null;
+    lastRunAt: number | null;
+    lastFetchHash?: string | null;
+    lastError: string | null;
+}
+/** A transitional Room shape (used while apps migrate onto the object model). */
+interface Room {
+    id: ID;
+    spaceId: ID;
+    category: string;
+    name: string;
+    kind: RoomKind;
+    topic?: string;
+    unread?: number;
+    mention?: boolean;
+    avatar?: string;
+    automation?: AutomationMeta;
+}
+/** The builtin object types. Custom types ride the same `string` field. */
+type BuiltinObjectType = 'room' | 'category' | 'automation' | 'doc' | 'project' | 'task';
+type ObjectType = BuiltinObjectType | (string & {});
+/** Runtime set of builtin type strings for renderer branching. */
+declare const BUILTIN_OBJECT_TYPES: readonly BuiltinObjectType[];
+/** How an object's content syncs. Builtins infer this; custom types set it explicitly. */
+type ObjectContentKind = 'merge' | 'append' | 'none';
+/** When `type === 'room'`, the room flavour. */
+type RoomSubtype = 'channel' | 'dm' | 'automation';
+/**
+ * One entry in a space's object index (`spaces/{spaceId}/objects/_index`).
+ * Identity + tree position + light metadata ONLY — heavy content (messages, doc
+ * blocks, project event log) lives in a per-object content doc keyed by `id`.
+ */
+interface ObjectNode {
+    id: ID;
+    type: ObjectType;
+    subtype?: RoomSubtype;
+    parentId: ID | null;
+    order: number;
+    title: string;
+    emoji?: string;
+    updatedAt: number;
+    archived?: boolean;
+    automation?: AutomationMeta;
+    contentKind?: ObjectContentKind;
+    meta?: Record<string, unknown>;
+}
+/** The object-index doc: the union-merged list of every object in a space. */
+interface ObjectsIndex {
+    v: 1;
+    objects: ObjectNode[];
+    updatedAt: number;
+}
+
+/**
+ * Identifier helpers — one source for unguessable ids.
+ *
+ * `randomId()` is a CSPRNG-backed 128-bit id (16 random bytes, hex). Use it for
+ * EVERY storage/space/room/object/blob id. Hex output is path-safe and server-safe.
+ */
+declare function randomId(): string;
+/**
+ * Slug for the human part of an id (e.g. `<spaceId>-<slug>-<ts>`). Restricted to
+ * URL-clean `[a-z0-9-]` so the id is safe as both a URL path segment and a
+ * server storage-path leaf (the server's FilesystemObjectStore rejects any key
+ * outside `[a-zA-Z0-9._:@/-]`). Falls back to `'room'` when a name strips to nothing.
+ */
+declare function roomSlug(name: string): string;
+
+/**
+ * Collection path + cap-scope helpers (merged from OctoChat + OctoVault).
+ *
+ * Paths are signed relative to SYNC_BASE; the server mounts the sync router at
+ * root, so they start with /pull or /push. Everything for a space is nested under
+ * `spaces/{spaceId}/…` so the `{spaceId}` segment gates it all uniformly through the
+ * space:owner/space:member enricher, and a single `spaces/{spaceId}/**` member cap
+ * covers a whole space.
+ *
+ * **Generic object collections** — scopes use the `obj*` collection names (the
+ * domain-neutral storage layer both apps migrate onto). App-specific collection
+ * names like `'chat'` are left for the consumer's own `paths.ts` extension until
+ * that app finishes migrating.
+ */
+
+declare const keyringName: (spaceId: string) => string;
+declare const keyringPull: (spaceId: string) => string;
+declare const keyringPush: (spaceId: string) => string;
+declare const attachmentPull: (roomId: string, blobId: string) => string;
+declare const attachmentPush: (roomId: string, blobId: string) => string;
+declare const profilePull: (userId: string) => string;
+declare const profilePush: (userId: string) => string;
+declare const spacesPull: (userId: string) => string;
+declare const spacesPush: (userId: string) => string;
+declare const roomsRegistryPull: (spaceId: string) => string;
+declare const roomsRegistryPush: (spaceId: string) => string;
+declare const objIndexPull: (spaceId: string) => string;
+declare const objIndexPush: (spaceId: string) => string;
+declare const objLogPull: (spaceId: string, objectId: string) => string;
+declare const objLogPush: (spaceId: string, objectId: string) => string;
+declare const objDocPull: (spaceId: string, objectId: string) => string;
+declare const objDocPush: (spaceId: string, objectId: string) => string;
+declare const objectBlobPull: (spaceId: string, blobId: string) => string;
+declare const objectBlobPush: (spaceId: string, blobId: string) => string;
+declare const typesIndexPull: (spaceId: string) => string;
+declare const typesIndexPush: (spaceId: string) => string;
+declare const spaceIndexPull: (shard: "public") => string;
+declare const OBJECT_COLLECTIONS: string[];
+/** Full owner/device access to every space the identity owns. */
+declare function ownerScope(): ScopePreset;
+/**
+ * Member access to one SPACE — its keyring + every channel's messages and
+ * attachments + the room registry, all under `spaces/{spaceId}/**`. One cap
+ * covers current AND future channels.
+ */
+declare function spaceMemberScope(spaceId: string, canWrite: boolean): ScopePreset;
+/**
+ * Personal cap: profile + space registry + device directory + all spaces.
+ * Note: app-specific collections like `'dminbox'` (chat) are NOT included here —
+ * add them in the consumer's own `paths.ts` extension.
+ */
+declare function accountScope(userId: string): ScopePreset;
+/**
+ * The single cap-cert scope granted to a PAIRED (linked) device. Covers both the
+ * object-store client (ownerScope) and the account client (accountScope), deduped,
+ * because a paired device cannot self-mint — it presents one root-signed cap-cert.
+ */
+declare function linkedDeviceScope(userId: string): ScopePreset;
+declare function bytesToHex(b: Uint8Array): string;
+/** The canonical identity derivation: `userId = sha256(edPub)[0:32]` (hex). */
+declare function userIdFromEdPub(edPubHex: string): Promise<string>;
+
+/**
+ * {@link SpaceAccessError} — a GENUINE access denial (not a transient connectivity failure).
+ *
+ * Lives in its own dependency-free module so both the low-level keyring opener
+ * (`client.ts`) and the higher-level space-encryptor cache (`space-encryptor.ts`) can
+ * throw it without an import cycle.
+ */
+declare class SpaceAccessError extends Error {
+    constructor(message: string);
+}
+
+/**
+ * Space access resolver — returns the right (client, encryptor) pair for any
+ * space regardless of whether it is private (E2EE) or public (plaintext).
+ *
+ * Replaces `space-encryptor.ts`. The key invariant: public spaces have
+ * `encryptor: null`; private spaces always have a live `Encryptor`.
+ *
+ * Resolution order (same semantics as the old `getSpaceEncryptor`):
+ *   1. Link entry in the access store → sign requests as the ephemeral identity;
+ *      no keyring, encryptor null.
+ *   2. Member entry → open the keyring as a recipient with the stored cap.
+ *   3. No entry + visibility === 'public' (from `reg`) → owner mode, no keyring.
+ *   4. No entry, private → either owner (open/mint keyring) or SpaceAccessError
+ *      if the space's roster shows we're a member but we're not holding a cap yet.
+ */
+
+interface SpaceAccessHandle {
+    encryptor: Encryptor | null;
+    client: StarfishClient;
+    /** True when opened as the space OWNER (so the caller must seed the room doc). */
+    isOwnerOpen: boolean;
+}
+/** Drop every cached handle (on account switch — keys are per-identity). */
+declare function clearSpaceAccessCache(): void;
+/**
+ * Resolve the right (client, encryptor) for a space, opening and caching on first use.
+ *
+ * `reg` is the space's `_rooms` access record if already known. Pass null when the
+ * caller has not yet read the registry; the resolver will probe if needed.
+ */
+declare function getSpaceAccess(spaceId: string, session: Session, reg: {
+    owner: string | null;
+    members: string[];
+    visibility?: SpaceVisibility;
+} | null): Promise<SpaceAccessHandle>;
+/**
+ * SOFT resolve — never mints a keyring, never throws on missing access.
+ * Returns null when the identity has no usable access for the space yet.
+ */
+declare function buildSpaceAccess(session: Session, spaceId: string, hint?: {
+    visibility?: SpaceVisibility;
+}): Promise<{
+    client: StarfishClient;
+    encryptor: Encryptor | null;
+} | null>;
+
+/**
+ * Unified local access store for spaces this identity has joined.
+ *
+ * Replaces the separate `member-caps.ts` (private spaces) and `pubspace-caps.ts`
+ * (public/link spaces). Two entry kinds:
+ *   - `member`: a member cap-cert (plain JSON, no bearer secret — safe to store
+ *     in the clear). Used for PRIVATE space keyring opens.
+ *   - `link`: an ephemeral-subject cap + the link's Ed25519 private key. Embeds a
+ *     bearer secret so it is SEALED in the synced `_spaces.pubAccess` field before
+ *     leaving this device; the local kv stores it plaintext only on the owning device.
+ *
+ * Two tiers (same as old member-caps): device-local kv (fast, offline) and the
+ * user's synced `_spaces` doc (durable source of truth; merged over local on hydrate).
+ * Keyed PER-USER so multiple accounts on one device never see each other's entries.
+ */
+
+type SpaceAccessEntry = {
+    kind: 'member';
+    cap: string;
+} | {
+    kind: 'link';
+    cap: unknown;
+    key: string;
+    write: boolean;
+};
+type SpaceAccessMap = Record<string, SpaceAccessEntry>;
+/**
+ * Load the active account's space-access entries into memory. Call (and await) on
+ * sign-in and on every account switch, before opening rooms.
+ *
+ * `serverCaps` (private member caps from `_spaces.caps`) and `serverPubAccess`
+ * (sealed link credentials from `_spaces.pubAccess`, already unsealed by the caller)
+ * are merged OVER the local kv cache (server wins).
+ */
+declare function hydrateSpaceAccessStore(userId: string, serverCaps: CapMap, serverLinkAccess: Record<string, {
+    cap: unknown;
+    key: string;
+    write: boolean;
+}>): Promise<void>;
+declare function getSpaceAccessEntry(spaceId: string): SpaceAccessEntry | null;
+declare function saveSpaceAccessEntry(spaceId: string, entry: SpaceAccessEntry): void;
+/** Forget one space's access (on leaving that space). */
+declare function removeSpaceAccessEntry(spaceId: string): void;
+/** A snapshot of the in-memory cache — used by `recoverSpaceAccess` to find entries
+ *  not yet on the server. */
+declare function localSpaceAccessEntries(): SpaceAccessMap;
+/** Build the `CapMap` slice (member entries only) for persisting into `_spaces.caps`. */
+declare function memberCapsFromStore(): CapMap;
+/** Build the `PubAccessMap` slice (link entries already sealed by the caller). */
+declare function linkAccessFromStore(): Record<string, {
+    cap: unknown;
+    key: string;
+    write: boolean;
+}>;
+/** Drop the in-memory cache (on account switch / sign-out). */
+declare function clearSpaceAccessStore(): void;
+
+/** The bucket new/unfiled objects land in, and the fallback a deleted category's
+ *  objects are reassigned to. */
+declare const DEFAULT_CATEGORY = "CHANNELS";
+/** Deterministic category-node id from its name, so two devices that concurrently
+ *  create the SAME category mint the SAME id → the union-merge dedupes them. */
+declare const categoryId: (name: string) => ID;
+/** A node plus its resolved children — the shape a tree view renders. */
+interface ObjectTreeNode extends ObjectNode {
+    depth: number;
+    children: ObjectTreeNode[];
+}
+/** Map a legacy {@link Room} `kind` to the unified room {@link RoomSubtype}. */
+declare function roomKindToSubtype(kind: Room['kind']): RoomSubtype;
+/** Inverse of {@link roomKindToSubtype}. A legacy persisted `'stream'` subtype hits
+ *  the `default` and reads back as a plain `'channel'` (normalization). */
+declare function subtypeToRoomKind(subtype: RoomSubtype | undefined): Room['kind'];
+/** The order value for a new node appended after `siblings`. */
+declare function nextOrder(siblings: ObjectNode[]): number;
+/**
+ * Build the render tree from a flat node list, repairing merge artifacts:
+ *  - **archived** nodes (and their subtrees) are dropped.
+ *  - **orphans** — a `parentId` that is missing or archived — reparent to root.
+ *  - **cycles** — a node reachable from itself via `parentId` — reparent to root.
+ *  - **siblings** sort by {@link compareSiblings} for cross-device determinism.
+ */
+declare function buildTree(nodes: ObjectNode[], includeArchived?: boolean): ObjectTreeNode[];
+/** The root→node trail (inclusive) for breadcrumbs. Returns `[]` if unknown. */
+declare function breadcrumbs(nodes: ObjectNode[], id: ID): ObjectNode[];
+/** The root→parent trail (EXCLUSIVE of the node itself). */
+declare function ancestors(nodes: ObjectNode[], id: ID): ObjectNode[];
+/** The ids of a node and its whole subtree (for cascade-archive). */
+declare function subtreeIds(nodes: ObjectNode[], rootId: ID): Set<ID>;
+interface NewObjectInput {
+    type: ObjectType;
+    subtype?: RoomSubtype;
+    parentId?: ID | null;
+    title: string;
+    emoji?: string;
+    automation?: AutomationMeta;
+    /** Provide to reuse an id (e.g. a room id derived elsewhere); else minted. */
+    id?: ID;
+}
+/** Append a new node under `parentId` at the end of its sibling order. */
+declare function addObject(nodes: ObjectNode[], input: NewObjectInput, now: number): {
+    nodes: ObjectNode[];
+    node: ObjectNode;
+};
+/** Patch a node's mutable metadata (title/emoji/automation), bumping `updatedAt`. */
+declare function patchObject(nodes: ObjectNode[], id: ID, patch: Partial<Pick<ObjectNode, 'title' | 'emoji' | 'automation'>>, now: number): ObjectNode[];
+/** Reparent a node (move in the tree). Rejects making a node its own descendant. */
+declare function reparentObject(nodes: ObjectNode[], id: ID, parentId: ID | null, now: number): ObjectNode[];
+/** Set explicit sibling order (drag-reorder). */
+declare function reorderObjects(nodes: ObjectNode[], orderById: Record<ID, number>, now: number): ObjectNode[];
+/** Cascade-archive a node and its whole subtree (soft delete). */
+declare function archiveObject(nodes: ObjectNode[], id: ID, now: number): ObjectNode[];
+/** The category→rooms grouping the legacy UI consumes. */
+interface AdaptedCategory {
+    name: string;
+    rooms: Room[];
+}
+/**
+ * Project the room/category nodes of an index into the legacy `{ name, rooms }[]`
+ * shape that app UIs still consume. Category nodes become buckets; room nodes become
+ * {@link Room}s grouped under their parent category (or `fallbackCategory` at root).
+ * Returns null when the index holds no room/category nodes yet.
+ *
+ * @deprecated Use the object tree directly once apps complete their migration.
+ */
+declare function objectsToRoomCategories(nodes: ObjectNode[], spaceId: string, fallbackCategory: string): AdaptedCategory[] | null;
+/**
+ * Drop `kind: 'automated'` rooms from a category list (they belong to an Agents
+ * view, not the main room list). A category that held only agents is removed too.
+ *
+ * @deprecated Use the object tree directly once apps complete their migration.
+ */
+declare function excludeAutomatedRooms(categories: AdaptedCategory[]): AdaptedCategory[];
+/** A minimal object descriptor the {@link seedIndexNodes} builder turns into nodes. */
+interface SeedRoom {
+    id: ID;
+    name: string;
+    kind: Room['kind'];
+    category: string;
+}
+/**
+ * Build the initial `ObjectNode[]` for a brand-new space's index: a `category` node
+ * per distinct category and a `room` node per seed object parented under it. Pure +
+ * deterministic (category ids via {@link categoryId}).
+ */
+declare function seedIndexNodes(rooms: SeedRoom[], now: number): ObjectNode[];
+
+/** Owner-set, SHARED space identity, persisted in the `_rooms` registry doc
+ *  (plaintext — NOT E2EE). `image` is a data URI. Both optional for back-compat. */
+interface SpaceMeta {
+    name?: string | null;
+    image?: string | null;
+    visibility?: SpaceVisibility;
+}
+/** A resolved name/image update fanned out so the SpacesProvider adopts a
+ *  freshly-reconciled value without waiting for its next navigation refresh. */
+interface SpaceMetaUpdate {
+    name: string;
+    short: string;
+    image?: string;
+}
+declare function onSpaceMeta(fn: (spaceId: string, meta: SpaceMetaUpdate) => void): () => void;
+declare function broadcastSpaceMeta(spaceId: string, meta: SpaceMetaUpdate): void;
+interface SpacesDoc {
+    spaces: Space[];
+    caps: CapMap;
+    mutes: MutePrefs;
+    reads: ReadPrefs;
+    pubAccess: PubAccessMap;
+    dms: DmMap;
+    quickReactions: string[];
+    archivedDms: ArchivedDms;
+    hash: string | null;
+}
+declare function readSpaces(client: StarfishClient, userId: string): Promise<SpacesDoc>;
+declare function updateSpacesDoc(client: StarfishClient, userId: string, mutator: (cur: {
+    spaces: Space[];
+    caps: CapMap;
+    pubAccess: PubAccessMap;
+}) => {
+    spaces: Space[];
+    caps: CapMap;
+    pubAccess: PubAccessMap;
+}): Promise<void>;
+declare function updateMutesDoc(client: StarfishClient, userId: string, mutator: (cur: MutePrefs) => MutePrefs | null): Promise<void>;
+declare function updateReadsDoc(client: StarfishClient, userId: string, mutator: (cur: ReadPrefs) => ReadPrefs | null): Promise<void>;
+declare function updateDmsDoc(client: StarfishClient, userId: string, mutator: (cur: DmMap) => DmMap | null): Promise<void>;
+declare function updateQuickReactionsDoc(client: StarfishClient, userId: string, mutator: (cur: string[]) => string[] | null): Promise<void>;
+declare function updateArchivedDmsDoc(client: StarfishClient, userId: string, mutator: (cur: ArchivedDms) => ArchivedDms | null): Promise<void>;
+declare function setDmMapping(client: StarfishClient, userId: string, peerUserId: string, spaceId: string): Promise<void>;
+declare function writeSpaces(client: StarfishClient, userId: string, spaces: Space[], _hash: string | null): Promise<void>;
+declare function reorderSpaces(client: StarfishClient, userId: string, order: string[]): Promise<void>;
+declare function normalizeCategories(rooms: Room[], stored: unknown): string[];
+declare function readRooms(client: StarfishClient, spaceId: string): Promise<{
+    owner: string | null;
+    members: string[];
+    visibility: SpaceVisibility | null;
+    name: string | null;
+    image: string | null;
+    hash: string | null;
+}>;
+declare function writeRooms(client: StarfishClient, spaceId: string, owner: string, members: string[], hash: string | null, meta?: SpaceMeta): Promise<void>;
+declare function addSpaceMember(client: StarfishClient, spaceId: string, ownerUserId: string, memberUserId: string): Promise<void>;
+/** Remove a member from the space roster (used for link revocation). */
+declare function removeSpaceMember(client: StarfishClient, spaceId: string, memberUserId: string): Promise<void>;
+declare function addJoinedSpace(client: StarfishClient, userId: string, space: Space): Promise<void>;
+declare function addJoinedSpaceWithCap(client: StarfishClient, userId: string, space: Space, capJson: string): Promise<void>;
+declare function addJoinedSpaceWithLinkAccess(client: StarfishClient, userId: string, space: Space, sealed: SealedBlob): Promise<void>;
+/**
+ * Create a new space owned by the identity. Seeds ONE generic `general` object node
+ * into the object index (encrypted for private, plaintext for public).
+ *
+ * `opts.visibility` defaults to `'private'`.
+ */
+declare function createSpace(session: Session, name: string, opts?: {
+    visibility?: SpaceVisibility;
+}): Promise<Space>;
+declare class CategoryError extends Error {
+}
+declare function reconcileSpaceMeta(client: StarfishClient, userId: string, spaceId: string, shared: SpaceMeta, knownSpaces?: Space[]): Promise<void>;
+
+interface JoinRequest {
+    edPub: string;
+    kemPub: string;
+    userId: string;
+}
+declare function makeJoinRequest(session: Session): string;
+/**
+ * Owner-side: add a recipient's KEM key to a SPACE keyring (one keyring → every
+ * object in the space). Reused by {@link inviteToSpace} and by device pairing.
+ */
+declare function addDeviceToSpaceKeyring(session: Session, spaceId: string, recipient: {
+    kemPub: string;
+    userId: string;
+}): Promise<void>;
+/**
+ * Owner: invite an identity into a PRIVATE space. Adds them to the keyring, records
+ * them in the roster, and mints a single space-scoped member cap.
+ * Returns the invite bundle JSON.
+ */
+declare function inviteToSpace(session: Session, spaceId: string, requestJson: string, canWrite?: boolean, spaceName?: string): Promise<string>;
+/**
+ * Invitee: accept a PRIVATE space invite — verify keyring access, store the cap,
+ * and register the space. Returns the joined space.
+ */
+declare function acceptSpaceInvite(session: Session, inviteJson: string): Promise<Space>;
+/** A space invite link token (v:1, no ownerId — derive from cap.iss instead). */
+interface SpaceInviteLinkToken {
+    v: 1;
+    spaceId: string;
+    spaceName: string;
+    cap: unknown;
+    /** The throwaway ephemeral subject's Ed25519 private key (hex). */
+    key: string;
+    write: boolean;
+}
+declare function encodeSpaceInviteLink(origin: string, token: SpaceInviteLinkToken): string;
+declare function decodeSpaceInviteLink(fragment: string): SpaceInviteLinkToken;
+/**
+ * Owner: create a shareable invite link for a PUBLIC space.
+ *
+ * Mints an ephemeral Ed/KEM keypair, adds its userId to the roster (so the server
+ * grants `space:member` to any bearer), and encodes the private key + cap in the URL.
+ * Anyone with the link can join; revoke by calling `removeSpaceMember(ephemeralUserId)`.
+ */
+declare function createSpaceInviteLink(session: Session, spaceId: string, spaceName: string, write: boolean, origin: string): Promise<{
+    token: SpaceInviteLinkToken;
+    link: string;
+}>;
+/**
+ * Any user: join a PUBLIC space by redeeming an invite link token.
+ * Stores the link credential locally and seals it into the synced `_spaces` doc.
+ */
+declare function joinSpaceByLink(session: Session, token: SpaceInviteLinkToken): Promise<Space>;
+/**
+ * Single sign-in hydration: merges server-side caps (plaintext member caps from
+ * `_spaces.caps`) and sealed link access (from `_spaces.pubAccess`) into the
+ * unified space-access store. Call once on sign-in / account switch.
+ * Backfills any local-only entries to the server.
+ */
+declare function recoverSpaceAccess(session: Session, server: {
+    caps: Record<string, string>;
+    pubAccess: Record<string, SealedBlob>;
+}): Promise<void>;
+
+/**
+ * Pull + (private: decrypt) + project a space's object index into the legacy
+ * `{ rooms, categories }` shape. `encryptor` is null for a PUBLIC space.
+ * Returns null on failure or an empty index.
+ */
+declare function readIndexRooms(client: StarfishClient, encryptor: Encryptor | null, indexPath: string, spaceId: string): Promise<{
+    rooms: Room[];
+    categories: string[];
+} | null>;
+/**
+ * Read a space's index rooms + categories, resolving access automatically.
+ * Pass `reg` (from `readRooms`) so the accessor picks the right auth mode.
+ */
+declare function readSpaceIndexRooms(session: Session, spaceId: string, reg: {
+    owner: string | null;
+    members: string[];
+    visibility?: SpaceVisibility;
+}): Promise<{
+    rooms: Room[];
+    categories: string[];
+} | null>;
+/** SOFT read — never throws, never mints. Returns an empty array on any failure. */
+declare function readSpaceRooms(session: Session, spaceId: string, hint?: {
+    visibility?: SpaceVisibility;
+}): Promise<Room[]>;
+/**
+ * Write the create-time seed into a space's index doc with an already-open access handle.
+ * Accepts a nullable encryptor — plaintext push when null (public spaces).
+ * Idempotent: a no-op if the index doc already exists (either encrypted or plaintext).
+ */
+declare function pushIndexSeed(client: StarfishClient, encryptor: Encryptor | null, spaceId: string, rooms: SeedRoom[]): Promise<void>;
+/**
+ * Seed a brand-new space's index as the OWNER.
+ * For private spaces: opens (minting if needed) the space keyring.
+ * For public spaces: pushes plaintext nodes.
+ */
+declare function seedSpaceObjectIndex(session: Session, spaceId: string, rooms: SeedRoom[], opts?: {
+    visibility?: SpaceVisibility;
+}): Promise<void>;
+/**
+ * Headless read-modify-write of a space's unified OBJECT INDEX. Works for both
+ * private (encrypt round-trip) and public (plaintext) spaces. Retries up to 3 times
+ * on ConflictError.
+ */
+declare function updateObjectIndex(session: Session, spaceId: string, mutator: (nodes: ObjectNode[], now: number) => ObjectNode[] | null, reg?: {
+    owner: string | null;
+    members: string[];
+    visibility?: SpaceVisibility;
+} | null): Promise<void>;
+
+/** The QR-payload prefix this SDK uses. Kept distinct from `octochat-pair:` so apps
+ *  can route QR payloads to the correct handler during their migration window. */
+declare const PAIR_PREFIX = "octospaces-pair:";
+/** Existing device: provision + PIN-seal a new device, publish to rendezvous, return the QR payload. */
+declare function startDevicePairing(session: Session, pin: string): Promise<string>;
+interface PairResult {
+    userId: string;
+    fingerprint: string;
+    deviceKeys: DeviceKeys;
+    capCert: CapCert;
+}
+/** New device: fetch the sealed blob by nonce, open with PIN, validate the bundle. */
+declare function completeDevicePairing(payload: string, pin: string): Promise<PairResult>;
+
+/**
+ * The app's offline-first read cache for every {@link StarfishClient}.
+ *
+ * Backs the SDK's {@link PullCache} (read-through pull cache) with the kv layer
+ * (localStorage on web, AsyncStorage on native). When a client is built with this
+ * cache, every successful structured `pull()` is written through, and a pull that
+ * fails because the transport is unreachable falls back to the last-synced snapshot.
+ *
+ * SECURITY: the SDK caches the RAW server response only. For E2E collections that
+ * payload is the SEALED ciphertext the server holds — never the decrypted form —
+ * so this cache is ciphertext-at-rest by construction.
+ */
+
+/**
+ * Max age for a cached snapshot before it's treated as a miss. Generous (30 days)
+ * because for an offline-first app any last-synced data beats none.
+ */
+declare const PULL_CACHE_MAX_AGE_MS: number;
+/** The shared app-wide pull cache (one instance, reused across every client). */
+declare function pullCache(): PullCache;
+
+/** Persist a freshly-read profile (fire-and-forget). */
+declare function cacheProfile(userId: string, profile: PublicProfile): void;
+/** Last-known profile for a user, or null if never cached / unparseable. */
+declare function loadCachedProfile(userId: string): Promise<PublicProfile | null>;
+
+/**
+ * A `fetch` wrapper that bounds the CONNECT/TTFB phase only.
+ *
+ * Aborts a request that hasn't RESPONDED within {@link CONNECT_TIMEOUT_MS}, turning
+ * an opaque infinite spinner into a normal rejection the open path can surface as a
+ * retriable error. Clears the timer once response headers arrive, so it bounds ONLY
+ * the connect phase — body downloads and long-lived streams stay unbounded.
+ */
+declare const CONNECT_TIMEOUT_MS = 12000;
+declare function fetchWithTimeout(timeoutMs?: number): typeof fetch;
+
+/**
+ * A chunked base64 provider for the Starfish platform.
+ *
+ * The SDK's default web encoder is `btoa(String.fromCharCode(...data))`, which
+ * spreads the entire byte array into one call — a multi-megabyte attachment
+ * overflows the argument/stack limit and throws "Maximum call stack size exceeded".
+ * This provider walks the bytes in fixed windows instead, so it scales to large blobs.
+ *
+ * Prefers the platform's own `btoa`/`atob` (web) and falls back to a pure
+ * implementation where they're absent (Hermes/native).
+ */
+
+/** Spread-free, chunked base64 — a drop-in for the SDK's default provider. */
+declare const starfishBase64: Base64Provider;
+
+/**
+ * base64url for link fragments (UTF-8 safe, web + native) — the encoding both
+ * invitation-link kinds ride in a URL `#fragment`. No padding, `+/` → `-_`.
+ */
+declare function toBase64Url(json: string): string;
+declare function fromBase64Url(b64url: string): string;
+
+export { type AdaptedCategory, type ArchivedDms, type AutomationMeta, BUILTIN_OBJECT_TYPES, CONNECT_TIMEOUT_MS, type CapMap, CategoryError, DEFAULT_CATEGORY, type DerivedIdentity, type DeviceKeys, type DmMap, type ID, type JoinRequest, type KvAdapter, type LinkedIdentity, type MutePrefs, type NewObjectInput, OBJECT_COLLECTIONS, type ObjectContentKind, type ObjectNode, type ObjectTreeNode, type ObjectType, type ObjectsIndex, type OctoSpacesConfig, PAIR_PREFIX, PULL_CACHE_MAX_AGE_MS, type PairResult, type PasskeyEnrollment, type PersistedSession, type PubAccessMap, type PublicProfile, type ReadPrefs, type Room, type RoomKind, type RoomSubtype, type SealedBlob, type SeedLock, type SeedRoom, type Session, type Space, type SpaceAccessEntry, SpaceAccessError, type SpaceAccessHandle, type SpaceAccessMap, type SpaceInviteLinkToken, type SpaceMeta, type SpaceMetaUpdate, type SpaceVisibility, type UnlockMethod, type Vault, type VaultLoad, acceptSpaceInvite, accountScope, addDeviceToSpaceKeyring, addJoinedSpace, addJoinedSpaceWithCap, addJoinedSpaceWithLinkAccess, addObject, addSpaceMember, ancestors, archiveObject, attachmentPull, attachmentPush, breadcrumbs, broadcastSpaceMeta, buildAuthHeaders, buildEncryptor, buildLinkedSession, buildSession, buildSpaceAccess, buildTree, bytesToHex, cacheProfile, capProviderFor, categoryId, clearSpaceAccessCache, clearSpaceAccessStore, completeDevicePairing, configureKv, configureOctoSpaces, createSpace, createSpaceInviteLink, decodeSpaceInviteLink, deriveSession, encodeSpaceInviteLink, ensureProfileKeys, ensurePseudo, excludeAutomatedRooms, fetchWithTimeout, fingerprintFromUserId, fromBase64Url, generateSeedWords, getSharedSpacesNamespace, getSpaceAccess, getSpaceAccessEntry, getSyncBase, getSyncNamespace, getSyncPrefix, hydrateSpaceAccessStore, inviteToSpace, isValidSeed, joinSpaceByLink, keyringName, keyringPull, keyringPush, kvGet, kvRemove, kvSet, linkAccessFromStore, linkedDeviceScope, loadCachedProfile, localSpaceAccessEntries, makeClient, makeJoinRequest, memberCapsFromStore, nextOrder, normalizeCategories, objDocPull, objDocPush, objIndexPull, objIndexPush, objLogPull, objLogPush, objectBlobPull, objectBlobPush, objectsToRoomCategories, onSpaceMeta, openEncryptor, ownerEnsureKeyring, ownerScope, ownerTrustedAdders, patchObject, profilePull, profilePush, pullCache, pushIndexSeed, randomId, readIndexRooms, readProfile, readProfiles, readPseudo, readRooms, readSpaceIndexRooms, readSpaceRooms, readSpaces, reconcileSpaceMeta, recoverSpaceAccess, removeSpaceAccessEntry, removeSpaceMember, reorderObjects, reorderSpaces, reparentObject, roomKindToSubtype, roomSlug, roomsRegistryPull, roomsRegistryPush, rootIdentityOf, saveSpaceAccessEntry, sealToRecipient, sealToSelf, seedIndexNodes, seedSpaceObjectIndex, setDmMapping, spaceIndexPull, spaceMemberScope, spacesPull, spacesPush, starfishBase64, startDevicePairing, subtreeIds, subtypeToRoomKind, toBase64Url, typesIndexPull, typesIndexPush, unsealFromRecipient, unsealFromSelf, updateArchivedDmsDoc, updateDmsDoc, updateMutesDoc, updateObjectIndex, updateQuickReactionsDoc, updateReadsDoc, updateSpacesDoc, userIdFromEdPub, writeProfile, writePseudo, writeRooms, writeSpaces };