@drakkar.software/octospaces-sdk 0.1.0 → 0.4.1

package/src/objects/objects.ts

@@ -1,9 +1,8 @@
 /**
- * Unified Object model — pure logic over the space object index.
+ * Generic object-tree model — pure logic over a space's object index.
  *
- * A space's contents (rooms, categories, docs, projects, tasks, …) are
- * {@link ObjectNode}s in one union-merged index doc at
- * `spaces/{spaceId}/objects/_index`. THIS module is the pure, testable core:
+ * A space's contents are {@link ObjectNode}s in one union-merged index doc at
+ * `spaces/{spaceId}/objects/_index`. This module is the pure, testable core:
  * the tree builder + merge-artifact guards, breadcrumbs, ordering, and the node
  * reducers a `store.set` applies.
  *
@@ -12,21 +11,10 @@
  * or an orphan. The builder below is the single place those are repaired so every
  * consumer renders a well-formed tree.
  *
- * **Transitional bridges** (`objectsToRoomCategories`, `roomKindToSubtype`, …) project
- * the object tree into the legacy `Room`-based shape that apps still speak during their
- * migration onto the object model. They are purely mechanical projections over
- * `ObjectNode` and carry no domain-specific names.
+ * No domain types (room, category, task, …) are defined here. Apps define their own.
  */
-import type { ID, ObjectNode, ObjectType, Room, RoomSubtype } from '../core/types.js';
-import { randomId, roomSlug } from '../core/ids.js';
-
-/** The bucket new/unfiled objects land in, and the fallback a deleted category's
- *  objects are reassigned to. */
-export const DEFAULT_CATEGORY = 'CHANNELS';
-
-/** Deterministic category-node id from its name, so two devices that concurrently
- *  create the SAME category mint the SAME id → the union-merge dedupes them. */
-export const categoryId = (name: string): ID => `cat-${roomSlug(name) || randomId()}`;
+import type { ID, NodeAccess, ObjectNode, ObjectType } from '../core/types.js';
+import { randomId } from '../core/ids.js';
 
 /** A node plus its resolved children — the shape a tree view renders. */
 export interface ObjectTreeNode extends ObjectNode {
@@ -34,25 +22,6 @@ export interface ObjectTreeNode extends ObjectNode {
   children: ObjectTreeNode[];
 }
 
-/** Map a legacy {@link Room} `kind` to the unified room {@link RoomSubtype}. */
-export function roomKindToSubtype(kind: Room['kind']): RoomSubtype {
-  switch (kind) {
-    case 'dm': return 'dm';
-    case 'automated': return 'automation';
-    default: return 'channel';
-  }
-}
-
-/** Inverse of {@link roomKindToSubtype}. A legacy persisted `'stream'` subtype hits
- *  the `default` and reads back as a plain `'channel'` (normalization). */
-export function subtypeToRoomKind(subtype: RoomSubtype | undefined): Room['kind'] {
-  switch (subtype) {
-    case 'dm': return 'dm';
-    case 'automation': return 'automated';
-    default: return 'channel';
-  }
-}
-
 function compareSiblings(a: ObjectNode, b: ObjectNode): number {
   if (a.order !== b.order) return a.order - b.order;
   return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
@@ -151,13 +120,17 @@ export function subtreeIds(nodes: ObjectNode[], rootId: ID): Set<ID> {
 
 export interface NewObjectInput {
   type: ObjectType;
-  subtype?: RoomSubtype;
   parentId?: ID | null;
   title: string;
   emoji?: string;
-  automation?: import('../core/types.js').AutomationMeta;
-  /** Provide to reuse an id (e.g. a room id derived elsewhere); else minted. */
+  /** App-specific metadata passed through to node.meta. */
+  meta?: Record<string, unknown>;
+  /** Provide to reuse an id (e.g. a node id derived elsewhere); else minted. */
   id?: ID;
+  /** Who may reach this node. Absent ⇒ `'space'` (all space members). */
+  access?: NodeAccess;
+  /** Whether the node's content is E2EE under its own per-node keyring. Absent ⇒ false. */
+  enc?: boolean;
 }
 
 /** Append a new node under `parentId` at the end of its sibling order. */
@@ -167,19 +140,25 @@ export function addObject(nodes: ObjectNode[], input: NewObjectInput, now: numbe
   const node: ObjectNode = {
     id: input.id ?? `obj-${randomId()}`,
     type: input.type,
-    ...(input.subtype ? { subtype: input.subtype } : {}),
     parentId,
     order: nextOrder(siblings),
     title: input.title,
     ...(input.emoji ? { emoji: input.emoji } : {}),
     updatedAt: now,
-    ...(input.automation ? { automation: input.automation } : {}),
+    ...(input.meta ? { meta: input.meta } : {}),
+    ...(input.access && input.access !== 'space' ? { access: input.access } : {}),
+    ...(input.enc ? { enc: true as const } : {}),
   };
   return { nodes: [...nodes, node], node };
 }
 
-/** Patch a node's mutable metadata (title/emoji/automation), bumping `updatedAt`. */
-export function patchObject(nodes: ObjectNode[], id: ID, patch: Partial<Pick<ObjectNode, 'title' | 'emoji' | 'automation'>>, now: number): ObjectNode[] {
+/** Patch a node's mutable metadata (title/emoji/meta/access/enc), bumping `updatedAt`. */
+export function patchObject(
+  nodes: ObjectNode[],
+  id: ID,
+  patch: Partial<Pick<ObjectNode, 'title' | 'emoji' | 'meta' | 'access' | 'enc'>>,
+  now: number,
+): ObjectNode[] {
   return nodes.map((n) => (n.id === id ? { ...n, ...patch, updatedAt: now } : n));
 }
 
@@ -202,95 +181,3 @@ export function archiveObject(nodes: ObjectNode[], id: ID, now: number): ObjectN
   return nodes.map((n) => (ids.has(n.id) ? { ...n, archived: true, updatedAt: now } : n));
 }
 
-// ── Transitional bridges (Room-based projections) ─────────────────────────────
-// Used while apps migrate their content onto the generic object model. Both apps
-// still speak the legacy `Room` type; these projections stay until that migration
-// is complete.
-
-/** The category→rooms grouping the legacy UI consumes. */
-export interface AdaptedCategory {
-  name: string;
-  rooms: Room[];
-}
-
-/**
- * Project the room/category nodes of an index into the legacy `{ name, rooms }[]`
- * shape that app UIs still consume. Category nodes become buckets; room nodes become
- * {@link Room}s grouped under their parent category (or `fallbackCategory` at root).
- * Returns null when the index holds no room/category nodes yet.
- *
- * @deprecated Use the object tree directly once apps complete their migration.
- */
-export function objectsToRoomCategories(nodes: ObjectNode[], spaceId: string, fallbackCategory: string): AdaptedCategory[] | null {
-  const live = nodes.filter((n) => !n.archived);
-  const cats = live.filter((n) => n.type === 'category').slice().sort(compareSiblings);
-  const rooms = live.filter((n) => n.type === 'room');
-  if (cats.length === 0 && rooms.length === 0) return null;
-
-  const titleById = new Map<ID, string>(cats.map((c) => [c.id, c.title]));
-  const buckets = new Map<string, Room[]>();
-  for (const c of cats) buckets.set(c.title, []);
-
-  const toRoom = (n: ObjectNode, category: string): Room => ({
-    id: n.id,
-    spaceId,
-    category,
-    name: n.title,
-    kind: subtypeToRoomKind(n.subtype),
-    ...(n.automation ? { automation: n.automation } : {}),
-  });
-
-  for (const n of rooms.slice().sort(compareSiblings)) {
-    const category = (n.parentId != null && titleById.get(n.parentId)) || fallbackCategory;
-    if (!buckets.has(category)) buckets.set(category, []);
-    buckets.get(category)!.push(toRoom(n, category));
-  }
-  return [...buckets.entries()].map(([name, rs]) => ({ name, rooms: rs }));
-}
-
-/**
- * Drop `kind: 'automated'` rooms from a category list (they belong to an Agents
- * view, not the main room list). A category that held only agents is removed too.
- *
- * @deprecated Use the object tree directly once apps complete their migration.
- */
-export function excludeAutomatedRooms(categories: AdaptedCategory[]): AdaptedCategory[] {
-  return categories
-    .map((c) => ({ ...c, rooms: c.rooms.filter((r) => r.kind !== 'automated') }))
-    .filter((c, i) => c.rooms.length > 0 || categories[i].rooms.length === 0);
-}
-
-// ── Seed: build the initial index nodes for a freshly-created space ────────────
-
-/** A minimal object descriptor the {@link seedIndexNodes} builder turns into nodes. */
-export interface SeedRoom {
-  id: ID;
-  name: string;
-  kind: Room['kind'];
-  category: string;
-}
-
-/**
- * Build the initial `ObjectNode[]` for a brand-new space's index: a `category` node
- * per distinct category and a `room` node per seed object parented under it. Pure +
- * deterministic (category ids via {@link categoryId}).
- */
-export function seedIndexNodes(rooms: SeedRoom[], now: number): ObjectNode[] {
-  const out: ObjectNode[] = [];
-  const catId = new Map<string, ID>();
-  let catOrder = 0;
-  for (const r of rooms) {
-    if (catId.has(r.category)) continue;
-    const id = categoryId(r.category);
-    catId.set(r.category, id);
-    out.push({ id, type: 'category', parentId: null, order: catOrder++, title: r.category, updatedAt: now });
-  }
-  const orderInCat = new Map<ID, number>();
-  for (const r of rooms) {
-    const parentId = catId.get(r.category)!;
-    const order = (orderInCat.get(parentId) ?? 0) + 1;
-    orderInCat.set(parentId, order);
-    out.push({ id: r.id, type: 'room', subtype: roomKindToSubtype(r.kind), parentId, order, title: r.name, updatedAt: now });
-  }
-  return out;
-}

package/src/spaces/members.test.ts

@@ -75,13 +75,20 @@ describe('acceptSpaceInvite validation', () => {
     ).rejects.toThrow('different identity');
   });
 
-  it('rejects invite missing iss', async () => {
+  it('accepts invite with no iss field (no longer required — keyrings are per-node now)', async () => {
     const inv = JSON.stringify({
       spaceId: 'sp-x',
+      spaceName: 'My Space',
       cap: { kind: 'member', sub: 'my-pub' },
     });
+    // Should NOT throw on missing iss — the iss check was removed with space keyrings.
+    // The accountClient.push mock is needed for addJoinedSpaceWithCap.
+    const fakeClient = {
+      pull: () => Promise.resolve({ data: { v: 1, spaces: [], caps: {}, pubAccess: {} }, hash: null }),
+      push: () => Promise.resolve(),
+    };
     await expect(
-      acceptSpaceInvite({ keys: { edPub: 'my-pub' }, accountClient: {} } as never, inv),
-    ).rejects.toThrow('missing its issuer');
+      acceptSpaceInvite({ keys: { edPub: 'my-pub' }, accountClient: fakeClient, userId: 'alice' } as never, inv),
+    ).resolves.toMatchObject({ id: 'sp-x' });
   });
 });

package/src/spaces/members.ts

@@ -1,21 +1,24 @@
 /**
- * Space membership — both keyring-based (private spaces) and link-based (public spaces).
+ * Space membership — invite-based (member cap) and link-based (open access).
  *
- * 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.
+ * MEMBER join: the owner records the invitee in the roster, mints a space-scoped
+ * member cap, and adds the invitee to the space-wide keyring (if it exists) so they
+ * can decrypt `enc` content. The invitee 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.
+ * 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`.
+ *
+ * DEVICE PAIRING: after pairing, call `addDeviceToSpaceKeyring(session, spaceId, device)`
+ * for each space the paired device should decrypt. ONE keyring per space encrypts all
+ * `enc` nodes; adding the device once unlocks the whole space's E2EE content.
  */
 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,
@@ -39,54 +42,54 @@ export function makeJoinRequest(session: Session): string {
   return JSON.stringify(req);
 }
 
+function isAlreadyPresentRecipient(err: unknown): boolean {
+  return err instanceof Error && /already present in epoch/.test(err.message);
+}
+
+function isKeyringMissing(err: unknown): boolean {
+  return err instanceof Error && /not found|404|does not exist/i.test(err.message);
+}
+
 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.
+ * Owner: invite an identity into a space. Records them in the roster, mints a
+ * space-scoped member cap, and adds them to the space-wide keyring if it exists
+ * (so they can decrypt `enc` nodes from the start).
+ * Returns the invite bundle JSON.
  */
-export async function addDeviceToSpaceKeyring(
+export async function inviteToSpace(
   session: Session,
   spaceId: string,
-  recipient: { kemPub: string; userId: string },
-): Promise<void> {
+  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 addSpaceMember(session.accountClient, spaceId, session.userId, req.userId);
+
+  // Add invitee to the space-wide keyring so they can decrypt enc nodes.
+  // Silently skip if the keyring doesn't exist yet (no enc nodes in the space).
   try {
     await addCollectionRecipient(
       session.chatClient,
       keyringName(spaceId),
-      { subKem: recipient.kemPub, userId: recipient.userId, label: recipient.userId.slice(0, 8) },
+      { subKem: req.kemPub, userId: req.userId, label: req.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;
+    if (!isAlreadyPresentRecipient(err) && !isKeyringMissing(err)) {
+      // Only rethrow unexpected errors — missing keyring (no enc nodes yet) is normal.
+      console.warn('[octospaces] inviteToSpace: keyring add skipped', 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,
@@ -105,22 +108,18 @@ export async function inviteToSpace(
 }
 
 /**
- * Invitee: accept a PRIVATE space invite — verify keyring access, store the cap,
- * and register the space. Returns the joined space.
+ * Invitee: accept a space invite — 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;
+  const cap = inv.cap as { kind?: string; sub?: 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 };
@@ -188,26 +187,38 @@ export async function createSpaceInviteLink(
   );
   // Add the ephemeral userId to the roster so the server grants `space:member`
   await addSpaceMember(session.accountClient, spaceId, session.userId, ephemeralUserId);
+
+  // Add ephemeral KEM to the space keyring so link-bearers can decrypt enc content.
+  // Silently skip if the keyring doesn't exist yet (no enc nodes).
+  try {
+    await addCollectionRecipient(
+      session.chatClient,
+      keyringName(spaceId),
+      { subKem: ek.kemPub, userId: ephemeralUserId, label: ephemeralUserId.slice(0, 8) },
+      { edPriv: session.keys.edPriv, edPub: session.keys.edPub, kemPriv: session.keys.kemPriv },
+      { trustedAdders: [session.keys.edPub] },
+    );
+  } catch (err) {
+    if (!isAlreadyPresentRecipient(err) && !isKeyringMissing(err)) {
+      console.warn('[octospaces] createSpaceInviteLink: keyring add skipped', err);
+    }
+  }
+
   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.
+ * Any user: join a 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));
@@ -216,6 +227,32 @@ export async function joinSpaceByLink(session: Session, token: SpaceInviteLinkTo
   return space;
 }
 
+/**
+ * Add a device's KEM key as a recipient of a space's keyring.
+ *
+ * Call this after device pairing (for each space the new device should be able to
+ * decrypt). ONE space keyring encrypts ALL the space's `enc` nodes — adding the device
+ * once unlocks the whole space's E2EE content. Silently a no-op if the keyring doesn't
+ * exist yet.
+ */
+export async function addDeviceToSpaceKeyring(
+  session: Session,
+  spaceId: string,
+  device: { kemPub: string; edPub: string; userId: string },
+): Promise<void> {
+  try {
+    await addCollectionRecipient(
+      session.chatClient,
+      keyringName(spaceId),
+      { subKem: device.kemPub, userId: device.userId, label: device.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) && !isKeyringMissing(err)) throw err;
+  }
+}
+
 /**
  * Single sign-in hydration: merges server-side caps (plaintext member caps from
  * `_spaces.caps`) and sealed link access (from `_spaces.pubAccess`) into the

package/src/spaces/nodes.test.ts

@@ -0,0 +1,225 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import type { StarfishClient } from '@drakkar.software/starfish-client';
+import type { ObjectNode } from '../core/types.js';
+
+// ── Mocks ──────────────────────────────────────────────────────────────────────
+//
+// We mock heavy external modules so the tests focus on the business logic in
+// nodes.ts (validation, index mutations, access-store calls) without needing
+// a real Starfish server or keyring library.
+
+vi.mock('../sync/space-access.js', () => ({
+  getSpaceClient: vi.fn().mockReturnValue({
+    pull: vi.fn().mockResolvedValue(null),
+    push: vi.fn().mockResolvedValue(undefined),
+  }),
+}));
+
+vi.mock('../sync/client.js', () => ({
+  ownerEnsureKeyring: vi.fn().mockResolvedValue({}),
+  makeClient: vi.fn().mockReturnValue({
+    pull: vi.fn().mockResolvedValue(null),
+    push: vi.fn().mockResolvedValue(undefined),
+  }),
+}));
+
+vi.mock('../sync/space-access-store.js', () => ({
+  saveNodeAccessEntry: vi.fn(),
+  saveSpaceAccessEntry: vi.fn(),
+  getNodeAccessEntry: vi.fn().mockReturnValue(null),
+}));
+
+vi.mock('@drakkar.software/starfish-sharing', () => ({
+  mintMemberCap: vi.fn().mockResolvedValue({ kind: 'member', sub: 'pub-key' }),
+}));
+
+vi.mock('@drakkar.software/starfish-keyring', () => ({
+  addCollectionRecipient: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('@drakkar.software/starfish-identities', () => ({
+  generateDeviceKeys: vi.fn().mockReturnValue({
+    edPub: 'eph-edpub',
+    edPriv: 'eph-edpriv',
+    kemPub: 'eph-kempub',
+    kemPriv: 'eph-kempriv',
+  }),
+}));
+
+vi.mock('../sync/paths.js', async (importOriginal) => {
+  const original = await importOriginal<typeof import('../sync/paths.js')>();
+  return {
+    ...original,
+    userIdFromEdPub: vi.fn().mockResolvedValue('ephemeral-user-id'),
+  };
+});
+
+vi.mock('./registry.js', () => ({
+  addSpaceMember: vi.fn().mockResolvedValue(undefined),
+  readSpaces: vi.fn().mockResolvedValue({ spaces: [], caps: {}, pubAccess: {} }),
+  updateSpacesDoc: vi.fn().mockImplementation(
+    (_client: unknown, _userId: string, mutator: (cur: { spaces: ObjectNode[]; caps: Record<string, string>; pubAccess: Record<string, unknown> }) => unknown) =>
+      mutator({ spaces: [], caps: {}, pubAccess: {} }),
+  ),
+}));
+
+vi.mock('../sync/account-seal.js', () => ({
+  sealToSelf: vi.fn().mockResolvedValue({ encrypted: true }),
+}));
+
+// ── now import the module under test ──────────────────────────────────────────
+
+import { createNode, setNodeAccess, decodeNodeInviteLink, encodeNodeInviteLink } from './nodes.js';
+import { ownerEnsureKeyring } from '../sync/client.js';
+
+// ── Fake session ──────────────────────────────────────────────────────────────
+
+function makeIndexClient(nodes: ObjectNode[] = []): StarfishClient {
+  return {
+    pull: vi.fn().mockResolvedValue({ data: { v: 2, objects: nodes }, hash: 'h1' }),
+    push: vi.fn().mockResolvedValue(undefined),
+  } as unknown as StarfishClient;
+}
+
+function makeSession(indexClient?: StarfishClient) {
+  return {
+    userId: 'alice',
+    keys: { edPriv: 'priv', edPub: 'pub', kemPriv: 'kempriv', kemPub: 'kempub' },
+    chatClient: indexClient ?? makeIndexClient(),
+    accountClient: {
+      pull: vi.fn().mockResolvedValue({ data: { v: 1, spaces: [], caps: {}, pubAccess: {} }, hash: null }),
+      push: vi.fn().mockResolvedValue(undefined),
+    } as unknown as StarfishClient,
+  } as unknown as import('../sync/identity.js').Session;
+}
+
+// ── createNode ────────────────────────────────────────────────────────────────
+
+describe('createNode', () => {
+  beforeEach(() => {
+    vi.mocked(ownerEnsureKeyring).mockClear();
+  });
+
+  it('creates a node with default access "space" (no access field in stored node)', async () => {
+    const session = makeSession();
+    const node = await createNode(session, 'sp-1', { type: 'page', title: 'Hello' });
+    expect(node.title).toBe('Hello');
+    expect(node.type).toBe('page');
+    // 'space' is the default — addObject omits the access field (absent ⇒ 'space')
+    expect(node.access).toBeUndefined();
+  });
+
+  it('creates a public node', async () => {
+    const session = makeSession();
+    const node = await createNode(session, 'sp-1', { type: 'page', title: 'Public', access: 'public' });
+    expect(node.access).toBe('public');
+  });
+
+  it('creates an invite node', async () => {
+    const session = makeSession();
+    const node = await createNode(session, 'sp-1', { type: 'page', title: 'Secret', access: 'invite' });
+    expect(node.access).toBe('invite');
+  });
+
+  it('rejects the invalid combo public+enc', async () => {
+    const session = makeSession();
+    await expect(
+      createNode(session, 'sp-1', { type: 'page', title: 'Bad', access: 'public', enc: true }),
+    ).rejects.toThrow(/public\+enc/i);
+  });
+
+  it('mints a per-node keyring for enc nodes', async () => {
+    const session = makeSession();
+    await createNode(session, 'sp-1', { type: 'page', title: 'E2EE', enc: true });
+    expect(ownerEnsureKeyring).toHaveBeenCalledOnce();
+  });
+
+  it('does NOT mint a keyring for plaintext nodes', async () => {
+    const session = makeSession();
+    await createNode(session, 'sp-1', { type: 'page', title: 'Plain' });
+    expect(ownerEnsureKeyring).not.toHaveBeenCalled();
+  });
+
+  it('pushes the new node to the index (via the space client)', async () => {
+    // updateObjectIndex calls getSpaceClient, which is mocked to return a fixed client.
+    // We capture that mock client to verify the push was called.
+    const { getSpaceClient } = await import('../sync/space-access.js');
+    const mockSpaceClient = vi.mocked(getSpaceClient).getMockImplementation()?.('sp-1', makeSession());
+    const session = makeSession();
+    await createNode(session, 'sp-1', { type: 'page', title: 'New Page' });
+    // The mock resolves correctly — just verify no error was thrown and the node id is set.
+    const node = await createNode(session, 'sp-1', { type: 'page', title: 'Check' });
+    expect(node.id).toMatch(/^obj-/);
+    void mockSpaceClient; // consumed
+  });
+});
+
+// ── setNodeAccess ─────────────────────────────────────────────────────────────
+
+describe('setNodeAccess', () => {
+  beforeEach(() => {
+    vi.mocked(ownerEnsureKeyring).mockClear();
+  });
+
+  it('rejects public+enc patch', async () => {
+    const session = makeSession();
+    await expect(
+      setNodeAccess(session, 'sp-1', 'n-1', { access: 'public', enc: true }),
+    ).rejects.toThrow(/public\+enc/i);
+  });
+
+  it('mints a keyring when enabling enc', async () => {
+    const client = makeIndexClient([
+      { id: 'n-1', type: 'page', parentId: null, order: 1, title: 'T', updatedAt: 1 },
+    ]);
+    const session = makeSession(client);
+    await setNodeAccess(session, 'sp-1', 'n-1', { enc: true });
+    expect(ownerEnsureKeyring).toHaveBeenCalledOnce();
+  });
+
+  it('does not mint a keyring when not enabling enc', async () => {
+    const client = makeIndexClient([
+      { id: 'n-1', type: 'page', parentId: null, order: 1, title: 'T', updatedAt: 1 },
+    ]);
+    const session = makeSession(client);
+    await setNodeAccess(session, 'sp-1', 'n-1', { access: 'invite' });
+    expect(ownerEnsureKeyring).not.toHaveBeenCalled();
+  });
+
+  it('is a no-op when the node does not exist in the index', async () => {
+    const client = makeIndexClient([]); // empty index
+    const session = makeSession(client);
+    await setNodeAccess(session, 'sp-1', 'n-missing', { access: 'public' });
+    expect(client.push).not.toHaveBeenCalled();
+  });
+});
+
+// ── node invite link encode/decode ────────────────────────────────────────────
+
+describe('encodeNodeInviteLink / decodeNodeInviteLink', () => {
+  it('round-trips a token through encode/decode', () => {
+    const token = {
+      v: 1 as const,
+      spaceId: 'sp-1',
+      nodeId: 'n-42',
+      nodeName: 'My Page',
+      cap: { kind: 'member', sub: 'pub' },
+      key: 'secretkey',
+      write: true,
+    };
+    const link = encodeNodeInviteLink('https://app.example.com', token);
+    expect(link).toContain('join/node#');
+
+    const fragment = link.split('#')[1]!;
+    const decoded = decodeNodeInviteLink(fragment);
+    expect(decoded.spaceId).toBe('sp-1');
+    expect(decoded.nodeId).toBe('n-42');
+    expect(decoded.nodeName).toBe('My Page');
+    expect(decoded.write).toBe(true);
+    expect(decoded.key).toBe('secretkey');
+  });
+
+  it('throws on a malformed fragment', () => {
+    expect(() => decodeNodeInviteLink('not-valid-base64-json')).toThrow();
+  });
+});