@drakkar.software/octospaces-sdk 0.1.0

package/src/sync/pairing.ts

@@ -0,0 +1,103 @@
+/**
+ * Device pairing (one-way, PIN-sealed). The existing device provisions a new
+ * device's keypair + cap bundle, seals it with the PIN (Argon2id → AES-GCM), and
+ * drops it on the public `_pairing/<nonce>` rendezvous. The QR carries only the
+ * nonce; the new device fetches the sealed blob, opens it with the PIN, and
+ * validates the cap bundle.
+ */
+import { StarfishClient } from '@drakkar.software/starfish-client';
+import {
+  installPairingBundle,
+  openWithPassphrase,
+  provisionDevice,
+  sealWithPassphrase,
+} from '@drakkar.software/starfish-identities';
+import type { CapCert } from '@drakkar.software/starfish-protocol';
+
+import type { DeviceKeys } from './client.js';
+import { getSyncBase, getSyncNamespace } from '../core/config.js';
+import { fetchWithTimeout } from './fetch-timeout.js';
+import type { Session } from './identity.js';
+import { fingerprintFromUserId } from './identity.js';
+import { addDeviceToSpaceKeyring } from '../spaces/members.js';
+import { bytesToHex, linkedDeviceScope } from './paths.js';
+import { readSpaces } from '../spaces/registry.js';
+
+/** 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. */
+export const PAIR_PREFIX = 'octospaces-pair:';
+
+// Linked-device cap-cert lifetime — one year keeps a linked device usable long-term.
+const LINKED_DEVICE_TTL_SEC = 365 * 24 * 60 * 60;
+
+function anonClient(): StarfishClient {
+  return new StarfishClient({ baseUrl: getSyncBase(), namespace: getSyncNamespace(), fetch: fetchWithTimeout() });
+}
+
+function randomNonce(): string {
+  const b = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(b);
+  return bytesToHex(b);
+}
+
+/** Existing device: provision + PIN-seal a new device, publish to rendezvous, return the QR payload. */
+export async function startDevicePairing(session: Session, pin: string): Promise<string> {
+  const { deviceKeys, bundle } = await provisionDevice(
+    { edPriv: session.keys.edPriv, edPub: session.keys.edPub },
+    { scope: linkedDeviceScope(session.userId), ttlSec: LINKED_DEVICE_TTL_SEC },
+  );
+  const { spaces, caps } = await readSpaces(session.accountClient, session.userId);
+  for (const space of spaces) {
+    if (caps[space.id]) continue;
+    try {
+      await addDeviceToSpaceKeyring(session, space.id, { kemPub: deviceKeys.kemPub, userId: session.userId });
+    } catch (err) {
+      console.log('[pairing] keyring grant failed', { spaceId: space.id, error: String((err as Error)?.message ?? err) });
+    }
+  }
+  const blob = JSON.stringify({ v: 1, keys: deviceKeys, bundle });
+  const sealed = await sealWithPassphrase(pin, new TextEncoder().encode(blob));
+  const nonce = randomNonce();
+  await anonClient().push(`/push/_pairing/${nonce}`, sealed as unknown as Record<string, unknown>, null);
+  return `${PAIR_PREFIX}${nonce}.${session.keys.edPub}`;
+}
+
+export interface PairResult {
+  userId: string;
+  fingerprint: string;
+  deviceKeys: DeviceKeys;
+  capCert: CapCert;
+}
+
+/** New device: fetch the sealed blob by nonce, open with PIN, validate the bundle. */
+export async function completeDevicePairing(payload: string, pin: string): Promise<PairResult> {
+  // Accept both `octospaces-pair:` and legacy `octochat-pair:` so apps still using the
+  // old QR format can complete a pairing against this SDK during the migration window.
+  const body = (payload.startsWith(PAIR_PREFIX) || payload.includes('-pair:')
+    ? payload.slice(payload.indexOf(':') + 1)
+    : payload).trim();
+  const [nonce, expectedRootEdPub] = body.split('.');
+  const res = await anonClient().pull(`/pull/_pairing/${nonce}`).catch(() => null);
+  const sealed = res?.data as Record<string, unknown> | undefined;
+  if (!sealed || !sealed.v) throw new Error('Pairing code not found or expired.');
+  let inner: Uint8Array;
+  try {
+    inner = await openWithPassphrase(pin, sealed as never);
+  } catch {
+    throw new Error('Wrong PIN or corrupted pairing code.');
+  }
+  const blob = JSON.parse(new TextDecoder().decode(inner)) as { keys: unknown; bundle: unknown };
+  const opts = (expectedRootEdPub ? { expectedRootEdPub } : {}) as Parameters<typeof installPairingBundle>[2];
+  const installed = await installPairingBundle(
+    blob.bundle as Parameters<typeof installPairingBundle>[0],
+    blob.keys as Parameters<typeof installPairingBundle>[1],
+    opts,
+  );
+  const userId = installed.credentials.userId;
+  return {
+    userId,
+    fingerprint: fingerprintFromUserId(userId),
+    deviceKeys: installed.credentials.device,
+    capCert: installed.credentials.capCert,
+  };
+}

package/src/sync/paths.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest';
+import {
+  OBJECT_COLLECTIONS,
+  ownerScope,
+  spaceMemberScope,
+  accountScope,
+  linkedDeviceScope,
+  keyringPull,
+  keyringPush,
+  objIndexPull,
+  objIndexPush,
+  spacesPull,
+  spacesPush,
+  profilePull,
+  spaceIndexPull,
+} from './paths.js';
+
+describe('OBJECT_COLLECTIONS', () => {
+  it('contains the canonical generic object collections', () => {
+    expect(OBJECT_COLLECTIONS).toContain('keyring');
+    expect(OBJECT_COLLECTIONS).toContain('objindex');
+    expect(OBJECT_COLLECTIONS).toContain('objlog');
+    expect(OBJECT_COLLECTIONS).toContain('objdoc');
+    expect(OBJECT_COLLECTIONS).toContain('objblob');
+    expect(OBJECT_COLLECTIONS).toContain('typeindex');
+  });
+
+  it('does NOT contain chat-only collections', () => {
+    expect(OBJECT_COLLECTIONS).not.toContain('chat');
+    expect(OBJECT_COLLECTIONS).not.toContain('dminbox');
+  });
+});
+
+describe('ownerScope', () => {
+  it('uses OBJECT_COLLECTIONS', () => {
+    const scope = ownerScope();
+    expect(scope.collections).toEqual(OBJECT_COLLECTIONS);
+  });
+
+  it('includes wildcard ops', () => {
+    const scope = ownerScope();
+    expect(scope.ops).toContain('read');
+    expect(scope.ops).toContain('write');
+  });
+});
+
+describe('spaceMemberScope', () => {
+  it('scopes to the given spaceId path', () => {
+    const scope = spaceMemberScope('sp-abc', true);
+    expect(scope.paths).toEqual(expect.arrayContaining([expect.stringContaining('sp-abc')]));
+  });
+
+  it('write=true grants write ops', () => {
+    const scope = spaceMemberScope('sp-abc', true);
+    expect(scope.ops).toContain('write');
+  });
+
+  it('write=false omits write ops', () => {
+    const scope = spaceMemberScope('sp-abc', false);
+    expect(scope.ops).not.toContain('write');
+  });
+
+  it('collections equal OBJECT_COLLECTIONS', () => {
+    const scope = spaceMemberScope('sp-abc', true);
+    expect(scope.collections).toEqual(OBJECT_COLLECTIONS);
+  });
+});
+
+describe('accountScope', () => {
+  it('does NOT contain dminbox', () => {
+    const scope = accountScope('user-1');
+    expect(scope.collections).not.toContain('dminbox');
+  });
+
+  it('does NOT contain pubspace', () => {
+    const scope = accountScope('user-1');
+    expect(scope.collections).not.toContain('pubspace');
+  });
+
+  it('does NOT include pubspaces/ paths', () => {
+    const scope = accountScope('user-1');
+    const hasPubspaces = (scope.paths ?? []).some((p) => p.includes('pubspaces/'));
+    expect(hasPubspaces).toBe(false);
+  });
+
+  it('scopes to the given userId', () => {
+    const scope = accountScope('user-1');
+    expect(scope.paths).toEqual(expect.arrayContaining([expect.stringContaining('user-1')]));
+  });
+});
+
+describe('linkedDeviceScope', () => {
+  it('contains both object and account collections', () => {
+    const scope = linkedDeviceScope('user-1');
+    expect(scope.collections).toEqual(expect.arrayContaining(['keyring', 'profile', 'spaces']));
+  });
+
+  it('does NOT contain pubspace', () => {
+    const scope = linkedDeviceScope('user-1');
+    expect(scope.collections).not.toContain('pubspace');
+  });
+
+  it('does NOT include pubspaces/ paths', () => {
+    const scope = linkedDeviceScope('user-1');
+    const hasPubspaces = (scope.paths ?? []).some((p) => p.includes('pubspaces/'));
+    expect(hasPubspaces).toBe(false);
+  });
+});
+
+describe('spaceIndexPull', () => {
+  it('returns a pull path for the public shard', () => {
+    expect(spaceIndexPull('public')).toContain('public');
+  });
+});
+
+describe('path helpers', () => {
+  it('keyringPull / keyringPush are symmetric', () => {
+    expect(keyringPull('sp-1')).toContain('sp-1');
+    expect(keyringPush('sp-1')).toContain('sp-1');
+  });
+
+  it('objIndexPull / objIndexPush are symmetric', () => {
+    expect(objIndexPull('sp-1')).toContain('sp-1');
+    expect(objIndexPush('sp-1')).toContain('sp-1');
+  });
+
+  it('spacesPull / spacesPush use the userId', () => {
+    expect(spacesPull('alice')).toContain('alice');
+    expect(spacesPush('alice')).toContain('alice');
+  });
+
+  it('profilePull uses the userId', () => {
+    expect(profilePull('alice')).toContain('alice');
+  });
+});

package/src/sync/paths.ts

@@ -0,0 +1,177 @@
+/**
+ * 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.
+ */
+import type { ScopePreset } from '@drakkar.software/starfish-identities';
+
+const pull = (rest: string) => `/pull/${rest}`;
+const push = (rest: string) => `/push/${rest}`;
+
+/** A room id is `sp-<rand>-<name>`; the space is its first two `-` segments. */
+export const spaceIdFromRoomId = (roomId: string) => roomId.split('-').slice(0, 2).join('-');
+
+// ── Space-wide keyring (one per space, shared by all its channels) ────────────
+export const keyringName = (spaceId: string) => `spaces/${spaceId}`;
+export const keyringPull = (spaceId: string) => pull(`${keyringName(spaceId)}/_keyring`);
+export const keyringPush = (spaceId: string) => push(`${keyringName(spaceId)}/_keyring`);
+
+// ── Attachments (sealed blobs, in a per-space subtree keyed by room) ──────────
+/** Storage path of one attachment blob — also the AAD bound into its seal. */
+export const attachmentName = (roomId: string, blobId: string) =>
+  `spaces/${spaceIdFromRoomId(roomId)}/attachments/${roomId}/${blobId}`;
+export const attachmentPull = (roomId: string, blobId: string) => pull(attachmentName(roomId, blobId));
+export const attachmentPush = (roomId: string, blobId: string) => push(attachmentName(roomId, blobId));
+
+// ── Profile + registries ──────────────────────────────────────────────────────
+export const profilePull = (userId: string) => pull(`user/${userId}/profile`);
+export const profilePush = (userId: string) => push(`user/${userId}/profile`);
+
+export const spacesPull = (userId: string) => pull(`user/${userId}/_spaces`);
+export const spacesPush = (userId: string) => push(`user/${userId}/_spaces`);
+
+export const roomsRegistryPull = (spaceId: string) => pull(`spaces/${spaceId}/_rooms`);
+export const roomsRegistryPush = (spaceId: string) => push(`spaces/${spaceId}/_rooms`);
+
+// ── Unified Object index + content (private/E2EE) ─────────────────────────────
+// ALL Object content lives in one generic path family — no type-specific prefixes:
+//
+//   objects/_index          — union-merged ObjectNode tree (every Object in the space)
+//   objects/logs/{id}       — WAL/CRDT append-only op-log (contentKind "append")
+//   objects/logs/{id}__snapshot — sibling LWW snapshot for fast cold-start
+//   objects/docs/{id}       — LWW merge-doc (contentKind "merge": records, captions)
+//   objects/blobs/{id}      — sealed raw binary blob (file/image objects)
+//
+// Keep in sync with the objindex/objlog/objsnap/objdoc/objblob collections in
+// apps/server AND Infra collections.py.
+export const objIndexName = (spaceId: string) => `spaces/${spaceId}/objects/_index`;
+export const objIndexPull = (spaceId: string) => pull(objIndexName(spaceId));
+export const objIndexPush = (spaceId: string) => push(objIndexName(spaceId));
+
+export const objLogName = (spaceId: string, objectId: string) => `spaces/${spaceId}/objects/logs/${objectId}`;
+export const objLogPull = (spaceId: string, objectId: string) => pull(objLogName(spaceId, objectId));
+export const objLogPush = (spaceId: string, objectId: string) => push(objLogName(spaceId, objectId));
+
+export const objDocName = (spaceId: string, objectId: string) => `spaces/${spaceId}/objects/docs/${objectId}`;
+export const objDocPull = (spaceId: string, objectId: string) => pull(objDocName(spaceId, objectId));
+export const objDocPush = (spaceId: string, objectId: string) => push(objDocName(spaceId, objectId));
+
+/** Storage path of one sealed object blob — also the AAD bound into its seal. */
+export const objectBlobName = (spaceId: string, blobId: string) => `spaces/${spaceId}/objects/blobs/${blobId}`;
+export const objectBlobPull = (spaceId: string, blobId: string) => pull(objectBlobName(spaceId, blobId));
+export const objectBlobPush = (spaceId: string, blobId: string) => push(objectBlobName(spaceId, blobId));
+
+// ── Per-space custom type registry (private/E2EE) ─────────────────────────────
+export const typesIndexName = (spaceId: string) => `spaces/${spaceId}/types/_index`;
+export const typesIndexPull = (spaceId: string) => pull(typesIndexName(spaceId));
+export const typesIndexPush = (spaceId: string) => push(typesIndexName(spaceId));
+
+// ── Public-space directory index (server-maintained projection) ───────────────
+export const spaceIndexName = (shard: 'public') => `_index/spaces/${shard}`;
+export const spaceIndexPull = (shard: 'public') => pull(spaceIndexName(shard));
+
+// ── Generic object collections — used in cap scopes ──────────────────────────
+// These are the domain-neutral storage collections both apps migrate onto. The
+// server ignores unrecognized collection names, so a cap minted with this set still
+// authorizes an app whose data currently lives under a legacy collection name during
+// the migration transition.
+export const OBJECT_COLLECTIONS: string[] = [
+  'keyring', 'objindex', 'objlog', 'objsnap', 'objdoc', 'objblob', 'typeindex',
+];
+
+// ── Cap scopes ────────────────────────────────────────────────────────────────
+
+/** Full owner/device access to every space the identity owns. */
+export function ownerScope(): ScopePreset {
+  return {
+    ops: ['read', 'list', 'write'],
+    collections: OBJECT_COLLECTIONS,
+    paths: ['spaces/**'],
+  };
+}
+
+/**
+ * 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.
+ */
+export function spaceMemberScope(spaceId: string, canWrite: boolean): ScopePreset {
+  const ops: ('read' | 'write' | 'list')[] = canWrite ? ['read', 'list', 'write'] : ['read', 'list'];
+  return {
+    ops,
+    collections: OBJECT_COLLECTIONS,
+    paths: [`spaces/${spaceId}/**`],
+  };
+}
+
+/**
+ * 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.
+ */
+export function accountScope(userId: string): ScopePreset {
+  return {
+    ops: ['read', 'list', 'write'],
+    collections: ['profile', 'devices', 'spaces', 'rooms'],
+    paths: [
+      `user/${userId}/profile`,
+      `users/${userId}/_devices`,
+      `user/${userId}/_spaces`,
+      'spaces/**',
+    ],
+  };
+}
+
+/**
+ * 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.
+ */
+export function linkedDeviceScope(userId: string): ScopePreset {
+  return {
+    ops: ['read', 'list', 'write'],
+    collections: [...OBJECT_COLLECTIONS, 'profile', 'devices', 'spaces', 'rooms'],
+    paths: [
+      'spaces/**',
+      `user/${userId}/profile`,
+      `users/${userId}/_devices`,
+      `user/${userId}/_spaces`,
+    ],
+  };
+}
+
+/** Extract the single space id a member cap is scoped to (from its `spaces/<id>/**`).
+ *  Returns null if the cap names no space path OR more than one distinct space. */
+export function spaceIdFromCap(cap: { scope?: { paths?: string[] } }): string | null {
+  let found: string | null = null;
+  for (const p of cap.scope?.paths ?? []) {
+    const m = /^spaces\/([^/]+)\//.exec(p);
+    if (!m) continue;
+    if (found !== null && found !== m[1]) return null;
+    found = m[1]!;
+  }
+  return found;
+}
+
+export function bytesToHex(b: Uint8Array): string {
+  let s = '';
+  for (const x of b) s += x.toString(16).padStart(2, '0');
+  return s;
+}
+
+/** The canonical identity derivation: `userId = sha256(edPub)[0:32]` (hex). */
+export async function userIdFromEdPub(edPubHex: string): Promise<string> {
+  const bytes = new Uint8Array(edPubHex.length / 2);
+  for (let i = 0; i < bytes.length; i++) bytes[i] = parseInt(edPubHex.slice(i * 2, i * 2 + 2), 16);
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes);
+  return bytesToHex(new Uint8Array(digest)).slice(0, 32);
+}

package/src/sync/profile-cache.ts

@@ -0,0 +1,34 @@
+/**
+ * Offline-first cache for public profiles (pseudo + inline avatar).
+ *
+ * Profiles are PUBLIC plaintext so they don't flow through the SDK's read-through
+ * pull cache. This kv cache gives them the same offline-first behavior: a successful
+ * read is persisted per user, and a read that fails because the device is offline
+ * falls back to the last-known pseudo/avatar.
+ */
+import { kvGet, kvSet } from '../core/adapters.js';
+import type { PublicProfile } from './client.js';
+
+const key = (userId: string) => `octospaces.profile.v1.${userId}`;
+
+/** Persist a freshly-read profile (fire-and-forget). */
+export function cacheProfile(userId: string, profile: PublicProfile): void {
+  void kvSet(key(userId), JSON.stringify(profile)).catch(() => {});
+}
+
+/** Last-known profile for a user, or null if never cached / unparseable. */
+export async function loadCachedProfile(userId: string): Promise<PublicProfile | null> {
+  try {
+    const raw = await kvGet(key(userId));
+    if (!raw) return null;
+    const d = JSON.parse(raw) as Partial<PublicProfile>;
+    return {
+      pseudo: typeof d.pseudo === 'string' ? d.pseudo : null,
+      avatar: typeof d.avatar === 'string' ? d.avatar : null,
+      edPub: typeof d.edPub === 'string' ? d.edPub : null,
+      kemPub: typeof d.kemPub === 'string' ? d.kemPub : null,
+    };
+  } catch {
+    return null;
+  }
+}

package/src/sync/pull-cache.test.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { configureKv } from '../core/adapters.js';
+import { pullCache, PULL_CACHE_MAX_AGE_MS } from './pull-cache.js';
+
+// Reset the singleton between tests by resetting the module-level `shared`
+// — we work around it by reconfiguring KV with a fresh store each time.
+let store: Map<string, string>;
+
+function makeKv() {
+  store = new Map<string, string>();
+  configureKv({
+    get: (k) => Promise.resolve(store.get(k) ?? null),
+    set: (k, v) => { store.set(k, v); return Promise.resolve(); },
+    remove: (k) => { store.delete(k); return Promise.resolve(); },
+  });
+}
+
+describe('PULL_CACHE_MAX_AGE_MS', () => {
+  it('is a positive number', () => {
+    expect(PULL_CACHE_MAX_AGE_MS).toBeGreaterThan(0);
+  });
+});
+
+describe('pullCache', () => {
+  beforeEach(() => { makeKv(); });
+
+  it('returns an object with get and set', () => {
+    const cache = pullCache();
+    expect(typeof cache.get).toBe('function');
+    expect(typeof cache.set).toBe('function');
+  });
+
+  it('set + get round-trip stores and retrieves a string', async () => {
+    const cache = pullCache();
+    const key = 'test-key';
+    const value = JSON.stringify({ data: { hello: 'world' }, hash: 'abc123' });
+    await cache.set(key, value);
+    const hit = await cache.get(key);
+    expect(hit).toBe(value);
+  });
+
+  it('returns null for unknown key', async () => {
+    const cache = pullCache();
+    const hit = await cache.get('no-such-key');
+    expect(hit).toBeNull();
+  });
+
+  it('uses octospaces.pullcache. prefix internally', async () => {
+    const cache = pullCache();
+    await cache.set('mykey', 'myvalue');
+    // The key in the underlying store should have the prefix
+    const raw = store.get('octospaces.pullcache.mykey');
+    expect(raw).toBe('myvalue');
+  });
+});

package/src/sync/pull-cache.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+import type { PullCache } from '@drakkar.software/starfish-client';
+
+import { kvGet, kvSet } from '../core/adapters.js';
+
+const PREFIX = 'octospaces.pullcache.';
+
+/**
+ * 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.
+ */
+export const PULL_CACHE_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000;
+
+let shared: PullCache | undefined;
+
+/** The shared app-wide pull cache (one instance, reused across every client). */
+export function pullCache(): PullCache {
+  return (shared ??= {
+    get: (key) => kvGet(PREFIX + key),
+    set: (key, value) => kvSet(PREFIX + key, value),
+  });
+}

package/src/sync/space-access-store.test.ts

@@ -0,0 +1,129 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { configureKv } from '../core/adapters.js';
+import {
+  clearSpaceAccessStore,
+  getSpaceAccessEntry,
+  hydrateSpaceAccessStore,
+  localSpaceAccessEntries,
+  memberCapsFromStore,
+  linkAccessFromStore,
+  removeSpaceAccessEntry,
+  saveSpaceAccessEntry,
+} from './space-access-store.js';
+
+let store: Map<string, string>;
+
+function makeKvStore() {
+  store = new Map<string, string>();
+  configureKv({
+    get: (k) => Promise.resolve(store.get(k) ?? null),
+    set: (k, v) => { store.set(k, v); return Promise.resolve(); },
+    remove: (k) => { store.delete(k); return Promise.resolve(); },
+  });
+  return store;
+}
+
+describe('space-access-store', () => {
+  beforeEach(() => {
+    clearSpaceAccessStore();
+    makeKvStore();
+  });
+
+  it('returns null for unknown space', () => {
+    expect(getSpaceAccessEntry('sp-unknown')).toBeNull();
+  });
+
+  it('save + get member round-trip', () => {
+    saveSpaceAccessEntry('sp-test', { kind: 'member', cap: '{"kind":"member"}' });
+    expect(getSpaceAccessEntry('sp-test')).toEqual({ kind: 'member', cap: '{"kind":"member"}' });
+  });
+
+  it('save + get link round-trip', () => {
+    saveSpaceAccessEntry('sp-pub', { kind: 'link', cap: { kind: 'member' }, key: 'hexkey', write: true });
+    const entry = getSpaceAccessEntry('sp-pub');
+    expect(entry?.kind).toBe('link');
+    if (entry?.kind === 'link') {
+      expect(entry.key).toBe('hexkey');
+      expect(entry.write).toBe(true);
+    }
+  });
+
+  it('remove drops a stored entry', () => {
+    saveSpaceAccessEntry('sp-abc', { kind: 'member', cap: 'capjson' });
+    removeSpaceAccessEntry('sp-abc');
+    expect(getSpaceAccessEntry('sp-abc')).toBeNull();
+  });
+
+  it('clear wipes all entries', () => {
+    saveSpaceAccessEntry('sp-1', { kind: 'member', cap: 'a' });
+    saveSpaceAccessEntry('sp-2', { kind: 'member', cap: 'b' });
+    clearSpaceAccessStore();
+    expect(getSpaceAccessEntry('sp-1')).toBeNull();
+    expect(getSpaceAccessEntry('sp-2')).toBeNull();
+  });
+
+  it('hydrate loads caps from kv', async () => {
+    const caps = { 'sp-x': '{"kind":"member","sub":"abc"}' };
+    store.set('octospaces.spaceaccess.user123', JSON.stringify({
+      'sp-x': { kind: 'member', cap: '{"kind":"member","sub":"abc"}' },
+    }));
+    clearSpaceAccessStore();
+    await hydrateSpaceAccessStore('user123', {}, {});
+    expect(getSpaceAccessEntry('sp-x')).toEqual({ kind: 'member', cap: '{"kind":"member","sub":"abc"}' });
+    void caps;
+  });
+
+  it('server caps override local on hydrate', async () => {
+    // Local has old value
+    store.set('octospaces.spaceaccess.user1', JSON.stringify({
+      'sp-a': { kind: 'member', cap: 'old-cap' },
+    }));
+    clearSpaceAccessStore();
+    await hydrateSpaceAccessStore('user1', { 'sp-a': 'new-cap' }, {});
+    expect(getSpaceAccessEntry('sp-a')).toEqual({ kind: 'member', cap: 'new-cap' });
+  });
+
+  it('server link access populates link entries', async () => {
+    clearSpaceAccessStore();
+    await hydrateSpaceAccessStore('user2', {}, {
+      'sp-link': { cap: { kind: 'member' }, key: 'privhex', write: false },
+    });
+    const entry = getSpaceAccessEntry('sp-link');
+    expect(entry?.kind).toBe('link');
+    if (entry?.kind === 'link') expect(entry.write).toBe(false);
+  });
+
+  it('uses octospaces. prefix for kv key (not octochat.)', async () => {
+    saveSpaceAccessEntry('sp-test', { kind: 'member', cap: '{"kind":"member"}' });
+    store.set('octospaces.spaceaccess.user-abc', JSON.stringify({
+      'sp-test': { kind: 'member', cap: '{"kind":"member"}' },
+    }));
+    clearSpaceAccessStore();
+    await hydrateSpaceAccessStore('user-abc', {}, {});
+    const legacyKey = Array.from(store.keys()).find((k) => k.startsWith('octochat.'));
+    expect(legacyKey).toBeUndefined();
+  });
+
+  it('memberCapsFromStore returns only member entries', () => {
+    saveSpaceAccessEntry('sp-m', { kind: 'member', cap: 'cap1' });
+    saveSpaceAccessEntry('sp-l', { kind: 'link', cap: {}, key: 'k', write: false });
+    const caps = memberCapsFromStore();
+    expect(caps).toHaveProperty('sp-m', 'cap1');
+    expect(caps).not.toHaveProperty('sp-l');
+  });
+
+  it('linkAccessFromStore returns only link entries', () => {
+    saveSpaceAccessEntry('sp-m', { kind: 'member', cap: 'cap1' });
+    saveSpaceAccessEntry('sp-l', { kind: 'link', cap: { iss: 'abc' }, key: 'k', write: true });
+    const links = linkAccessFromStore();
+    expect(links).toHaveProperty('sp-l');
+    expect(links['sp-l']?.write).toBe(true);
+    expect(links).not.toHaveProperty('sp-m');
+  });
+
+  it('localSpaceAccessEntries returns a snapshot', () => {
+    saveSpaceAccessEntry('sp-snap', { kind: 'member', cap: 'c' });
+    const snap = localSpaceAccessEntries();
+    expect(snap).toHaveProperty('sp-snap');
+  });
+});