@drakkar.software/octospaces-sdk 0.1.0

package/src/sync/base64.ts

@@ -0,0 +1,89 @@
+/**
+ * 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).
+ */
+import type { Base64Provider } from '@drakkar.software/starfish-protocol';
+
+const CHUNK = 0x6000; // 24 576 bytes — multiple of 3, well under V8's apply limit
+
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+const REVERSE = (() => {
+  const table = new Int16Array(128).fill(-1);
+  for (let i = 0; i < ALPHABET.length; i++) table[ALPHABET.charCodeAt(i)] = i;
+  return table;
+})();
+
+const nativeCodec =
+  typeof globalThis !== 'undefined' &&
+  typeof globalThis.btoa === 'function' &&
+  typeof globalThis.atob === 'function';
+
+function encodeViaBtoa(data: Uint8Array): string {
+  let binary = '';
+  for (let i = 0; i < data.length; i += CHUNK) {
+    binary += String.fromCharCode.apply(null, data.subarray(i, i + CHUNK) as unknown as number[]);
+  }
+  return globalThis.btoa(binary);
+}
+
+function decodeViaAtob(encoded: string): Uint8Array {
+  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: Uint8Array): string {
+  const len = data.length;
+  const full = len - (len % 3);
+  const parts: string[] = [];
+  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: string): Uint8Array {
+  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) & 0xff;
+    }
+  }
+  return o === out.length ? out : out.subarray(0, o);
+}
+
+/** Spread-free, chunked base64 — a drop-in for the SDK's default provider. */
+export const starfishBase64: Base64Provider = nativeCodec
+  ? { encode: encodeViaBtoa, decode: decodeViaAtob }
+  : { encode: encodePure, decode: decodePure };

package/src/sync/base64url.ts

@@ -0,0 +1,22 @@
+/**
+ * base64url for link fragments (UTF-8 safe, web + native) — the encoding both
+ * invitation-link kinds ride in a URL `#fragment`. No padding, `+/` → `-_`.
+ */
+export function toBase64Url(json: string): string {
+  const bytes = new TextEncoder().encode(json);
+  let bin = '';
+  for (const b of bytes) bin += String.fromCharCode(b);
+  const b64 = typeof btoa === 'function' ? btoa(bin) : Buffer.from(json, 'utf-8').toString('base64');
+  return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function fromBase64Url(b64url: string): string {
+  const b64 = b64url.replace(/-/g, '+').replace(/_/g, '/');
+  if (typeof atob === 'function') {
+    const bin = atob(b64);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+  }
+  return Buffer.from(b64, 'base64').toString('utf-8');
+}

package/src/sync/client.ts

@@ -0,0 +1,301 @@
+/**
+ * Starfish client construction + space keyring/encryptor helpers.
+ */
+import { StarfishClient } from '@drakkar.software/starfish-client';
+import type { BatchPullEntry, Encryptor, StarfishCapProvider } from '@drakkar.software/starfish-client';
+import { createKeyring, createKeyringEncryptor } from '@drakkar.software/starfish-keyring';
+import type { Keyring } from '@drakkar.software/starfish-keyring';
+import { signRequest, stableStringify } from '@drakkar.software/starfish-protocol';
+import type { SignableMethod } from '@drakkar.software/starfish-protocol';
+
+import { getSyncBase, getSyncNamespace, getSyncPrefix, getOnServerReachable } from '../core/config.js';
+import { fetchWithTimeout } from './fetch-timeout.js';
+import { pullCache, PULL_CACHE_MAX_AGE_MS } from './pull-cache.js';
+import { cacheProfile, loadCachedProfile } from './profile-cache.js';
+import { keyringPull, keyringPush, profilePull, profilePush } from './paths.js';
+import { SpaceAccessError } from '../core/space-access-error.js';
+
+export interface DeviceKeys {
+  edPriv: string;
+  edPub: string;
+  kemPriv: string;
+  kemPub: string;
+}
+
+export function capProviderFor(cap: unknown, devEdPrivHex: string): StarfishCapProvider {
+  return {
+    async getCap() {
+      return { cap: cap as never, devEdPrivHex };
+    },
+  };
+}
+
+/**
+ * Build a Starfish client. `namespaceOverride` overrides the configured namespace,
+ * enabling the shared-spaces feature (a separate namespace for cross-app registry ops).
+ */
+export function makeClient(cap: unknown, devEdPrivHex: string, namespaceOverride?: string): StarfishClient {
+  return new StarfishClient({
+    baseUrl: getSyncBase(),
+    namespace: namespaceOverride ?? getSyncNamespace(),
+    capProvider: capProviderFor(cap, devEdPrivHex),
+    fetch: fetchWithTimeout(),
+    cache: pullCache(),
+    cacheMaxAgeMs: PULL_CACHE_MAX_AGE_MS,
+    cacheFallbackStatuses: [429, 500, 502, 503, 504],
+    onRevalidated: () => getOnServerReachable()?.(),
+  });
+}
+
+/**
+ * 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.
+ */
+export async function openEncryptor(
+  client: StarfishClient,
+  keys: DeviceKeys,
+  spaceId: string,
+  trustedAdders: string[],
+): Promise<Encryptor> {
+  const res = await client.pull(keyringPull(spaceId)).catch(() => {
+    throw new Error('Could not reach the server to fetch space keys.');
+  });
+  const keyring = res?.data as unknown as Keyring | undefined;
+  if (!keyring || !keyring.epochs) {
+    throw new SpaceAccessError('This space has no keyring yet — ask the owner to open it first.');
+  }
+  try {
+    const enc = await createKeyringEncryptor(
+      keyring,
+      { kemPubHex: keys.kemPub, kemPrivHex: keys.kemPriv },
+      { trustedAdders },
+    );
+    return enc as unknown as Encryptor;
+  } catch {
+    throw new SpaceAccessError("You're not a recipient of this space's keyring yet — ask the owner to re-invite.");
+  }
+}
+
+/** Soft variant of {@link openEncryptor}: returns null instead of throwing. */
+export async function buildEncryptor(
+  client: StarfishClient,
+  keys: DeviceKeys,
+  spaceId: string,
+  trustedAdders: string[],
+): Promise<Encryptor | null> {
+  try {
+    return await openEncryptor(client, keys, spaceId, trustedAdders);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Owner-side: create the SPACE keyring if missing, return an encryptor.
+ */
+export async function ownerEnsureKeyring(
+  client: StarfishClient,
+  keys: DeviceKeys,
+  spaceId: string,
+  trustedAdders: string[] = [keys.edPub],
+): Promise<Encryptor> {
+  const krRes = await client.pull(keyringPull(spaceId)).catch(() => null);
+  let keyring = krRes?.data as unknown as Keyring | undefined;
+  if (!keyring || !keyring.epochs) {
+    const created = await createKeyring({ edPrivHex: keys.edPriv, edPubHex: keys.edPub }, [
+      { subKemHex: keys.kemPub },
+    ]);
+    keyring = created.keyring;
+    await client.push(keyringPush(spaceId), keyring as unknown as Record<string, unknown>, krRes?.hash ?? null);
+  }
+  const enc = await createKeyringEncryptor(
+    keyring,
+    { kemPubHex: keys.kemPub, kemPrivHex: keys.kemPriv },
+    { trustedAdders },
+  );
+  return enc as unknown as Encryptor;
+}
+
+/** A user's public profile: display pseudo + optional inline avatar + public identity keys. */
+export interface PublicProfile {
+  pseudo: string | null;
+  avatar: string | null;
+  edPub: string | null;
+  kemPub: string | null;
+}
+
+/** Read any user's public profile. */
+export async function readProfile(userId: string): Promise<PublicProfile> {
+  try {
+    const r = await fetchWithTimeout()(`${getSyncBase()}${getSyncPrefix()}${profilePull(userId)}`);
+    if (!r.ok) return { pseudo: null, avatar: null, edPub: null, kemPub: null };
+    const body = await r.json();
+    const data = body?.data as { pseudo?: unknown; avatar?: unknown; edPub?: unknown; kemPub?: unknown } | undefined;
+    const profile: PublicProfile = {
+      pseudo: typeof data?.pseudo === 'string' ? data.pseudo : null,
+      avatar: typeof data?.avatar === 'string' ? data.avatar : null,
+      edPub: typeof data?.edPub === 'string' ? data.edPub : null,
+      kemPub: typeof data?.kemPub === 'string' ? data.kemPub : null,
+    };
+    cacheProfile(userId, profile);
+    return profile;
+  } catch {
+    return (await loadCachedProfile(userId)) ?? { pseudo: null, avatar: null, edPub: null, kemPub: null };
+  }
+}
+
+/** Read any user's public profile pseudo. */
+export async function readPseudo(userId: string): Promise<string | null> {
+  return (await readProfile(userId)).pseudo;
+}
+
+let profileBatchClient: StarfishClient | undefined;
+function getProfileBatchClient(): StarfishClient {
+  if (!profileBatchClient) {
+    profileBatchClient = new StarfishClient({ baseUrl: getSyncBase(), namespace: getSyncNamespace(), fetch: fetchWithTimeout() });
+  }
+  return profileBatchClient;
+}
+
+const PROFILE_BATCH_CHUNK = 24;
+
+/**
+ * Read MANY users' public profiles in one /batch/pull round-trip per chunk.
+ */
+export async function readProfiles(ids: string[]): Promise<Map<string, PublicProfile>> {
+  const out = new Map<string, PublicProfile>();
+  const client = getProfileBatchClient();
+  for (let i = 0; i < ids.length; i += PROFILE_BATCH_CHUNK) {
+    const chunk = ids.slice(i, i + PROFILE_BATCH_CHUNK);
+    let entries: BatchPullEntry[];
+    try {
+      entries = await client.batchPullMany('profile', chunk.map((id) => ({ identity: id })));
+    } catch {
+      for (const id of chunk) {
+        const cached = await loadCachedProfile(id);
+        if (cached) out.set(id, cached);
+      }
+      continue;
+    }
+    chunk.forEach((id, j) => {
+      const entry = entries[j];
+      if (!entry || entry.error) return;
+      const data = (entry.data ?? null) as { pseudo?: unknown; avatar?: unknown; edPub?: unknown; kemPub?: unknown } | null;
+      const profile: PublicProfile = {
+        pseudo: typeof data?.pseudo === 'string' ? data.pseudo : null,
+        avatar: typeof data?.avatar === 'string' ? data.avatar : null,
+        edPub: typeof data?.edPub === 'string' ? data.edPub : null,
+        kemPub: typeof data?.kemPub === 'string' ? data.kemPub : null,
+      };
+      cacheProfile(id, profile);
+      out.set(id, profile);
+    });
+  }
+  return out;
+}
+
+/**
+ * Merge a patch into the caller's own profile doc.
+ */
+export async function writeProfile(
+  client: StarfishClient,
+  userId: string,
+  patch: { pseudo?: string; avatar?: string | null; edPub?: string; kemPub?: string },
+): Promise<void> {
+  const current = await client.pull(profilePull(userId)).catch(() => null);
+  const base = (current?.data as Record<string, unknown> | undefined) ?? {};
+  const next: Record<string, unknown> = { ...base, ...patch, v: 1 };
+  if (next.avatar == null) delete next.avatar;
+  await client.push(profilePush(userId), next, current?.hash ?? null);
+}
+
+/** Write the caller's own profile pseudo. */
+export async function writePseudo(client: StarfishClient, userId: string, pseudo: string): Promise<void> {
+  await writeProfile(client, userId, { pseudo });
+}
+
+/**
+ * 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.
+ */
+export async function ensureProfileKeys(
+  client: StarfishClient,
+  userId: string,
+  keys: { edPub: string; kemPub: string },
+): Promise<void> {
+  let confirmedAbsent = false;
+  try {
+    const r = await fetchWithTimeout()(`${getSyncBase()}${getSyncPrefix()}${profilePull(userId)}`);
+    if (r.status === 404) confirmedAbsent = true;
+    else if (r.ok) {
+      const body = await r.json();
+      const data = body?.data as { edPub?: unknown; kemPub?: unknown } | undefined;
+      confirmedAbsent = !(typeof data?.edPub === 'string' && typeof data?.kemPub === 'string');
+    } else return;
+  } catch {
+    return;
+  }
+  if (!confirmedAbsent) return;
+  await writeProfile(client, userId, { edPub: keys.edPub, kemPub: keys.kemPub });
+}
+
+/**
+ * Build cap-cert auth headers for a raw `fetch` outside the StarfishClient.
+ */
+export async function buildAuthHeaders(
+  cap: unknown,
+  devEdPrivHex: string,
+  method: string,
+  pathAndQuery: string,
+): Promise<Record<string, string>> {
+  let host = '';
+  try {
+    host = new URL(getSyncBase()).host;
+  } catch { /* relative base */ }
+
+  const { sig, ts, nonce } = await signRequest(
+    { method: method as SignableMethod, pathAndQuery, host },
+    devEdPrivHex,
+  );
+
+  const capJson = stableStringify(cap as Record<string, unknown>);
+  const capB64 =
+    typeof btoa === 'function'
+      ? btoa(capJson)
+      : Buffer.from(capJson, 'utf-8').toString('base64');
+
+  return {
+    Authorization: `Cap ${capB64}`,
+    'X-Starfish-Sig': sig,
+    'X-Starfish-Ts': String(ts),
+    'X-Starfish-Nonce': nonce,
+  };
+}
+
+async function readOwnPseudo(userId: string): Promise<{ read: boolean; pseudo: string | null }> {
+  try {
+    const r = await fetchWithTimeout()(`${getSyncBase()}${getSyncPrefix()}${profilePull(userId)}`);
+    if (r.status === 404) return { read: true, pseudo: null };
+    if (!r.ok) return { read: false, pseudo: null };
+    const body = await r.json();
+    const data = body?.data as { pseudo?: unknown } | undefined;
+    return { read: true, pseudo: typeof data?.pseudo === 'string' ? data.pseudo : null };
+  } catch {
+    return { read: false, pseudo: null };
+  }
+}
+
+/**
+ * Seed the caller's profile pseudo only if none exists yet, returning the
+ * authoritative server value.
+ */
+export async function ensurePseudo(client: StarfishClient, userId: string, fallback: string): Promise<string> {
+  const { read, pseudo } = await readOwnPseudo(userId);
+  if (pseudo && pseudo.trim()) return pseudo;
+  if (!read) return fallback;
+  await writeProfile(client, userId, { pseudo: fallback });
+  return fallback;
+}

package/src/sync/fetch-timeout.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { CONNECT_TIMEOUT_MS, fetchWithTimeout } from './fetch-timeout.js';
+
+describe('CONNECT_TIMEOUT_MS', () => {
+  it('is 12 seconds', () => {
+    expect(CONNECT_TIMEOUT_MS).toBe(12_000);
+  });
+});
+
+describe('fetchWithTimeout', () => {
+  it('returns a fetch function', () => {
+    const fn = fetchWithTimeout();
+    expect(typeof fn).toBe('function');
+  });
+
+  it('returns a fetch function with custom timeout', () => {
+    const fn = fetchWithTimeout(5_000);
+    expect(typeof fn).toBe('function');
+  });
+
+  it('aborts on timeout', async () => {
+    // Use a very short timeout and a never-resolving URL to trigger abort.
+    const fn = fetchWithTimeout(10);
+    await expect(fn('https://httpbin.org/delay/10')).rejects.toThrow();
+  }, 2_000);
+});

package/src/sync/fetch-timeout.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+
+export const CONNECT_TIMEOUT_MS = 12_000; // generous: trips only on a truly stalled socket
+
+export function fetchWithTimeout(timeoutMs = CONNECT_TIMEOUT_MS): typeof fetch {
+  return (input, init) => {
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    const caller = init?.signal;
+    if (caller) {
+      if (caller.aborted) ctrl.abort();
+      else caller.addEventListener('abort', () => ctrl.abort(), { once: true });
+    }
+    return fetch(input as RequestInfo, { ...init, signal: ctrl.signal }).finally(() => clearTimeout(timer));
+  };
+}

package/src/sync/identity.ts

@@ -0,0 +1,158 @@
+/**
+ * Identity & 12-word recovery seed. The seed is a BIP-39 mnemonic used as the
+ * passphrase for Starfish's `bootstrapRootIdentity`; the same words deterministically
+ * recover the identity.
+ */
+import { generateMnemonic, validateMnemonic } from '@scure/bip39';
+import { wordlist } from '@scure/bip39/wordlists/english.js';
+import { bootstrapRootIdentity, mintDeviceCap } from '@drakkar.software/starfish-identities';
+import type { StarfishClient } from '@drakkar.software/starfish-client';
+import type { CapCert } from '@drakkar.software/starfish-protocol';
+
+import { makeClient, ensureProfileKeys, ensurePseudo, type DeviceKeys } from './client.js';
+import { accountScope, ownerScope } from './paths.js';
+import { getSharedSpacesNamespace } from '../core/config.js';
+import type { DerivedIdentity } from '../core/storage-types.js';
+
+export 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.
+ */
+export function ownerTrustedAdders(session: Session): string[] {
+  return session.ownerEdPub === session.keys.edPub
+    ? [session.keys.edPub]
+    : [session.ownerEdPub, session.keys.edPub];
+}
+
+/** Fresh 12-word recovery seed. */
+export function generateSeedWords(): string[] {
+  return generateMnemonic(wordlist, 128).split(' ');
+}
+
+export function isValidSeed(words: string[]): boolean {
+  return validateMnemonic(words.join(' ').trim(), wordlist);
+}
+
+/** Human-readable fingerprint derived from the identity's user id. */
+export function fingerprintFromUserId(userId: string): string {
+  const h = userId.replace(/[^0-9a-f]/gi, '').toUpperCase();
+  return [h.slice(0, 4), h.slice(4, 8), h.slice(8, 12)].filter(Boolean).join(' · ');
+}
+
+/**
+ * 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.
+ */
+export async function buildSession({ userId, keys }: DerivedIdentity, name?: string): Promise<Session> {
+  const fallback = name && name.trim() ? name.trim() : `user-${userId.slice(0, 6)}`;
+  const sub = { edPubHex: keys.edPub, kemPubHex: keys.kemPub };
+  const chatCap = await mintDeviceCap(keys.edPriv, keys.edPub, sub, ownerScope());
+  const accountCap = await mintDeviceCap(keys.edPriv, keys.edPub, sub, accountScope(userId));
+  const chatClient = makeClient(chatCap, keys.edPriv);
+  const accountClient = makeClient(accountCap, keys.edPriv);
+
+  const sharedNs = getSharedSpacesNamespace();
+  const spacesRegistryClient = sharedNs ? makeClient(accountCap, keys.edPriv, sharedNs) : accountClient;
+  const spacesKeyringClient = sharedNs ? makeClient(chatCap, keys.edPriv, sharedNs) : chatClient;
+
+  const displayName = await ensurePseudo(accountClient, userId, fallback).catch(() => fallback);
+  void ensureProfileKeys(accountClient, userId, keys).catch(() => {});
+  return {
+    userId,
+    name: displayName,
+    keys,
+    chatCap,
+    accountCap,
+    chatClient,
+    accountClient,
+    spacesRegistryClient,
+    spacesKeyringClient,
+    fingerprint: fingerprintFromUserId(userId),
+    ownerEdPub: keys.edPub,
+  };
+}
+
+/** A paired device's credentials: its own keypair + the root-signed cap-cert. */
+export 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.
+ */
+export async function buildLinkedSession({ userId, keys, capCert }: LinkedIdentity, name?: string): Promise<Session> {
+  const fallback = name && name.trim() ? name.trim() : `user-${userId.slice(0, 6)}`;
+  const chatClient = makeClient(capCert, keys.edPriv);
+  const accountClient = makeClient(capCert, keys.edPriv);
+
+  const sharedNs = getSharedSpacesNamespace();
+  const spacesRegistryClient = sharedNs ? makeClient(capCert, keys.edPriv, sharedNs) : accountClient;
+  const spacesKeyringClient = sharedNs ? makeClient(capCert, keys.edPriv, sharedNs) : chatClient;
+
+  const displayName = await ensurePseudo(accountClient, userId, fallback).catch(() => fallback);
+  return {
+    userId,
+    name: displayName,
+    keys,
+    chatCap: capCert,
+    accountCap: capCert,
+    chatClient,
+    accountClient,
+    spacesRegistryClient,
+    spacesKeyringClient,
+    fingerprint: fingerprintFromUserId(userId),
+    ownerEdPub: capCert.iss,
+  };
+}
+
+/** Derive a full owner session (identity + caps + clients) from a seed. */
+export async function deriveSession(seedWords: string[], name?: string): Promise<Session> {
+  const passphrase = seedWords.join(' ').trim();
+  const creds = await bootstrapRootIdentity(passphrase);
+  return buildSession({ userId: creds.userId, keys: creds.device as DeviceKeys }, name);
+}
+
+/** The cached root identity (userId + keys) carried by a built session. */
+export function rootIdentityOf(s: Session): DerivedIdentity {
+  return { userId: s.userId, keys: s.keys };
+}