@drakkar.software/octospaces-sdk 0.1.0

package/src/spaces/members.ts

@@ -0,0 +1,271 @@
+/**
+ * Space membership — both keyring-based (private spaces) and link-based (public spaces).
+ *
+ * PRIVATE join: the owner adds the invitee to the space keyring, records them in the
+ * roster, and mints a space-scoped member cap. The invitee verifies keyring access on
+ * accept and stores a `{kind:'member'}` entry.
+ *
+ * PUBLIC (link) join: the owner mints an ephemeral Ed/KEM keypair whose *private* key
+ * ships inside a URL-fragment token, adds the ephemeral userId to the roster so the
+ * server grants `space:member`, and mints a member cap scoped to that ephemeral subject.
+ * Any bearer of the link stores a `{kind:'link'}` entry. Revocation = `removeSpaceMember`.
+ */
+import { generateDeviceKeys } from '@drakkar.software/starfish-identities';
+import { addCollectionRecipient } from '@drakkar.software/starfish-keyring';
+import { mintMemberCap } from '@drakkar.software/starfish-sharing';
+
+import type { Space } from '../core/types.js';
+import { buildEncryptor, makeClient } from '../sync/client.js';
+import type { Session } from '../sync/identity.js';
+import {
+  getSpaceAccessEntry,
+  hydrateSpaceAccessStore,
+  localSpaceAccessEntries,
+  saveSpaceAccessEntry,
+} from '../sync/space-access-store.js';
+import { keyringName, spaceMemberScope, userIdFromEdPub } from '../sync/paths.js';
+import { addJoinedSpaceWithCap, addJoinedSpaceWithLinkAccess, addSpaceMember, readSpaces, updateSpacesDoc } from './registry.js';
+import { sealToSelf, unsealFromSelf } from '../sync/account-seal.js';
+import { toBase64Url, fromBase64Url } from '../sync/base64url.js';
+
+export interface JoinRequest {
+  edPub: string;
+  kemPub: string;
+  userId: string;
+}
+
+export function makeJoinRequest(session: Session): string {
+  const req: JoinRequest = { edPub: session.keys.edPub, kemPub: session.keys.kemPub, userId: session.userId };
+  return JSON.stringify(req);
+}
+
+interface SpaceInvite {
+  spaceId: string;
+  spaceName: string;
+  cap: unknown;
+}
+
+function isAlreadyPresentRecipient(err: unknown): boolean {
+  return err instanceof Error && /already present in epoch/.test(err.message);
+}
+
+/**
+ * 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.
+ */
+export async function addDeviceToSpaceKeyring(
+  session: Session,
+  spaceId: string,
+  recipient: { kemPub: string; userId: string },
+): Promise<void> {
+  try {
+    await addCollectionRecipient(
+      session.chatClient,
+      keyringName(spaceId),
+      { subKem: recipient.kemPub, userId: recipient.userId, label: recipient.userId.slice(0, 8) },
+      { edPriv: session.keys.edPriv, edPub: session.keys.edPub, kemPriv: session.keys.kemPriv },
+      { trustedAdders: [session.keys.edPub] },
+    );
+  } catch (err) {
+    if (!isAlreadyPresentRecipient(err)) throw err;
+  }
+}
+
+/**
+ * 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.
+ */
+export async function inviteToSpace(
+  session: Session,
+  spaceId: string,
+  requestJson: string,
+  canWrite = true,
+  spaceName?: string,
+): Promise<string> {
+  const req = JSON.parse(requestJson) as JoinRequest;
+  if (!req.edPub || !req.kemPub || !req.userId) throw new Error('That is not a valid join request.');
+  await addDeviceToSpaceKeyring(session, spaceId, { kemPub: req.kemPub, userId: req.userId });
+  await addSpaceMember(session.accountClient, spaceId, session.userId, req.userId);
+  // NOTE: 'chat' is the cap collection the deployed server's space-member enricher recognises.
+  const cap = await mintMemberCap(
+    session.keys.edPriv,
+    session.keys.edPub,
+    { edPubHex: req.edPub, kemPubHex: req.kemPub, userIdHex: req.userId },
+    'chat',
+    spaceMemberScope(spaceId, canWrite),
+  );
+  let name = spaceName?.trim();
+  if (!name) {
+    const { spaces } = await readSpaces(session.accountClient, session.userId);
+    name = spaces.find((s) => s.id === spaceId)?.name ?? 'Space';
+  }
+  const invite: SpaceInvite = { spaceId, spaceName: name, cap };
+  return JSON.stringify(invite);
+}
+
+/**
+ * Invitee: accept a PRIVATE space invite — verify keyring access, store the cap,
+ * and register the space. Returns the joined space.
+ */
+export async function acceptSpaceInvite(session: Session, inviteJson: string): Promise<Space> {
+  const inv = JSON.parse(inviteJson) as Partial<SpaceInvite>;
+  const cap = inv.cap as { kind?: string; sub?: string; iss?: string } | undefined;
+  if (!cap || !inv.spaceId) throw new Error('That is not a valid space invite.');
+  if (cap.kind !== 'member') throw new Error('That is not a valid space invite.');
+  if (!cap.sub || cap.sub !== session.keys.edPub) {
+    throw new Error('This invite was issued for a different identity.');
+  }
+  if (!cap.iss) throw new Error('This invite is missing its issuer.');
+  const spaceId = inv.spaceId;
+  const client = makeClient(cap, session.keys.edPriv);
+  const enc = await buildEncryptor(client, session.keys, spaceId, [cap.iss]);
+  if (!enc) throw new Error("Accepted, but you're not in the space keyring yet — ask the owner to re-invite.");
+  const capJson = JSON.stringify(cap);
+  const name = inv.spaceName?.trim() || `space-${spaceId.slice(-6)}`;
+  const space: Space = { id: spaceId, name, short: name.slice(0, 2).toUpperCase(), members: 1 };
+  await addJoinedSpaceWithCap(session.accountClient, session.userId, space, capJson);
+  saveSpaceAccessEntry(spaceId, { kind: 'member', cap: capJson });
+  return space;
+}
+
+// ── Link-based joins (public spaces) ─────────────────────────────────────────
+
+/** A space invite link token (v:1, no ownerId — derive from cap.iss instead). */
+export interface SpaceInviteLinkToken {
+  v: 1;
+  spaceId: string;
+  spaceName: string;
+  cap: unknown;
+  /** The throwaway ephemeral subject's Ed25519 private key (hex). */
+  key: string;
+  write: boolean;
+}
+
+export function encodeSpaceInviteLink(origin: string, token: SpaceInviteLinkToken): string {
+  const base = origin.replace(/\/+$/, '');
+  return `${base}/join#${toBase64Url(JSON.stringify(token))}`;
+}
+
+export function decodeSpaceInviteLink(fragment: string): SpaceInviteLinkToken {
+  const frag = fragment.startsWith('#') ? fragment.slice(1) : fragment;
+  const tok = JSON.parse(fromBase64Url(frag)) as Partial<SpaceInviteLinkToken>;
+  if (!tok || !tok.spaceId || !tok.cap || !tok.key) {
+    throw new Error('That space invite link is malformed or incomplete.');
+  }
+  return {
+    v: 1,
+    spaceId: tok.spaceId,
+    spaceName: tok.spaceName ?? 'Space',
+    cap: tok.cap,
+    key: tok.key,
+    write: !!tok.write,
+  };
+}
+
+/**
+ * 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)`.
+ */
+export async function createSpaceInviteLink(
+  session: Session,
+  spaceId: string,
+  spaceName: string,
+  write: boolean,
+  origin: string,
+): Promise<{ token: SpaceInviteLinkToken; link: string }> {
+  const ek = generateDeviceKeys();
+  const ephemeralUserId = await userIdFromEdPub(ek.edPub);
+  const cap = await mintMemberCap(
+    session.keys.edPriv,
+    session.keys.edPub,
+    { edPubHex: ek.edPub, kemPubHex: ek.kemPub, userIdHex: ephemeralUserId },
+    'chat',
+    spaceMemberScope(spaceId, write),
+  );
+  // Add the ephemeral userId to the roster so the server grants `space:member`
+  await addSpaceMember(session.accountClient, spaceId, session.userId, ephemeralUserId);
+  const token: SpaceInviteLinkToken = { v: 1, spaceId, spaceName, cap, key: ek.edPriv, write };
+  return { token, link: encodeSpaceInviteLink(origin, token) };
+}
+
+/**
+ * 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.
+ */
+export async function joinSpaceByLink(session: Session, token: SpaceInviteLinkToken): Promise<Space> {
+  const cap = token.cap as { iss?: string };
+  const ownerId = cap.iss ? await userIdFromEdPub(cap.iss) : undefined;
+  const name = token.spaceName.trim() || `space-${token.spaceId.slice(-6)}`;
+  const space: Space = {
+    id: token.spaceId,
+    name,
+    short: name.slice(0, 2).toUpperCase(),
+    members: 1,
+    visibility: 'public',
+    ...(ownerId ? { ownerId } : {}),
+    write: token.write,
+  };
+  const accessPayload = { cap: token.cap, key: token.key, write: token.write };
+  const sealed = await sealToSelf(session, JSON.stringify(accessPayload));
+  await addJoinedSpaceWithLinkAccess(session.accountClient, session.userId, space, sealed);
+  saveSpaceAccessEntry(token.spaceId, { kind: 'link', cap: token.cap, key: token.key, write: token.write });
+  return 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.
+ */
+export async function recoverSpaceAccess(
+  session: Session,
+  server: { caps: Record<string, string>; pubAccess: Record<string, import('../sync/account-seal.js').SealedBlob> },
+): Promise<void> {
+  // Unseal link access blobs
+  const linkAccess: Record<string, { cap: unknown; key: string; write: boolean }> = {};
+  for (const [spaceId, sealed] of Object.entries(server.pubAccess)) {
+    try {
+      const raw = await unsealFromSelf(session, sealed);
+      const parsed = JSON.parse(raw) as { cap: unknown; key: string; write: boolean };
+      if (parsed.cap && parsed.key) linkAccess[spaceId] = parsed;
+    } catch (e) {
+      console.error('[octospaces] recoverSpaceAccess: failed to unseal', spaceId, e);
+    }
+  }
+
+  await hydrateSpaceAccessStore(session.userId, server.caps, linkAccess);
+
+  // Backfill local-only entries to the server
+  const local = localSpaceAccessEntries();
+  const missingMemberCaps = Object.entries(local)
+    .filter(([id, e]) => e.kind === 'member' && !(id in server.caps));
+  const missingLinks = Object.entries(local)
+    .filter(([id, e]) => e.kind === 'link' && !(id in server.pubAccess));
+
+  if (missingMemberCaps.length === 0 && missingLinks.length === 0) return;
+
+  try {
+    const newCaps: Record<string, string> = {};
+    for (const [id, e] of missingMemberCaps) if (e.kind === 'member') newCaps[id] = e.cap;
+
+    const newPubAccess: Record<string, import('../sync/account-seal.js').SealedBlob> = {};
+    for (const [id, e] of missingLinks) {
+      if (e.kind === 'link') {
+        newPubAccess[id] = await sealToSelf(session, JSON.stringify({ cap: e.cap, key: e.key, write: e.write }));
+      }
+    }
+
+    await updateSpacesDoc(session.accountClient, session.userId, (cur) => ({
+      spaces: cur.spaces,
+      caps: { ...cur.caps, ...newCaps },
+      pubAccess: { ...cur.pubAccess, ...newPubAccess },
+    }));
+  } catch (e) {
+    console.error('[octospaces] recoverSpaceAccess: backfill failed', e);
+  }
+}

package/src/spaces/object-index.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { Encryptor, StarfishClient } from '@drakkar.software/starfish-client';
+import { readIndexRooms, pushIndexSeed } from './object-index.js';
+import type { SeedRoom } from './object-index.js';
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+
+function makeClient(data: unknown, hash = 'h1'): StarfishClient {
+  return {
+    pull: vi.fn().mockResolvedValue({ data, hash }),
+    push: vi.fn().mockResolvedValue(undefined),
+  } as unknown as StarfishClient;
+}
+
+function makeEncryptor(decryptOutput: Record<string, unknown>): Encryptor {
+  return {
+    decrypt: vi.fn().mockResolvedValue(decryptOutput),
+    encrypt: vi.fn().mockImplementation(async (v: Record<string, unknown>) => ({ _encrypted: true, ...v })),
+  } as unknown as Encryptor;
+}
+
+const spaceId = 'sp-test';
+const plainNodes = [{ id: 'r1', type: 'room', subtype: 'channel', parentId: null, order: 0, title: 'general', updatedAt: 1 }];
+const plainIndexDoc = { objects: plainNodes };
+
+// ── readIndexRooms ─────────────────────────────────────────────────────────────
+
+describe('readIndexRooms — plaintext (null encryptor)', () => {
+  it('returns rooms from a plaintext objects doc', async () => {
+    const client = makeClient(plainIndexDoc);
+    const result = await readIndexRooms(client, null, '/pull/spaces/sp-test/objects/_index', spaceId);
+    expect(result).not.toBeNull();
+    expect(result!.rooms.length).toBeGreaterThan(0);
+  });
+
+  it('returns null when pull returns no data', async () => {
+    const client = makeClient(null);
+    const result = await readIndexRooms(client, null, '/pull/x', spaceId);
+    expect(result).toBeNull();
+  });
+});
+
+describe('readIndexRooms — encrypted (with encryptor)', () => {
+  it('calls encryptor.decrypt and projects rooms', async () => {
+    const enc = makeEncryptor(plainIndexDoc);
+    const client = makeClient({ _encrypted: true, ct: 'abc' });
+    const result = await readIndexRooms(client, enc, '/pull/x', spaceId);
+    expect(enc.decrypt).toHaveBeenCalled();
+    expect(result).not.toBeNull();
+    expect(result!.rooms.length).toBeGreaterThan(0);
+  });
+
+  it('returns null on decrypt error', async () => {
+    const enc = {
+      decrypt: vi.fn().mockRejectedValue(new Error('bad key')),
+      encrypt: vi.fn(),
+    } as unknown as Encryptor;
+    const client = makeClient({ _encrypted: true });
+    const result = await readIndexRooms(client, enc, '/pull/x', spaceId);
+    expect(result).toBeNull();
+  });
+});
+
+// ── pushIndexSeed ──────────────────────────────────────────────────────────────
+
+const seedRooms: SeedRoom[] = [{ id: 'sp-test-general', name: 'general', kind: 'channel', category: 'CHANNELS' }];
+
+describe('pushIndexSeed — plaintext', () => {
+  it('pushes plaintext objects when encryptor is null', async () => {
+    const client = makeClient(null, null as unknown as string);
+    (client.pull as ReturnType<typeof vi.fn>).mockResolvedValue(null);
+    await pushIndexSeed(client, null, spaceId, seedRooms);
+    expect(client.push).toHaveBeenCalled();
+    const [, payload] = (client.push as ReturnType<typeof vi.fn>).mock.calls[0] as [string, Record<string, unknown>];
+    expect(Array.isArray(payload.objects)).toBe(true);
+    expect((payload as { _encrypted?: boolean })._encrypted).toBeUndefined();
+  });
+
+  it('is idempotent when plaintext {objects} already exists', async () => {
+    const client = makeClient(plainIndexDoc);
+    await pushIndexSeed(client, null, spaceId, seedRooms);
+    expect(client.push).not.toHaveBeenCalled();
+  });
+});
+
+describe('pushIndexSeed — encrypted', () => {
+  it('pushes encrypted payload when encryptor provided', async () => {
+    const enc = makeEncryptor({});
+    (enc.encrypt as ReturnType<typeof vi.fn>).mockResolvedValue({ _encrypted: true, ct: 'x' });
+    const client = makeClient(null, null as unknown as string);
+    (client.pull as ReturnType<typeof vi.fn>).mockResolvedValue(null);
+    await pushIndexSeed(client, enc, spaceId, seedRooms);
+    expect(enc.encrypt).toHaveBeenCalled();
+    expect(client.push).toHaveBeenCalled();
+    const [, payload] = (client.push as ReturnType<typeof vi.fn>).mock.calls[0] as [string, Record<string, unknown>];
+    expect((payload as { _encrypted?: boolean })._encrypted).toBe(true);
+  });
+
+  it('is idempotent when encrypted doc already exists', async () => {
+    const enc = makeEncryptor({});
+    const client = makeClient({ _encrypted: true, ct: 'existing' });
+    await pushIndexSeed(client, enc, spaceId, seedRooms);
+    expect(client.push).not.toHaveBeenCalled();
+  });
+});

package/src/spaces/object-index.ts

@@ -0,0 +1,160 @@
+/**
+ * Headless reads + create-time seeding of a space's unified OBJECT INDEX.
+ *
+ * Both PRIVATE (encrypted) and PUBLIC (plaintext) spaces store their room/category
+ * tree in `spaces/{spaceId}/objects/_index`. The `encryptor` parameter is null for
+ * public spaces — the helpers pass data through unchanged.
+ */
+import { ConflictError } from '@drakkar.software/starfish-client';
+import type { Encryptor, StarfishClient } from '@drakkar.software/starfish-client';
+
+import type { ObjectNode, Room, SpaceVisibility } from '../core/types.js';
+import type { Session } from '../sync/identity.js';
+import { DEFAULT_CATEGORY, objectsToRoomCategories, seedIndexNodes } from '../objects/objects.js';
+import type { SeedRoom } from '../objects/objects.js';
+import { objIndexPull, objIndexPush } from '../sync/paths.js';
+import { buildSpaceAccess, getSpaceAccess } from '../sync/space-access.js';
+
+export type { SeedRoom };
+
+function indexNodes(plain: Record<string, unknown>): ObjectNode[] {
+  return Array.isArray((plain as { objects?: unknown }).objects)
+    ? (plain as { objects: ObjectNode[] }).objects
+    : [];
+}
+
+/**
+ * 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.
+ */
+export async function readIndexRooms(
+  client: StarfishClient,
+  encryptor: Encryptor | null,
+  indexPath: string,
+  spaceId: string,
+): Promise<{ rooms: Room[]; categories: string[] } | null> {
+  try {
+    const res = await client.pull(indexPath).catch(() => null);
+    if (!res?.data) return null;
+    const plain = encryptor
+      ? await encryptor.decrypt(res.data as Record<string, unknown>)
+      : (res.data as Record<string, unknown>);
+    const cats = objectsToRoomCategories(indexNodes(plain), spaceId, DEFAULT_CATEGORY);
+    if (!cats) return null;
+    return { rooms: cats.flatMap((c) => c.rooms), categories: cats.map((c) => c.name) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read a space's index rooms + categories, resolving access automatically.
+ * Pass `reg` (from `readRooms`) so the accessor picks the right auth mode.
+ */
+export async function readSpaceIndexRooms(
+  session: Session,
+  spaceId: string,
+  reg: { owner: string | null; members: string[]; visibility?: SpaceVisibility },
+): Promise<{ rooms: Room[]; categories: string[] } | null> {
+  if (reg.owner === null && reg.visibility !== 'public') return null;
+  try {
+    const { encryptor, client } = await getSpaceAccess(spaceId, session, reg);
+    return await readIndexRooms(client, encryptor, objIndexPull(spaceId), spaceId);
+  } catch {
+    return null;
+  }
+}
+
+/** SOFT read — never throws, never mints. Returns an empty array on any failure. */
+export async function readSpaceRooms(
+  session: Session,
+  spaceId: string,
+  hint?: { visibility?: SpaceVisibility },
+): Promise<Room[]> {
+  const access = await buildSpaceAccess(session, spaceId, hint).catch(() => null);
+  if (!access) return [];
+  const idx = await readIndexRooms(access.client, access.encryptor, objIndexPull(spaceId), spaceId);
+  return idx?.rooms ?? [];
+}
+
+/**
+ * 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).
+ */
+export async function pushIndexSeed(
+  client: StarfishClient,
+  encryptor: Encryptor | null,
+  spaceId: string,
+  rooms: SeedRoom[],
+): Promise<void> {
+  const res = await client.pull(objIndexPull(spaceId)).catch(() => null);
+  const existing = res?.data as Record<string, unknown> | undefined;
+  if (existing?._encrypted || Array.isArray(existing?.objects)) return;
+  const nodes = seedIndexNodes(rooms, Date.now());
+  const payload = encryptor
+    ? await encryptor.encrypt({ objects: nodes }) as Record<string, unknown>
+    : { objects: nodes };
+  await client.push(objIndexPush(spaceId), payload, res?.hash ?? null);
+}
+
+/**
+ * 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.
+ */
+export async function seedSpaceObjectIndex(
+  session: Session,
+  spaceId: string,
+  rooms: SeedRoom[],
+  opts?: { visibility?: SpaceVisibility },
+): Promise<void> {
+  const { encryptor, client } = await getSpaceAccess(spaceId, session, {
+    owner: session.userId,
+    members: [],
+    visibility: opts?.visibility,
+  });
+  await pushIndexSeed(client, encryptor, spaceId, rooms);
+}
+
+/**
+ * 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.
+ */
+export async function updateObjectIndex(
+  session: Session,
+  spaceId: string,
+  mutator: (nodes: ObjectNode[], now: number) => ObjectNode[] | null,
+  reg?: { owner: string | null; members: string[]; visibility?: SpaceVisibility } | null,
+): Promise<void> {
+  const { client, encryptor } = await getSpaceAccess(spaceId, session, reg ?? null);
+  const pullPath = objIndexPull(spaceId);
+  const pushPath = objIndexPush(spaceId);
+  const MAX_ATTEMPTS = 3;
+  for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+    const res = await client.pull(pullPath).catch(() => null);
+    const raw = res?.data as Record<string, unknown> | undefined;
+    const plain = raw
+      ? encryptor
+        ? await encryptor.decrypt(raw)
+        : raw
+      : {};
+    const cur = Array.isArray((plain as { objects?: unknown }).objects)
+      ? (plain as { objects: ObjectNode[] }).objects
+      : [];
+    const next = mutator(cur, Date.now());
+    if (!next) return;
+    const payload = encryptor
+      ? await encryptor.encrypt({ objects: next }) as Record<string, unknown>
+      : { objects: next };
+    try {
+      await client.push(pushPath, payload, res?.hash ?? null);
+      return;
+    } catch (err) {
+      if (err instanceof ConflictError && attempt < MAX_ATTEMPTS - 1) continue;
+      throw err;
+    }
+  }
+}

package/src/spaces/registry.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi } from 'vitest';
+import type { StarfishClient } from '@drakkar.software/starfish-client';
+import { readRooms, writeRooms, addSpaceMember, removeSpaceMember } from './registry.js';
+
+// ── Fake client ────────────────────────────────────────────────────────────────
+
+function makeRoomsClient(data: unknown, hash = 'h1'): StarfishClient {
+  return {
+    pull: vi.fn().mockResolvedValue({ data, hash }),
+    push: vi.fn().mockResolvedValue(undefined),
+  } as unknown as StarfishClient;
+}
+
+// ── readRooms ──────────────────────────────────────────────────────────────────
+
+describe('readRooms', () => {
+  it('returns visibility null for a private space doc', async () => {
+    const client = makeRoomsClient({ v: 1, owner: 'alice', members: [] });
+    const result = await readRooms(client, 'sp-private');
+    expect(result.visibility).toBeNull();
+  });
+
+  it('returns visibility "public" when doc has visibility:"public"', async () => {
+    const client = makeRoomsClient({ v: 1, owner: 'alice', members: [], visibility: 'public' });
+    const result = await readRooms(client, 'sp-pub');
+    expect(result.visibility).toBe('public');
+  });
+
+  it('returns owner, members, name, image', async () => {
+    const client = makeRoomsClient({
+      v: 1, owner: 'alice', members: ['bob'], name: 'My Space', image: 'data:image/png;base64,abc',
+    });
+    const result = await readRooms(client, 'sp-x');
+    expect(result.owner).toBe('alice');
+    expect(result.members).toEqual(['bob']);
+    expect(result.name).toBe('My Space');
+    expect(result.image).toBe('data:image/png;base64,abc');
+  });
+
+  it('returns null owner/name/image for missing fields', async () => {
+    const client = makeRoomsClient({});
+    const result = await readRooms(client, 'sp-empty');
+    expect(result.owner).toBeNull();
+    expect(result.name).toBeNull();
+    expect(result.image).toBeNull();
+    expect(result.members).toEqual([]);
+  });
+});
+
+// ── writeRooms ─────────────────────────────────────────────────────────────────
+
+describe('writeRooms', () => {
+  it('omits visibility field for a private space', async () => {
+    const client = makeRoomsClient(null);
+    await writeRooms(client, 'sp-priv', 'alice', [], null);
+    const [, doc] = (client.push as ReturnType<typeof vi.fn>).mock.calls[0] as [string, Record<string, unknown>];
+    expect(doc).not.toHaveProperty('visibility');
+  });
+
+  it('emits visibility:"public" for a public space', async () => {
+    const client = makeRoomsClient(null);
+    await writeRooms(client, 'sp-pub', 'alice', [], null, { visibility: 'public' });
+    const [, doc] = (client.push as ReturnType<typeof vi.fn>).mock.calls[0] as [string, Record<string, unknown>];
+    expect(doc).toHaveProperty('visibility', 'public');
+  });
+
+  it('preserves name and image', async () => {
+    const client = makeRoomsClient(null);
+    await writeRooms(client, 'sp-x', 'alice', ['bob'], null, { name: 'Test', image: 'data:x' });
+    const [, doc] = (client.push as ReturnType<typeof vi.fn>).mock.calls[0] as [string, Record<string, unknown>];
+    expect(doc).toHaveProperty('name', 'Test');
+    expect(doc).toHaveProperty('image', 'data:x');
+  });
+});
+
+// ── addSpaceMember / removeSpaceMember ────────────────────────────────────────
+
+describe('addSpaceMember', () => {
+  it('adds a member and preserves visibility', async () => {
+    const client = makeRoomsClient({ v: 1, owner: 'alice', members: [], visibility: 'public' });
+    await addSpaceMember(client, 'sp-pub', 'alice', 'bob');
+    const [, doc] = (client.push as ReturnType<typeof vi.fn>).mock.calls[0] as [string, Record<string, unknown>];
+    expect((doc as { members: string[] }).members).toContain('bob');
+    expect(doc).toHaveProperty('visibility', 'public');
+  });
+
+  it('is a no-op when member already present', async () => {
+    const client = makeRoomsClient({ v: 1, owner: 'alice', members: ['bob'] });
+    await addSpaceMember(client, 'sp-x', 'alice', 'bob');
+    expect(client.push).not.toHaveBeenCalled();
+  });
+});
+
+describe('removeSpaceMember', () => {
+  it('removes a member and preserves name/image/visibility', async () => {
+    const client = makeRoomsClient({
+      v: 1, owner: 'alice', members: ['bob', 'carol'], name: 'S', visibility: 'public',
+    });
+    await removeSpaceMember(client, 'sp-pub', 'bob');
+    const [, doc] = (client.push as ReturnType<typeof vi.fn>).mock.calls[0] as [string, Record<string, unknown>];
+    expect((doc as { members: string[] }).members).not.toContain('bob');
+    expect((doc as { members: string[] }).members).toContain('carol');
+    expect(doc).toHaveProperty('visibility', 'public');
+  });
+
+  it('is a no-op when member is not in the roster', async () => {
+    const client = makeRoomsClient({ v: 1, owner: 'alice', members: ['carol'] });
+    await removeSpaceMember(client, 'sp-x', 'unknown');
+    expect(client.push).not.toHaveBeenCalled();
+  });
+});