@drakkar.software/octospaces-sdk 0.1.0

package/dist/platform/index.native.js

@@ -0,0 +1,106 @@
+// src/platform/platform.native.ts
+import { install } from "react-native-quick-crypto";
+import { configurePlatform } from "@drakkar.software/starfish-protocol";
+
+// src/sync/base64.ts
+var CHUNK = 24576;
+var ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+var REVERSE = (() => {
+  const table = new Int16Array(128).fill(-1);
+  for (let i = 0; i < ALPHABET.length; i++) table[ALPHABET.charCodeAt(i)] = i;
+  return table;
+})();
+var nativeCodec = typeof globalThis !== "undefined" && typeof globalThis.btoa === "function" && typeof globalThis.atob === "function";
+function encodeViaBtoa(data) {
+  let binary = "";
+  for (let i = 0; i < data.length; i += CHUNK) {
+    binary += String.fromCharCode.apply(null, data.subarray(i, i + CHUNK));
+  }
+  return globalThis.btoa(binary);
+}
+function decodeViaAtob(encoded) {
+  const binary = globalThis.atob(encoded);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function encodePure(data) {
+  const len = data.length;
+  const full = len - len % 3;
+  const parts = [];
+  for (let start = 0; start < full; start += CHUNK) {
+    const stop = Math.min(start + CHUNK, full);
+    let s = "";
+    for (let i = start; i < stop; i += 3) {
+      const n = data[i] << 16 | data[i + 1] << 8 | data[i + 2];
+      s += ALPHABET[n >> 18 & 63] + ALPHABET[n >> 12 & 63] + ALPHABET[n >> 6 & 63] + ALPHABET[n & 63];
+    }
+    parts.push(s);
+  }
+  if (len - full === 1) {
+    const n = data[full] << 16;
+    parts.push(ALPHABET[n >> 18 & 63] + ALPHABET[n >> 12 & 63] + "==");
+  } else if (len - full === 2) {
+    const n = data[full] << 16 | data[full + 1] << 8;
+    parts.push(ALPHABET[n >> 18 & 63] + ALPHABET[n >> 12 & 63] + ALPHABET[n >> 6 & 63] + "=");
+  }
+  return parts.join("");
+}
+function decodePure(encoded) {
+  let validLen = encoded.length;
+  while (validLen > 0 && encoded.charCodeAt(validLen - 1) === 61) validLen--;
+  const out = new Uint8Array(validLen * 3 >> 2);
+  let o = 0, buf = 0, bits = 0;
+  for (let i = 0; i < validLen; i++) {
+    const code = encoded.charCodeAt(i);
+    const v = code < 128 ? REVERSE[code] : -1;
+    if (v < 0) continue;
+    buf = buf << 6 | v;
+    bits += 6;
+    if (bits >= 8) {
+      bits -= 8;
+      out[o++] = buf >> bits & 255;
+    }
+  }
+  return o === out.length ? out : out.subarray(0, o);
+}
+var starfishBase64 = nativeCodec ? { encode: encodeViaBtoa, decode: decodeViaAtob } : { encode: encodePure, decode: decodePure };
+
+// src/platform/platform.native.ts
+install();
+function configureStarfishPlatform() {
+  configurePlatform({ base64: starfishBase64 });
+}
+
+// src/platform/kv.native.ts
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+// src/core/adapters.ts
+var kv = null;
+function configureKv(adapter) {
+  kv = adapter;
+}
+
+// src/platform/kv.native.ts
+function kvGet(key) {
+  return AsyncStorage.getItem(key).catch(() => null);
+}
+function kvSet(key, value) {
+  return AsyncStorage.setItem(key, value).catch(() => {
+  });
+}
+function kvRemove(key) {
+  return AsyncStorage.removeItem(key).catch(() => {
+  });
+}
+function configureNativeKv() {
+  configureKv({ get: kvGet, set: kvSet, remove: kvRemove });
+}
+export {
+  configureNativeKv,
+  configureStarfishPlatform,
+  kvGet,
+  kvRemove,
+  kvSet
+};
+//# sourceMappingURL=index.native.js.map

package/dist/platform/index.native.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/platform/platform.native.ts","../../src/sync/base64.ts","../../src/platform/kv.native.ts","../../src/core/adapters.ts"],"sourcesContent":["/**\n * Native crypto setup. Installs react-native-quick-crypto to patch\n * `globalThis.crypto` and `globalThis.Buffer` before any SDK call.\n * Requires a custom dev build (not Expo Go) + New Architecture.\n */\n// eslint-disable-next-line @typescript-eslint/ban-ts-comment\n// @ts-ignore — optional peer dep; only present in native builds\nimport { install } from 'react-native-quick-crypto';\nimport { configurePlatform } from '@drakkar.software/starfish-protocol';\nimport { starfishBase64 } from '../sync/base64.js';\n\ninstall();\n\nexport function configureStarfishPlatform(): void {\n  configurePlatform({ base64: starfishBase64 });\n}\n","/**\n * A chunked base64 provider for the Starfish platform.\n *\n * The SDK's default web encoder is `btoa(String.fromCharCode(...data))`, which\n * spreads the entire byte array into one call — a multi-megabyte attachment\n * overflows the argument/stack limit and throws \"Maximum call stack size exceeded\".\n * This provider walks the bytes in fixed windows instead, so it scales to large blobs.\n *\n * Prefers the platform's own `btoa`/`atob` (web) and falls back to a pure\n * implementation where they're absent (Hermes/native).\n */\nimport type { Base64Provider } from '@drakkar.software/starfish-protocol';\n\nconst CHUNK = 0x6000; // 24 576 bytes — multiple of 3, well under V8's apply limit\n\nconst ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';\n\nconst REVERSE = (() => {\n  const table = new Int16Array(128).fill(-1);\n  for (let i = 0; i < ALPHABET.length; i++) table[ALPHABET.charCodeAt(i)] = i;\n  return table;\n})();\n\nconst nativeCodec =\n  typeof globalThis !== 'undefined' &&\n  typeof globalThis.btoa === 'function' &&\n  typeof globalThis.atob === 'function';\n\nfunction encodeViaBtoa(data: Uint8Array): string {\n  let binary = '';\n  for (let i = 0; i < data.length; i += CHUNK) {\n    binary += String.fromCharCode.apply(null, data.subarray(i, i + CHUNK) as unknown as number[]);\n  }\n  return globalThis.btoa(binary);\n}\n\nfunction decodeViaAtob(encoded: string): Uint8Array {\n  const binary = globalThis.atob(encoded);\n  const out = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);\n  return out;\n}\n\nfunction encodePure(data: Uint8Array): string {\n  const len = data.length;\n  const full = len - (len % 3);\n  const parts: string[] = [];\n  for (let start = 0; start < full; start += CHUNK) {\n    const stop = Math.min(start + CHUNK, full);\n    let s = '';\n    for (let i = start; i < stop; i += 3) {\n      const n = (data[i] << 16) | (data[i + 1] << 8) | data[i + 2];\n      s += ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + ALPHABET[n & 63];\n    }\n    parts.push(s);\n  }\n  if (len - full === 1) {\n    const n = data[full] << 16;\n    parts.push(ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + '==');\n  } else if (len - full === 2) {\n    const n = (data[full] << 16) | (data[full + 1] << 8);\n    parts.push(ALPHABET[(n >> 18) & 63] + ALPHABET[(n >> 12) & 63] + ALPHABET[(n >> 6) & 63] + '=');\n  }\n  return parts.join('');\n}\n\nfunction decodePure(encoded: string): Uint8Array {\n  let validLen = encoded.length;\n  while (validLen > 0 && encoded.charCodeAt(validLen - 1) === 61) validLen--;\n  const out = new Uint8Array((validLen * 3) >> 2);\n  let o = 0, buf = 0, bits = 0;\n  for (let i = 0; i < validLen; i++) {\n    const code = encoded.charCodeAt(i);\n    const v = code < 128 ? REVERSE[code] : -1;\n    if (v < 0) continue;\n    buf = (buf << 6) | v;\n    bits += 6;\n    if (bits >= 8) {\n      bits -= 8;\n      out[o++] = (buf >> bits) & 0xff;\n    }\n  }\n  return o === out.length ? out : out.subarray(0, o);\n}\n\n/** Spread-free, chunked base64 — a drop-in for the SDK's default provider. */\nexport const starfishBase64: Base64Provider = nativeCodec\n  ? { encode: encodeViaBtoa, decode: decodeViaAtob }\n  : { encode: encodePure, decode: decodePure };\n","/** Native KV adapter — backed by `@react-native-async-storage/async-storage`. */\n// eslint-disable-next-line @typescript-eslint/ban-ts-comment\n// @ts-ignore — optional peer dep; the native bundle is only loaded on RN targets.\nimport AsyncStorage from '@react-native-async-storage/async-storage';\n\nimport { configureKv } from '../core/adapters.js';\n\nexport function kvGet(key: string): Promise<string | null> {\n  return (AsyncStorage as { getItem(k: string): Promise<string | null> }).getItem(key).catch(() => null);\n}\n\nexport function kvSet(key: string, value: string): Promise<void> {\n  return (AsyncStorage as { setItem(k: string, v: string): Promise<void> }).setItem(key, value).catch(() => {});\n}\n\nexport function kvRemove(key: string): Promise<void> {\n  return (AsyncStorage as { removeItem(k: string): Promise<void> }).removeItem(key).catch(() => {});\n}\n\n/** Call once at app boot (native). Wires `AsyncStorage` into the SDK. */\nexport function configureNativeKv(): void {\n  configureKv({ get: kvGet, set: kvSet, remove: kvRemove });\n}\n","/**\n * Platform adapters the headless SDK needs the host app to provide.\n *\n * The SDK can't do Metro `.native.ts` file-extension resolution and must not bind\n * to localStorage / AsyncStorage / SecureStore directly, so the host injects a\n * key/value store at boot via {@link configureKv}. This holds account-scoped state\n * the SDK persists offline (joined-space member caps, the public-space access map,\n * read marks, mutes, profile/pull caches).\n */\n\n/** Async key/value store — web `localStorage`, native `AsyncStorage`, etc. */\nexport interface KvAdapter {\n  get(key: string): Promise<string | null>;\n  set(key: string, value: string): Promise<void>;\n  remove(key: string): Promise<void>;\n}\n\nlet kv: KvAdapter | null = null;\n\n/** Install the host's key/value store. Call once at app boot. */\nexport function configureKv(adapter: KvAdapter): void {\n  kv = adapter;\n}\n\n/** The configured KV store, or throw if the host never called {@link configureKv}. */\nexport function getKv(): KvAdapter {\n  if (!kv) throw new Error('octospaces-sdk: configureKv() not called — wire it at app boot.');\n  return kv;\n}\n\n// Free-function shims matching the historical `kv` module surface.\nexport const kvGet = (key: string): Promise<string | null> => getKv().get(key);\nexport const kvSet = (key: string, value: string): Promise<void> => getKv().set(key, value);\nexport const kvRemove = (key: string): Promise<void> => getKv().remove(key);\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@drakkar.software/octospaces-sdk",
+  "version": "0.1.0",
+  "description": "Shared headless spaces core — identity, registry, objects, and sync plumbing.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./platform": {
+      "react-native": "./dist/platform/index.native.js",
+      "import": "./dist/platform/index.js",
+      "types": "./dist/platform/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@noble/curves": "^2.2.0",
+    "@noble/hashes": "^2.2.0",
+    "@scure/bip39": "^2.0.0",
+    "hash-wasm": "^4.12.0"
+  },
+  "peerDependencies": {
+    "@drakkar.software/starfish-client": ">=3.0.0-alpha.27",
+    "@drakkar.software/starfish-identities": ">=3.0.0-alpha.27",
+    "@drakkar.software/starfish-keyring": ">=3.0.0-alpha.27",
+    "@drakkar.software/starfish-protocol": ">=3.0.0-alpha.27",
+    "@drakkar.software/starfish-sharing": ">=3.0.0-alpha.27"
+  },
+  "devDependencies": {
+    "@drakkar.software/starfish-client": "3.0.0-alpha.27",
+    "@drakkar.software/starfish-identities": "3.0.0-alpha.27",
+    "@drakkar.software/starfish-keyring": "3.0.0-alpha.27",
+    "@drakkar.software/starfish-protocol": "3.0.0-alpha.27",
+    "@drakkar.software/starfish-sharing": "3.0.0-alpha.27",
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "~6.0.3",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "tsc --noEmit"
+  }
+}

package/src/core/adapters.ts

@@ -0,0 +1,34 @@
+/**
+ * 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. */
+export interface KvAdapter {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
+}
+
+let kv: KvAdapter | null = null;
+
+/** Install the host's key/value store. Call once at app boot. */
+export function configureKv(adapter: KvAdapter): void {
+  kv = adapter;
+}
+
+/** The configured KV store, or throw if the host never called {@link configureKv}. */
+export function getKv(): KvAdapter {
+  if (!kv) throw new Error('octospaces-sdk: configureKv() not called — wire it at app boot.');
+  return kv;
+}
+
+// Free-function shims matching the historical `kv` module surface.
+export const kvGet = (key: string): Promise<string | null> => getKv().get(key);
+export const kvSet = (key: string, value: string): Promise<void> => getKv().set(key, value);
+export const kvRemove = (key: string): Promise<void> => getKv().remove(key);

package/src/core/config.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.
+ */
+export 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;
+}
+
+let cfg: OctoSpacesConfig | null = null;
+
+/** Configure the SDK. Call once at app boot before any sync/identity API. */
+export function configureOctoSpaces(config: OctoSpacesConfig): void {
+  // Guard against the common mistake of passing `namespace` (wrong key) instead of
+  // `syncNamespace`. TypeScript's excess-property check is bypassed when the config
+  // is assembled via a conditional spread, so the wrong key would be silently ignored.
+  if ('namespace' in config && !config.syncNamespace) {
+    throw new Error(
+      `octospaces-sdk: configureOctoSpaces received "namespace" — did you mean "syncNamespace"?`,
+    );
+  }
+  const ns = (config.syncNamespace ?? '').trim();
+  if (ns !== '' && !/^[A-Za-z0-9_-]+$/.test(ns)) {
+    throw new Error(`octospaces-sdk: syncNamespace must be a bare name ([A-Za-z0-9_-]+), got "${ns}"`);
+  }
+  const sharedNs = (config.sharedSpacesNamespace ?? '').trim();
+  if (sharedNs !== '' && !/^[A-Za-z0-9_-]+$/.test(sharedNs)) {
+    throw new Error(`octospaces-sdk: sharedSpacesNamespace must be a bare name ([A-Za-z0-9_-]+), got "${sharedNs}"`);
+  }
+  cfg = {
+    ...config,
+    syncNamespace: ns || undefined,
+    sharedSpacesNamespace: sharedNs || undefined,
+  };
+}
+
+function req(): OctoSpacesConfig {
+  if (!cfg) throw new Error('octospaces-sdk: configureOctoSpaces() not called — wire it at app boot.');
+  return cfg;
+}
+
+/** Starfish sync server base URL. */
+export const getSyncBase = (): string => req().syncBase;
+/** Bare namespace name (or `undefined` for a root-mounted server). */
+export const getSyncNamespace = (): string | undefined => req().syncNamespace;
+/** Namespaced path prefix (`/v1/<namespace>`, or `''` locally). */
+export const getSyncPrefix = (): string => {
+  const ns = req().syncNamespace;
+  return ns ? `/v1/${ns}` : '';
+};
+/** Optional separate namespace for shared-spaces storage. `undefined` means use the default namespace. */
+export const getSharedSpacesNamespace = (): string | undefined => cfg?.sharedSpacesNamespace;
+/** Live change-event SSE endpoint. */
+export const getEventsUrl = (): string => req().eventsUrl ?? `${getSyncBase()}${getSyncPrefix()}/events`;
+/** Public web origin (right-trimmed of trailing slashes; `''` by default). */
+export const getWebBase = (): string => (req().webBase ?? '').replace(/\/+$/, '');
+/** Callback to invoke when a background Starfish revalidation succeeds. */
+export const getOnServerReachable = (): (() => void) | undefined => cfg?.onServerReachable;

package/src/core/ids.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { randomId, roomSlug } from './ids.js';
+
+describe('randomId', () => {
+  it('returns a non-empty string', () => {
+    expect(typeof randomId()).toBe('string');
+    expect(randomId().length).toBeGreaterThan(0);
+  });
+
+  it('returns unique values', () => {
+    const ids = new Set(Array.from({ length: 100 }, () => randomId()));
+    expect(ids.size).toBe(100);
+  });
+
+  it('contains only URL-safe characters', () => {
+    for (let i = 0; i < 50; i++) {
+      expect(randomId()).toMatch(/^[A-Za-z0-9_-]+$/);
+    }
+  });
+});
+
+describe('roomSlug', () => {
+  it('lowercases and replaces spaces with hyphens', () => {
+    expect(roomSlug('General Channel')).toBe('general-channel');
+  });
+
+  it('strips non-alphanumeric characters', () => {
+    expect(roomSlug('Off-Topic!')).toBe('off-topic');
+  });
+
+  it('handles empty string — returns a non-empty fallback or empty string', () => {
+    // roomSlug may return a fallback (e.g. 'room') for empty input.
+    const result = roomSlug('');
+    expect(typeof result).toBe('string');
+  });
+
+  it('returns lowercase for single word', () => {
+    expect(roomSlug('General')).toBe('general');
+  });
+
+  it('trims leading/trailing hyphens', () => {
+    const slug = roomSlug('  hello  ');
+    expect(slug).not.toMatch(/^-|-$/);
+  });
+});

package/src/core/ids.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+export function randomId(): string {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  let s = '';
+  for (const b of bytes) s += b.toString(16).padStart(2, '0');
+  return s;
+}
+
+/**
+ * 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.
+ */
+export function roomSlug(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .slice(0, 40) || 'room'
+  );
+}

package/src/core/space-access-error.ts

@@ -0,0 +1,13 @@
+/**
+ * {@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.
+ */
+export class SpaceAccessError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SpaceAccessError';
+  }
+}

package/src/core/storage-types.ts

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+import type { BootstrapOrigin } from '@drakkar.software/starfish-identities';
+import type { CapCert } from '@drakkar.software/starfish-protocol';
+
+import type { DeviceKeys } from '../sync/client.js';
+
+/**
+ * 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.
+ */
+export interface DerivedIdentity {
+  userId: string;
+  keys: DeviceKeys;
+}
+
+/** The recovery seed + display name — the minimum needed to re-derive an identity. */
+export 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).
+ */
+export interface Vault {
+  accounts: PersistedSession[];
+  activeId: string;
+}
+
+/** Ways the web-persisted seed can be unlocked. */
+export type UnlockMethod = 'pin' | 'passkey';
+
+/** A registered passkey + the PRF secret used to seal the seed for it. */
+export interface PasskeyEnrollment {
+  credentialId: string;
+  salt: string;
+  secretHex: string;
+}
+
+/** How to lock the seed when persisting it (web only). */
+export 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.
+ */
+export type VaultLoad =
+  | { kind: 'none' }
+  | { kind: 'ready'; vault: Vault }
+  | { kind: 'locked'; methods: UnlockMethod[] }
+  | { kind: 'error'; error: unknown };

package/src/core/types.ts

@@ -0,0 +1,162 @@
+/**
+ * Domain model for OctoSpaces — space + object types shared by the SDK and any UI.
+ *
+ * A space's contents are modelled as a tree of typed {@link ObjectNode}s stored in
+ * a union-merged index at `spaces/{spaceId}/objects/_index`. Everything —  rooms,
+ * categories, docs, projects, tasks — is an `ObjectNode` discriminated by `type`.
+ * Apps extend the model by adding their own `ObjectType` strings; the generic
+ * primitives here are app-neutral.
+ */
+
+// Re-export SealedBlob so consumers get it from one place.
+export type { SealedBlob } from '../sync/account-seal.js';
+
+export type ID = string;
+
+/** A user's presence indicator. The theme maps each to a color (app-side). */
+export type PresenceStatus = 'online' | 'away' | 'dnd' | 'offline';
+
+/** A security item's verification state. The theme maps each to a color (app-side). */
+export type VerificationLevel = 'verified' | 'pending' | 'unverified';
+
+/** 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. */
+export 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`. */
+export type PubAccessMap = Record<string, import('../sync/account-seal.js').SealedBlob>;
+
+/** Maps a DM peer's userId → the private DM-space id shared with them. */
+export type DmMap = Record<string, string>;
+
+/** The set of DM-space ids the user has archived (hidden from the DM list). */
+export type ArchivedDms = Record<string, true>;
+
+/** A mute entry. `true` = muted indefinitely; a number = muted UNTIL that epoch-ms instant. */
+export type MuteValue = true | number;
+
+/** Per-user mute preferences: which rooms and which whole spaces are silenced. */
+export 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. */
+export type ReadValue = number;
+
+/** Per-user read marks — the timestamp each room was last read. */
+export interface ReadPrefs {
+  rooms: Record<string, ReadValue>;
+}
+
+/** Whether a space encrypts its content client-side. */
+export type SpaceVisibility = 'private' | 'public';
+
+export 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. */
+export type RoomKind = 'channel' | 'dm' | 'automated';
+
+/** Scheduled-fetch cadence for automated rooms. */
+export 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. */
+export interface AutomationMeta {
+  providerId: string;
+  params: Record<string, unknown>;
+  intervalMin: number;
+  schedule?: AutomationSchedule;
+  onOpen?: boolean;
+  enabled: boolean;
+  credential: import('../sync/account-seal.js').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). */
+export interface Room {
+  id: ID;
+  spaceId: ID;
+  category: string;
+  name: string;
+  kind: RoomKind;
+  topic?: string;
+  unread?: number;
+  mention?: boolean;
+  avatar?: string;
+  automation?: AutomationMeta;
+}
+
+// ── Object model ─────────────────────────────────────────────────────────────
+// Everything in a space — rooms, categories, docs, projects, etc. — is an
+// ObjectNode with a type. Apps extend ObjectType with their own strings.
+
+/** The builtin object types. Custom types ride the same `string` field. */
+export type BuiltinObjectType = 'room' | 'category' | 'automation' | 'doc' | 'project' | 'task';
+export type ObjectType = BuiltinObjectType | (string & {});
+
+/** Runtime set of builtin type strings for renderer branching. */
+export const BUILTIN_OBJECT_TYPES: readonly BuiltinObjectType[] = ['room', 'category', 'automation', 'doc', 'project', 'task'];
+
+/** How an object's content syncs. Builtins infer this; custom types set it explicitly. */
+export type ObjectContentKind = 'merge' | 'append' | 'none';
+
+/** When `type === 'room'`, the room flavour. */
+export 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`.
+ */
+export 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. */
+export interface ObjectsIndex {
+  v: 1;
+  objects: ObjectNode[];
+  updatedAt: number;
+}