@drakkar.software/octospaces-sdk 0.1.0

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

@@ -0,0 +1,117 @@
+/**
+ * Unified local access store for spaces this identity has joined.
+ *
+ * Replaces the separate `member-caps.ts` (private spaces) and `pubspace-caps.ts`
+ * (public/link spaces). Two entry kinds:
+ *   - `member`: a member cap-cert (plain JSON, no bearer secret — safe to store
+ *     in the clear). Used for PRIVATE space keyring opens.
+ *   - `link`: an ephemeral-subject cap + the link's Ed25519 private key. Embeds a
+ *     bearer secret so it is SEALED in the synced `_spaces.pubAccess` field before
+ *     leaving this device; the local kv stores it plaintext only on the owning device.
+ *
+ * Two tiers (same as old member-caps): device-local kv (fast, offline) and the
+ * user's synced `_spaces` doc (durable source of truth; merged over local on hydrate).
+ * Keyed PER-USER so multiple accounts on one device never see each other's entries.
+ */
+import type { CapMap, PubAccessMap } from '../core/types.js';
+import type { SealedBlob } from './account-seal.js';
+import { kvGet, kvSet } from '../core/adapters.js';
+
+export type SpaceAccessEntry =
+  | { kind: 'member'; cap: string }
+  | { kind: 'link'; cap: unknown; key: string; write: boolean };
+
+export type SpaceAccessMap = Record<string, SpaceAccessEntry>;
+
+const keyFor = (userId: string) => `octospaces.spaceaccess.${userId}`;
+
+let cache: SpaceAccessMap = {};
+let activeKey: string | null = null;
+
+/**
+ * Load the active account's space-access entries into memory. Call (and await) on
+ * sign-in and on every account switch, before opening rooms.
+ *
+ * `serverCaps` (private member caps from `_spaces.caps`) and `serverPubAccess`
+ * (sealed link credentials from `_spaces.pubAccess`, already unsealed by the caller)
+ * are merged OVER the local kv cache (server wins).
+ */
+export async function hydrateSpaceAccessStore(
+  userId: string,
+  serverCaps: CapMap,
+  serverLinkAccess: Record<string, { cap: unknown; key: string; write: boolean }>,
+): Promise<void> {
+  const key = keyFor(userId);
+  if (activeKey === key) return;
+  activeKey = key;
+  cache = {};
+  const raw = await kvGet(key);
+  if (raw) {
+    try {
+      cache = JSON.parse(raw) as SpaceAccessMap;
+    } catch (e) {
+      console.error('[octospaces] space-access-store: corrupt cache, resetting:', e);
+      cache = {};
+    }
+  }
+  let changed = false;
+  for (const [spaceId, capJson] of Object.entries(serverCaps)) {
+    cache[spaceId] = { kind: 'member', cap: capJson };
+    changed = true;
+  }
+  for (const [spaceId, access] of Object.entries(serverLinkAccess)) {
+    cache[spaceId] = { kind: 'link', cap: access.cap, key: access.key, write: access.write };
+    changed = true;
+  }
+  if (changed) await kvSet(key, JSON.stringify(cache));
+}
+
+function persist(): void {
+  if (activeKey) void kvSet(activeKey, JSON.stringify(cache));
+}
+
+export function getSpaceAccessEntry(spaceId: string): SpaceAccessEntry | null {
+  return cache[spaceId] ?? null;
+}
+
+export function saveSpaceAccessEntry(spaceId: string, entry: SpaceAccessEntry): void {
+  cache = { ...cache, [spaceId]: entry };
+  persist();
+}
+
+/** Forget one space's access (on leaving that space). */
+export function removeSpaceAccessEntry(spaceId: string): void {
+  if (!(spaceId in cache)) return;
+  const next = { ...cache };
+  delete next[spaceId];
+  cache = next;
+  persist();
+}
+
+/** A snapshot of the in-memory cache — used by `recoverSpaceAccess` to find entries
+ *  not yet on the server. */
+export function localSpaceAccessEntries(): SpaceAccessMap {
+  return cache;
+}
+
+/** Build the `CapMap` slice (member entries only) for persisting into `_spaces.caps`. */
+export function memberCapsFromStore(): CapMap {
+  const out: CapMap = {};
+  for (const [id, e] of Object.entries(cache)) if (e.kind === 'member') out[id] = e.cap;
+  return out;
+}
+
+/** Build the `PubAccessMap` slice (link entries already sealed by the caller). */
+export function linkAccessFromStore(): Record<string, { cap: unknown; key: string; write: boolean }> {
+  const out: Record<string, { cap: unknown; key: string; write: boolean }> = {};
+  for (const [id, e] of Object.entries(cache)) {
+    if (e.kind === 'link') out[id] = { cap: e.cap, key: e.key, write: e.write };
+  }
+  return out;
+}
+
+/** Drop the in-memory cache (on account switch / sign-out). */
+export function clearSpaceAccessStore(): void {
+  cache = {};
+  activeKey = null;
+}

package/src/sync/space-access.ts

@@ -0,0 +1,136 @@
+/**
+ * Space access resolver — returns the right (client, encryptor) pair for any
+ * space regardless of whether it is private (E2EE) or public (plaintext).
+ *
+ * Replaces `space-encryptor.ts`. The key invariant: public spaces have
+ * `encryptor: null`; private spaces always have a live `Encryptor`.
+ *
+ * Resolution order (same semantics as the old `getSpaceEncryptor`):
+ *   1. Link entry in the access store → sign requests as the ephemeral identity;
+ *      no keyring, encryptor null.
+ *   2. Member entry → open the keyring as a recipient with the stored cap.
+ *   3. No entry + visibility === 'public' (from `reg`) → owner mode, no keyring.
+ *   4. No entry, private → either owner (open/mint keyring) or SpaceAccessError
+ *      if the space's roster shows we're a member but we're not holding a cap yet.
+ */
+import type { Encryptor, StarfishClient } from '@drakkar.software/starfish-client';
+
+import { buildEncryptor, makeClient, openEncryptor, ownerEnsureKeyring } from './client.js';
+import type { Session } from './identity.js';
+import { ownerTrustedAdders } from './identity.js';
+import { getSpaceAccessEntry } from './space-access-store.js';
+import { SpaceAccessError } from '../core/space-access-error.js';
+import type { SpaceVisibility } from '../core/types.js';
+
+// Re-export so existing importers keep reaching SpaceAccessError through this module.
+export { SpaceAccessError };
+
+export interface SpaceAccessHandle {
+  encryptor: Encryptor | null;
+  client: StarfishClient;
+  /** True when opened as the space OWNER (so the caller must seed the room doc). */
+  isOwnerOpen: boolean;
+}
+
+const cache = new Map<string, Promise<SpaceAccessHandle>>();
+
+/** Drop every cached handle (on account switch — keys are per-identity). */
+export function clearSpaceAccessCache(): void {
+  cache.clear();
+}
+
+/**
+ * Resolve the right (client, encryptor) for a space, opening and caching on first use.
+ *
+ * `reg` is the space's `_rooms` access record if already known. Pass null when the
+ * caller has not yet read the registry; the resolver will probe if needed.
+ */
+export function getSpaceAccess(
+  spaceId: string,
+  session: Session,
+  reg: { owner: string | null; members: string[]; visibility?: SpaceVisibility } | null,
+): Promise<SpaceAccessHandle> {
+  const hit = cache.get(spaceId);
+  if (hit) return hit;
+  const p = (async (): Promise<SpaceAccessHandle> => {
+    const entry = getSpaceAccessEntry(spaceId);
+
+    // 1. Link entry — ephemeral identity; no keyring
+    if (entry?.kind === 'link') {
+      const cap = entry.cap;
+      const client = makeClient(cap, entry.key);
+      return { encryptor: null, client, isOwnerOpen: false };
+    }
+
+    // 2. Member entry — open as a keyring recipient
+    if (entry?.kind === 'member') {
+      const cap = JSON.parse(entry.cap) as { iss?: string };
+      const client = makeClient(cap, session.keys.edPriv);
+      const encryptor = await openEncryptor(client, session.keys, spaceId, cap.iss ? [cap.iss] : []);
+      return { encryptor, client, isOwnerOpen: false };
+    }
+
+    // 3. No entry — branch on visibility
+    const visibility = reg?.visibility;
+    if (visibility === 'public') {
+      return { encryptor: null, client: session.chatClient, isOwnerOpen: reg!.owner === session.userId };
+    }
+
+    // 4. No entry, private — owner or error
+    const owner = reg?.owner ?? null;
+    const members = reg?.members ?? [];
+    if (owner !== null && owner !== session.userId) {
+      throw new SpaceAccessError(
+        members.includes(session.userId)
+          ? "You're a member of this space, but its key isn't on this device yet — reconnect, or ask the owner to re-invite."
+          : "You don't have access to this space.",
+      );
+    }
+    const encryptor = await ownerEnsureKeyring(
+      session.chatClient,
+      session.keys,
+      spaceId,
+      ownerTrustedAdders(session),
+    );
+    return { encryptor, client: session.chatClient, isOwnerOpen: true };
+  })();
+  cache.set(spaceId, p);
+  p.catch(() => cache.delete(spaceId));
+  return p;
+}
+
+/**
+ * SOFT resolve — never mints a keyring, never throws on missing access.
+ * Returns null when the identity has no usable access for the space yet.
+ */
+export async function buildSpaceAccess(
+  session: Session,
+  spaceId: string,
+  hint?: { visibility?: SpaceVisibility },
+): Promise<{ client: StarfishClient; encryptor: Encryptor | null } | null> {
+  const entry = getSpaceAccessEntry(spaceId);
+
+  if (entry?.kind === 'link') {
+    const client = makeClient(entry.cap, entry.key);
+    return { client, encryptor: null };
+  }
+
+  let client = session.chatClient;
+  let trustedAdders = ownerTrustedAdders(session);
+
+  if (entry?.kind === 'member') {
+    const cap = JSON.parse(entry.cap) as { iss?: string };
+    client = makeClient(cap, session.keys.edPriv);
+    if (cap.iss) trustedAdders = [cap.iss];
+    const encryptor = await buildEncryptor(client, session.keys, spaceId, trustedAdders);
+    return encryptor ? { client, encryptor } : null;
+  }
+
+  if (hint?.visibility === 'public') {
+    return { client, encryptor: null };
+  }
+
+  // No entry, no hint — try the keyring probe (owner path)
+  const encryptor = await buildEncryptor(client, session.keys, spaceId, trustedAdders);
+  return encryptor ? { client, encryptor } : null;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2020", "DOM"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,40 @@
+import { defineConfig } from 'tsup';
+
+// Deps that will never be present at SDK build time (native peer deps)
+const NATIVE_EXTERNALS = [
+  'react-native-quick-crypto',
+  '@react-native-async-storage/async-storage',
+];
+
+export default defineConfig([
+  {
+    entry: { index: 'src/index.ts' },
+    format: ['esm'],
+    dts: true,
+    clean: true,
+    splitting: false,
+    sourcemap: true,
+    target: 'es2020',
+  },
+  {
+    entry: { 'platform/index': 'src/platform/index.ts' },
+    format: ['esm'],
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    target: 'es2020',
+    outDir: 'dist',
+  },
+  {
+    entry: { 'platform/index.native': 'src/platform/index.native.ts' },
+    format: ['esm'],
+    dts: true,
+    splitting: false,
+    sourcemap: true,
+    target: 'es2020',
+    outDir: 'dist',
+    external: NATIVE_EXTERNALS,
+    // Do NOT resolve or bundle native platform deps — they are provided at runtime.
+    noExternal: [],
+  },
+]);

package/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    globals: false,
+    include: ['src/**/*.test.ts'],
+    // Run serially — some tests share module-level singletons (member-caps cache).
+    pool: 'forks',
+    poolOptions: { forks: { singleFork: true } },
+  },
+});