@drakkar.software/octospaces-sdk 0.1.0 → 0.4.1

package/src/sync/pairing.ts

@@ -19,9 +19,7 @@ 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. */
@@ -40,21 +38,21 @@ function randomNonce(): string {
   return bytesToHex(b);
 }
 
-/** Existing device: provision + PIN-seal a new device, publish to rendezvous, return the QR payload. */
+/**
+ * Existing device: provision + PIN-seal a new device, publish to rendezvous, return
+ * the QR payload.
+ *
+ * After pairing, call `addDeviceToSpaceKeyring(session, spaceId, newDeviceKeys)` for
+ * each space whose E2EE content the new device should decrypt. ONE space keyring
+ * encrypts ALL `enc` nodes in a space — one call per space unlocks everything.
+ * Plaintext (`space` / `public`) nodes are immediately accessible via the linked-device
+ * cap-cert (no extra keyring step).
+ */
 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();

package/src/sync/paths.test.ts

@@ -3,26 +3,43 @@ import {
   OBJECT_COLLECTIONS,
   ownerScope,
   spaceMemberScope,
+  nodeMemberScope,
   accountScope,
   linkedDeviceScope,
   keyringPull,
   keyringPush,
   objIndexPull,
   objIndexPush,
+  objPubPull,
+  objPubPush,
+  objInvPull,
+  objInvPush,
+  objectDirPull,
   spacesPull,
   spacesPush,
   profilePull,
-  spaceIndexPull,
 } from './paths.js';
 
 describe('OBJECT_COLLECTIONS', () => {
-  it('contains the canonical generic object collections', () => {
-    expect(OBJECT_COLLECTIONS).toContain('keyring');
+  it('contains spacekeyring (space-wide keyring)', () => {
+    expect(OBJECT_COLLECTIONS).toContain('spacekeyring');
+  });
+
+  it('contains the generic object storage collections', () => {
     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');
+    expect(OBJECT_COLLECTIONS).toContain('objpub');
+  });
+
+  it('does NOT contain nodekeyring (removed — keyring is now space-wide)', () => {
+    expect(OBJECT_COLLECTIONS).not.toContain('nodekeyring');
+  });
+
+  it('does NOT contain objinv (invite-only content excluded from broad scope)', () => {
+    expect(OBJECT_COLLECTIONS).not.toContain('objinv');
   });
 
   it('does NOT contain chat-only collections', () => {
@@ -37,7 +54,7 @@ describe('ownerScope', () => {
     expect(scope.collections).toEqual(OBJECT_COLLECTIONS);
   });
 
-  it('includes wildcard ops', () => {
+  it('includes read, list, write ops', () => {
     const scope = ownerScope();
     expect(scope.ops).toContain('read');
     expect(scope.ops).toContain('write');
@@ -64,6 +81,54 @@ describe('spaceMemberScope', () => {
     const scope = spaceMemberScope('sp-abc', true);
     expect(scope.collections).toEqual(OBJECT_COLLECTIONS);
   });
+
+  it('includes spacekeyring (members need to reach the space keyring)', () => {
+    const scope = spaceMemberScope('sp-abc', true);
+    expect(scope.collections).toContain('spacekeyring');
+  });
+
+  it('does NOT include objinv in collections', () => {
+    const scope = spaceMemberScope('sp-abc', true);
+    expect(scope.collections).not.toContain('objinv');
+  });
+});
+
+describe('nodeMemberScope', () => {
+  it('scopes to the specific nodeId path', () => {
+    const scope = nodeMemberScope('sp-1', 'n-42', true);
+    expect(scope.paths).toEqual(
+      expect.arrayContaining([expect.stringContaining('n-42')]),
+    );
+    expect(scope.paths).toEqual(
+      expect.arrayContaining([expect.stringContaining('sp-1')]),
+    );
+  });
+
+  it('includes objinv (invite-plaintext content gate)', () => {
+    const scope = nodeMemberScope('sp-1', 'n-42', true);
+    expect(scope.collections).toContain('objinv');
+  });
+
+  it('does NOT include nodekeyring (keyring is space-wide, not per-node)', () => {
+    const scope = nodeMemberScope('sp-1', 'n-42', true);
+    expect(scope.collections).not.toContain('nodekeyring');
+  });
+
+  it('does NOT include spacekeyring (use spaceMemberScope for enc node access)', () => {
+    const scope = nodeMemberScope('sp-1', 'n-42', true);
+    expect(scope.collections).not.toContain('spacekeyring');
+  });
+
+  it('does NOT include broad space collections', () => {
+    const scope = nodeMemberScope('sp-1', 'n-42', true);
+    expect(scope.collections).not.toContain('objdoc');
+    expect(scope.collections).not.toContain('objpub');
+  });
+
+  it('write=false omits write ops', () => {
+    const scope = nodeMemberScope('sp-1', 'n-42', false);
+    expect(scope.ops).not.toContain('write');
+  });
 });
 
 describe('accountScope', () => {
@@ -90,40 +155,83 @@ describe('accountScope', () => {
 });
 
 describe('linkedDeviceScope', () => {
-  it('contains both object and account collections', () => {
+  it('contains spacekeyring (space-wide keyring)', () => {
     const scope = linkedDeviceScope('user-1');
-    expect(scope.collections).toEqual(expect.arrayContaining(['keyring', 'profile', 'spaces']));
+    expect(scope.collections).toContain('spacekeyring');
   });
 
-  it('does NOT contain pubspace', () => {
+  it('does NOT contain nodekeyring (removed — keyring is space-wide)', () => {
     const scope = linkedDeviceScope('user-1');
-    expect(scope.collections).not.toContain('pubspace');
+    expect(scope.collections).not.toContain('nodekeyring');
   });
 
-  it('does NOT include pubspaces/ paths', () => {
+  it('contains standard account collections', () => {
     const scope = linkedDeviceScope('user-1');
-    const hasPubspaces = (scope.paths ?? []).some((p) => p.includes('pubspaces/'));
-    expect(hasPubspaces).toBe(false);
+    expect(scope.collections).toEqual(expect.arrayContaining(['profile', 'spaces']));
+  });
+
+  it('does NOT contain pubspace', () => {
+    const scope = linkedDeviceScope('user-1');
+    expect(scope.collections).not.toContain('pubspace');
   });
 });
 
-describe('spaceIndexPull', () => {
+describe('objectDirPull', () => {
   it('returns a pull path for the public shard', () => {
-    expect(spaceIndexPull('public')).toContain('public');
+    expect(objectDirPull('public')).toContain('public');
+    expect(objectDirPull('public')).toContain('_index/objects');
+  });
+
+  it('defaults to the public shard', () => {
+    expect(objectDirPull()).toContain('public');
   });
 });
 
-describe('path helpers', () => {
-  it('keyringPull / keyringPush are symmetric', () => {
+describe('space keyring path helpers', () => {
+  it('keyringPull / keyringPush embed spaceId', () => {
     expect(keyringPull('sp-1')).toContain('sp-1');
+    expect(keyringPull('sp-1')).toContain('_keyring');
     expect(keyringPush('sp-1')).toContain('sp-1');
+    expect(keyringPush('sp-1')).toContain('_keyring');
   });
 
-  it('objIndexPull / objIndexPush are symmetric', () => {
+  it('keyringPull and keyringPush are symmetric (same subpath)', () => {
+    const pull = keyringPull('sp-1').replace('/pull/', '/');
+    const push = keyringPush('sp-1').replace('/push/', '/');
+    expect(pull).toBe(push);
+  });
+
+  it('keyringPull path does NOT contain a nodeId segment', () => {
+    const path = keyringPull('sp-42');
+    // Space-wide path: spaces/sp-42/_keyring — no /objects/n/ segment.
+    expect(path).not.toContain('/objects/n/');
+  });
+});
+
+describe('public node content path helpers', () => {
+  it('objPubPull / objPubPush embed spaceId and nodeId', () => {
+    expect(objPubPull('sp-1', 'n-5')).toContain('sp-1');
+    expect(objPubPull('sp-1', 'n-5')).toContain('n-5');
+    expect(objPubPush('sp-1', 'n-5')).toContain('pub');
+  });
+});
+
+describe('invite-only content path helpers', () => {
+  it('objInvPull / objInvPush embed spaceId and nodeId', () => {
+    expect(objInvPull('sp-1', 'n-5')).toContain('sp-1');
+    expect(objInvPull('sp-1', 'n-5')).toContain('n-5');
+    expect(objInvPush('sp-1', 'n-5')).toContain('content');
+  });
+});
+
+describe('object index path helpers', () => {
+  it('objIndexPull / objIndexPush embed spaceId', () => {
     expect(objIndexPull('sp-1')).toContain('sp-1');
     expect(objIndexPush('sp-1')).toContain('sp-1');
   });
+});
 
+describe('other path helpers', () => {
   it('spacesPull / spacesPush use the userId', () => {
     expect(spacesPull('alice')).toContain('alice');
     expect(spacesPush('alice')).toContain('alice');

package/src/sync/paths.ts

@@ -1,5 +1,5 @@
 /**
- * Collection path + cap-scope helpers (merged from OctoChat + OctoVault).
+ * Collection path + cap-scope helpers for OctoSpaces.
  *
  * 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
@@ -8,9 +8,13 @@
  * 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.
+ * domain-neutral storage layer). The access record lives at
+ * `spaces/{spaceId}/_access` (collection `spaceregistry`); the space-wide keyring at
+ * `spaces/{spaceId}/_keyring` (collection `spacekeyring`). ONE keyring per space
+ * encrypts ALL the space's `enc` nodes.
+ *
+ * Note: `objinv` (invite-plaintext content) is intentionally EXCLUDED from
+ * OBJECT_COLLECTIONS / spaceMemberScope — only a per-node cap can reach it.
  */
 import type { ScopePreset } from '@drakkar.software/starfish-identities';
 
@@ -20,7 +24,9 @@ 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) ────────────
+// ── Space-wide keyring (one keyring per space, encrypts all enc nodes) ────────
+/** Base name used as the `collectionName` arg to `addCollectionRecipient`.
+ *  Appending `/_keyring` gives the full storage path. */
 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`);
@@ -39,24 +45,27 @@ 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`);
+export const spaceAccessPull = (spaceId: string) => pull(`spaces/${spaceId}/_access`);
+export const spaceAccessPush = (spaceId: string) => push(`spaces/${spaceId}/_access`);
 
-// ── 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.
+// ── Object index (member-gated, always plaintext) ────────────────────────────
+// The index lists every node with structural fields plaintext. For `invite`
+// nodes the title/emoji are stripped before storage; only invited members read
+// the real title from the node's content doc. Keep in sync with the objindex
+// collection 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));
 
+// ── Space-tier & general object content (space:member gated) ─────────────────
+//
+//   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")
+//   objects/blobs/{id}            — sealed raw binary blob
+//
+// Keep in sync with the objlog/objsnap/objdoc/objblob collections in
+// apps/server AND Infra collections.py.
 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));
@@ -70,22 +79,39 @@ export const objectBlobName = (spaceId: string, blobId: string) => `spaces/${spa
 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) ─────────────────────────────
+// ── Public node content (world-readable) ─────────────────────────────────────
+// For `access:'public'` nodes, content is stored here so anonymous readers can
+// fetch it without being a space member. Keep in sync with objpub in server config.
+export const objPubName = (spaceId: string, nodeId: string) => `spaces/${spaceId}/objects/pub/${nodeId}`;
+export const objPubPull = (spaceId: string, nodeId: string) => pull(objPubName(spaceId, nodeId));
+export const objPubPush = (spaceId: string, nodeId: string) => push(objPubName(spaceId, nodeId));
+
+// ── Invite-only plaintext content (cap-gated) ────────────────────────────────
+// For `access:'invite' + enc:false` nodes, content is stored here. The `objinv`
+// collection is intentionally excluded from spaceMemberScope — only a per-node cap
+// (nodeMemberScope) can reach it. Keep in sync with objinv in server config.
+export const objInvName = (spaceId: string, nodeId: string) => `spaces/${spaceId}/objects/n/${nodeId}/content`;
+export const objInvPull = (spaceId: string, nodeId: string) => pull(objInvName(spaceId, nodeId));
+export const objInvPush = (spaceId: string, nodeId: string) => push(objInvName(spaceId, nodeId));
+
+// ── Per-space custom type registry ────────────────────────────────────────────
 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));
+// ── Global object directory (server-maintained projection) ───────────────────
+// Pull `_index/objects/{shard}` to discover world-readable public nodes.
+// Default shard 'public'; future: sharded by app-supplied type string.
+export const objectDirName = (shard: string = 'public') => `_index/objects/${shard}`;
+export const objectDirPull = (shard: string = 'public') => pull(objectDirName(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.
+// These are the domain-neutral storage collections both apps migrate onto.
+// IMPORTANT: `objinv` is NOT included here — it is excluded from the broad space
+// member scope so that only per-node caps (nodeMemberScope) can reach it.
+// `spacekeyring` IS included — space members need to reach the keyring to decrypt enc content.
 export const OBJECT_COLLECTIONS: string[] = [
-  'keyring', 'objindex', 'objlog', 'objsnap', 'objdoc', 'objblob', 'typeindex',
+  'spacekeyring', 'objindex', 'objlog', 'objsnap', 'objdoc', 'objblob', 'typeindex', 'objpub',
 ];
 
 // ── Cap scopes ────────────────────────────────────────────────────────────────
@@ -100,9 +126,10 @@ export function ownerScope(): ScopePreset {
 }
 
 /**
- * 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.
+ * Member access to one SPACE — the space keyring, every node's content docs and
+ * attachments, all under `spaces/{spaceId}/**`. Does NOT cover `objinv` (invite-
+ * plaintext content) — use `nodeMemberScope` for that. One cap covers current AND
+ * future nodes.
  */
 export function spaceMemberScope(spaceId: string, canWrite: boolean): ScopePreset {
   const ops: ('read' | 'write' | 'list')[] = canWrite ? ['read', 'list', 'write'] : ['read', 'list'];
@@ -113,6 +140,20 @@ export function spaceMemberScope(spaceId: string, canWrite: boolean): ScopePrese
   };
 }
 
+/**
+ * Narrow per-node cap for `invite+plaintext` nodes. Covers ONLY the node's `objinv`
+ * content path — the space keyring is space-wide and is covered by the broader space
+ * member scope. Use `spaceMemberScope` when the bearer also needs to decrypt enc content.
+ */
+export function nodeMemberScope(spaceId: string, nodeId: string, canWrite: boolean): ScopePreset {
+  const ops: ('read' | 'write' | 'list')[] = canWrite ? ['read', 'list', 'write'] : ['read', 'list'];
+  return {
+    ops,
+    collections: ['objinv'],
+    paths: [`spaces/${spaceId}/objects/n/${nodeId}/**`],
+  };
+}
+
 /**
  * Personal cap: profile + space registry + device directory + all spaces.
  * Note: app-specific collections like `'dminbox'` (chat) are NOT included here —
@@ -121,7 +162,7 @@ export function spaceMemberScope(spaceId: string, canWrite: boolean): ScopePrese
 export function accountScope(userId: string): ScopePreset {
   return {
     ops: ['read', 'list', 'write'],
-    collections: ['profile', 'devices', 'spaces', 'rooms'],
+    collections: ['profile', 'devices', 'spaces', 'spaceregistry'],
     paths: [
       `user/${userId}/profile`,
       `users/${userId}/_devices`,
@@ -139,7 +180,7 @@ export function accountScope(userId: string): ScopePreset {
 export function linkedDeviceScope(userId: string): ScopePreset {
   return {
     ops: ['read', 'list', 'write'],
-    collections: [...OBJECT_COLLECTIONS, 'profile', 'devices', 'spaces', 'rooms'],
+    collections: [...OBJECT_COLLECTIONS, 'profile', 'devices', 'spaces', 'spaceregistry'],
     paths: [
       'spaces/**',
       `user/${userId}/profile`,

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

@@ -88,6 +88,23 @@ export function removeSpaceAccessEntry(spaceId: string): void {
   persist();
 }
 
+// ── Per-node access entries (keyed by `${spaceId}:${nodeId}`) ────────────────
+
+/** Look up a per-node invite access entry. Returns null if not invited or unknown. */
+export function getNodeAccessEntry(spaceId: string, nodeId: string): SpaceAccessEntry | null {
+  return cache[`${spaceId}:${nodeId}`] ?? null;
+}
+
+/** Persist an invite access entry for one node. */
+export function saveNodeAccessEntry(spaceId: string, nodeId: string, entry: SpaceAccessEntry): void {
+  saveSpaceAccessEntry(`${spaceId}:${nodeId}`, entry);
+}
+
+/** Forget a node's invite access entry (e.g. on leaving the node). */
+export function removeNodeAccessEntry(spaceId: string, nodeId: string): void {
+  removeSpaceAccessEntry(`${spaceId}:${nodeId}`);
+}
+
 /** A snapshot of the in-memory cache — used by `recoverSpaceAccess` to find entries
  *  not yet on the server. */
 export function localSpaceAccessEntries(): SpaceAccessMap {