@volter/world-platform 2.0.3 → 2.0.4

package/src/db/migrations/meta/_journal.json

@@ -8,6 +8,13 @@
       "when": 1790550512216,
       "tag": "0000_init",
       "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "6",
+      "when": 1790587292062,
+      "tag": "0001_world_access",
+      "breakpoints": true
     }
   ]
 }

package/src/db/migrations.ts

@@ -29,5 +29,11 @@ export const MIGRATIONS: ReadonlyArray<{ tag: string; statements: readonly strin
       "CREATE TABLE `webhooks` (\n\t`id` text PRIMARY KEY NOT NULL,\n\t`org_id` text NOT NULL,\n\t`url` text NOT NULL,\n\t`secret` text NOT NULL,\n\t`events` text NOT NULL,\n\t`description` text NOT NULL,\n\t`created_at` text NOT NULL,\n\t`consecutive_failures` integer NOT NULL,\n\t`last_failed_at` text,\n\t`disabled_at` text\n);",
       "CREATE INDEX `webhooks_org` ON `webhooks` (`org_id`);"
     ]
+  },
+  {
+    "tag": "0001_world_access",
+    "statements": [
+      "CREATE TABLE `world_access` (\n\t`org_id` text NOT NULL,\n\t`name` text NOT NULL,\n\t`members` text NOT NULL,\n\t`set_by` text NOT NULL,\n\t`set_at` text NOT NULL,\n\tPRIMARY KEY(`org_id`, `name`)\n);"
+    ]
   }
 ];

package/src/db/pack-migrations.ts

@@ -9,7 +9,7 @@ const dir = join(import.meta.dir, 'migrations');
 const target = join(import.meta.dir, 'migrations.ts');
 export function packed(): string {
   const files = readdirSync(dir).filter((f) => /^\d{4}_.+\.sql$/.test(f)).sort();
-  const list = files.map((f) => ({ tag: f.replace(/\.sql$/, ''), statements: readFileSync(join(dir, f), 'utf8').split('--> statement-breakpoint').map((s) => s.trim()).filter(Boolean) }));
+  const list = files.map((f) => ({ tag: f.replace(/\.sql$/, ''), statements: readFileSync(join(dir, f), 'utf8').replace(/\r\n/g, '\n').split('--> statement-breakpoint').map((s) => s.trim()).filter(Boolean) }));
   return `// GENERATED by \`bun src/db/pack-migrations.ts --write\` from ./migrations/*.sql (drizzle-kit's): do not edit.\nexport const MIGRATIONS: ReadonlyArray<{ tag: string; statements: readonly string[] }> = ${JSON.stringify(list, null, 2)};\n`;
 }
 if (import.meta.main) {

package/src/db/schema.ts

@@ -12,6 +12,16 @@ export const orgWorlds = sqliteTable('org_worlds', {
   provisionedAt: text('provisioned_at').notNull(),
 }, (t) => [primaryKey({ columns: [t.orgId, t.name] })]);
 
+/** A World kept to some of its org (architecture, "A World may be kept to some of its org"): a row means only the
+ *  listed members (by the directory's user id) reach it, admins always; no row, the whole org. */
+export const worldAccess = sqliteTable('world_access', {
+  orgId: text('org_id').notNull(),
+  name: text('name').notNull(),
+  members: text('members', { mode: 'json' }).$type<string[]>().notNull(),
+  setBy: text('set_by').notNull(),
+  setAt: text('set_at').notNull(),
+}, (t) => [primaryKey({ columns: [t.orgId, t.name] })]);
+
 /** An org's settings: its security switches, labs and support consent (absent: the defaults). */
 export const orgSettings = sqliteTable('org_settings', {
   orgId: text('org_id').primaryKey(),

package/src/directory.ts

@@ -106,7 +106,8 @@ export function volterDirectory(identity: Identity): Directory {
       return invitationView(inv);
     },
     pendingInvitations: async (orgId) => ((await call<InvitationRow[]>('GET', `/api/organizations/${seg(orgId)}/invitations`)) ?? []).map(invitationView),
-    async revokeInvitation(orgId, invitationId) { await call('DELETE', `/api/organizations/${seg(orgId)}/invitations/${seg(invitationId)}`); },
+    // one already used, revoked or expired is refused: a join that races a revocation lets no one in
+    async revokeInvitation(orgId, invitationId) { if ((await call('DELETE', `/api/organizations/${seg(orgId)}/invitations/${seg(invitationId)}`)) === null) throw new Error('no such pending invitation'); },
     userIdByEmail,
     async personById(userId) {
       try {

package/src/doors.ts

@@ -31,14 +31,17 @@ export const DOORS: readonly Door[] = [
   { method: 'GET', path: '/-/worlds/{org}/{world}/previews', who: 'person', scope: 'worlds:read', summary: 'The world\'s previews: named branches made for CI (a pull request each), with where each lives and a link that opens it.', answers: '{ world, previews: [{ label, branch, expiresAt, open, live, base?, origin? }] }' },
   { method: 'PUT', path: '/-/worlds/{org}/{world}/previews/{label}', who: 'person', scope: 'worlds:write', summary: 'Make a preview: a branch of the world named `label` (pr-12), made with a key the platform mints in the world for the caller (for the person; recorded against the token that asked, so logout, revoking the token or leaving the org ends the preview); ends after ttlDays (7 by default, at most 7). Answers a key to the branch for a token (never the branch\'s own token; none for a browser session). Asked again, the same preview and a fresh key, unless replace asks for a fresh one; at most 20 previews of a world at once (409).', body: '{ ttlDays?: 1-7, replace?: true }', answers: '201 { label, branch, base, origin?, open, token?, expiresAt, created: true }, or 200 with created: false' },
   { method: 'DELETE', path: '/-/worlds/{org}/{world}/previews/{label}', who: 'person', scope: 'worlds:write', summary: 'Remove a preview and its branch (a pull request closed).', answers: '{ removed, branch }' },
-  { method: 'GET', path: '/-/worlds/{org}/{world}/previews/{label}/open', who: 'person', scope: 'worlds:read', summary: 'Open a preview as yourself: a pass for its branch, as the world\'s own open door gives one; 410 once it has ended.', answers: '303 to the preview\'s page, or { url, scope, expiresIn }' },
+  { method: 'GET', path: '/-/worlds/{org}/{world}/previews/{label}/open', who: 'person', scope: 'worlds:read', summary: 'Open a preview as yourself: a pass for its branch, as opening the world gives one; 410 once it has ended.', answers: '303 to the preview\'s page, or { url, scope, expiresIn }' },
   { method: 'POST', path: '/-/cli/device', who: 'anyone', scope: null, summary: 'Begin signing the volter command in through the browser (the device authorization grant): a code for the person to approve, and where.', body: '{ name? }', answers: '{ device_code, user_code, verification_uri, verification_uri_complete, expires_in, interval }' },
   { method: 'GET', path: '/-/cli/approve', who: 'person', scope: null, summary: 'The page where a signed-in person approves or refuses a code the volter command shows (signing in first when needed).', answers: 'a page' },
   { method: 'POST', path: '/-/cli/approve', who: 'person', scope: null, summary: 'Approve or refuse a code, from the approval page itself in a signed-in browser (never with a token, never a support session).', body: 'form: code, decision (approve or deny)', answers: 'a page' },
   { method: 'POST', path: '/-/cli/token', who: 'anyone', scope: null, summary: 'The volter command collects its personal token once the person approved its code (30 days, named for the machine, scoped orgs:read, worlds:read and worlds:write); authorization_pending until then.', body: '{ device_code }', answers: '{ token, name, expiresAt, person }' },
   { method: 'POST', path: '/-/worlds/{org}/{world}/keys', who: 'person', scope: 'worlds:write', summary: 'Make a key in a World of your org, for an app or a job, shown once: for you, ending in 90 days unless you say otherwise, and revoked when you leave the org; made with a personal token, it ends no later than the token and is revoked with it. A browser session on the World itself makes no keys.', body: '{ name, scope?: read | write, expiresInDays?: 1-365 | null }', answers: '{ world, base, id, name, scope, expiresAt, key }' },
+  { method: 'GET', path: '/-/worlds/{org}/{world}/access', who: 'admin', scope: 'members:read', summary: 'Who reaches the world: the whole org, or only the listed members (admins always). A world kept from the caller answers 404.', answers: '{ world, restricted, members: [userId] }' },
+  { method: 'PUT', path: '/-/worlds/{org}/{world}/access', who: 'admin', scope: 'members:write', summary: 'Keep the world to named members, or open it to the whole org again. Keeping it revokes, at once, the world keys held there by the members it leaves out (and the previews those keys made). Webhook: world.access_changed.', body: '{ restricted: boolean, members?: [userId] }', answers: '{ world, restricted, members, revokedFor }' },
   { method: 'GET', path: '/-/worlds/{org}/{world}/token', who: 'person', scope: 'worlds:read', summary: 'A named key for the volter command (`volter remote add`), made in the world and shown once: for a token only, never a browser or a support session; write for a token with worlds:write, else read. Listed and revoked alone in the world\'s Settings.', answers: '{ name, base, scope, token, keyId }' },
-  { method: 'GET', path: '/-/orgs', who: 'person', scope: 'orgs:read', summary: 'Who you are and the orgs you belong to, each with its worlds, security switches and whether it is held.', answers: '{ person, orgs[] }' },
+  { method: 'GET', path: '/-/orgs', who: 'person', scope: 'orgs:read', summary: 'Who you are and the orgs you belong to, each with its worlds, security switches and whether it is held, and the invitations to your address still pending, where the provider keeps them.', answers: '{ person, orgs[], invitations[] }' },
+  { method: 'POST', path: '/-/invitations/{id}/join', who: 'person', scope: 'orgs:write', summary: 'Join the org a pending invitation to your address names, in its role, when your identity owns that address.', answers: '{ joined, role }' },
   { method: 'POST', path: '/-/orgs', who: 'person', scope: 'orgs:write', summary: 'Create an org, you its admin; where the platform has a site, its terms accepted. A name the pages use (account, help, new, …) is refused.', body: '{ name, accepted? }', answers: '{ id, slug, name }' },
   { method: 'GET', path: '/-/orgs/{org}', who: 'person', scope: 'orgs:read', summary: 'The org and its worlds.', answers: '{ id, slug, name, role, worlds[] }' },
   { method: 'PATCH', path: '/-/orgs/{org}', who: 'admin', scope: 'orgs:write', summary: 'Rename the org (the display name only; the address stays).', body: '{ name }', answers: '{ id, name }' },
@@ -121,7 +124,7 @@ export function platformApiMarkdown(): string {
     ['Signing in', (d) => d.path === '/-/sign-in' || d.path === '/-/sign-out'],
     ['Signing the volter command in', (d) => d.path.startsWith('/-/cli/')],
     ['Worlds', (d) => d.path.startsWith('/-/worlds')],
-    ['Orgs, members, billing, security, activity', (d) => d.path.startsWith('/-/orgs')],
+    ['Orgs, members, billing, security, activity', (d) => d.path.startsWith('/-/orgs') || d.path.startsWith('/-/invitations/')],
     ['Your tokens and support', (d) => d.path.startsWith('/-/tokens') || d.path === '/-/support'],
     ['The operator\'s', (d) => d.who === 'operator' && !/^\/-\/status/.test(d.path)],
   ];

package/src/platform.ts

@@ -17,7 +17,7 @@ import { EARLY_FEATURES } from './labs.ts';
 import type { Biller, BillerFactory } from './biller.ts';
 import { createPages, pageShell, RESERVED_ORG_NAMES } from './pages.ts';
 import { beginSignIn, CALLBACK_PATH, endSession, finishSignIn, providerClient, Sessions, sessionIdOf, whoIs, type IdentityOptions, type ProviderOptions } from './identity.ts';
-import { isAdmin, localDirectory, OnlyAdmin, volterDirectory, type Directory, type OrgRef } from './directory.ts';
+import { isAdmin, localDirectory, OnlyAdmin, volterDirectory, type Directory, type OrgRef, type PendingInvitation } from './directory.ts';
 import { eq } from 'drizzle-orm';
 import { billerRecords } from './db/schema.ts';
 import { assertName, Store, type OrgWorld, type Preview, type Security, type SupportRequest } from './store.ts';
@@ -188,24 +188,43 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
   /** A person removed from an org where the platform did not see it (at the identity service directly) keeps nothing:
    *  every person a key in the org's Worlds is for (or was made by) who is no longer a member has their keys, and the
    *  branches those made, revoked there. Org tokens' keys are ended with the org token. */
+  /** A person's keys in a World and in each live preview branch of it: a preview key minted for them lives in the branch's own
+   *  key store, under a parent key the preview's maker holds, so the parent's revocation does not reach it. */
+  const revokeHeldIn = async (orgId: string, world: string, person: string): Promise<boolean> => {
+    let any = false;
+    for (const served of [world, ...opts.store.previewsOf(orgId).filter((p) => p.world === world).map((p) => p.branch)]) {
+      const row = await worldRow(served); if (!row) continue;
+      const r = await fetch(`${new URL(row.base).origin}/-/${row.name}/keys?person=${encodeURIComponent(person)}`, { method: 'DELETE', headers: { 'x-volter-token': row.token } }).catch(() => null);
+      any ||= Boolean(r?.ok);
+    }
+    return any;
+  };
   const sweepRemovedMembers = async (): Promise<number> => {
     let revoked = 0;
     for (const orgId of opts.store.orgIds()) {
-      const gone = new Map<string, boolean>();
+      const membership = new Map<string, OrgRef | null | 'unknown'>();
       for (const w of opts.store.doc(orgId).worlds) {
-        const row = await worldRow(w.name); if (!row) continue;
-        const res = await fetch(`${new URL(row.base).origin}/-/${row.name}/keys`, { headers: { 'x-volter-token': row.token } }).catch(() => null);
-        const keys = res?.ok ? ((await res.json()) as { keys: Array<{ person?: string | null }> }).keys : [];
+        // the people holding keys in the World or in a live preview branch of it
+        const keys: Array<{ person?: string | null }> = [];
+        for (const served of [w.name, ...opts.store.previewsOf(orgId).filter((p) => p.world === w.name).map((p) => p.branch)]) {
+          const row = await worldRow(served); if (!row) continue;
+          const res = await fetch(`${new URL(row.base).origin}/-/${row.name}/keys`, { headers: { 'x-volter-token': row.token } }).catch(() => null);
+          if (res?.ok) keys.push(...((await res.json()) as { keys: Array<{ person?: string | null }> }).keys);
+        }
+        const keptTo = opts.store.accessOf(orgId, w.name);
         for (const person of new Set(keys.map((k) => k.person).filter((p): p is string => typeof p === 'string' && !p.startsWith('org-token:')))) {
-          if (!gone.has(person)) gone.set(person, (await dir.memberOf(person, orgId).catch(() => 'unknown' as const)) === null);
-          if (gone.get(person)) { await fetch(`${new URL(row.base).origin}/-/${row.name}/keys?person=${encodeURIComponent(person)}`, { method: 'DELETE', headers: { 'x-volter-token': row.token } }).catch(() => null); revoked += 1; }
+          if (!membership.has(person)) membership.set(person, await dir.memberOf(person, orgId).catch(() => 'unknown' as const));
+          const ref = membership.get(person);
+          // gone from the org, or kept off this World (not an admin, not named on it): nothing held there stays
+          const off = ref === null || (ref !== 'unknown' && ref !== undefined && keptTo !== null && !isAdmin(ref) && !keptTo.includes(person));
+          if (off) { await revokeHeldIn(orgId, w.name, person); revoked += 1; }
         }
       }
     }
     return revoked;
   };
   const revokePersonKeys = async (orgId: string, subject: string): Promise<void> => {
-    for (const w of opts.store.doc(orgId).worlds) { const row = await worldRow(w.name); if (row) await fetch(`${new URL(row.base).origin}/-/${row.name}/keys?person=${encodeURIComponent(subject)}`, { method: 'DELETE', headers: { 'x-volter-token': row.token } }).catch(() => null); }
+    for (const w of opts.store.doc(orgId).worlds) await revokeHeldIn(orgId, w.name, subject);
   };
   // ── billing: an attached biller answers for plans and prices; without one nothing is limited ──
   const biller: Biller | null = opts.billing ? opts.billing({
@@ -254,6 +273,29 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
   type Person = { id: string; email?: string; name?: string; /** an org token acting as its org (layer 6): the org, and the token's name */ orgToken?: { orgId: string; name: string }; /** a support session (layer 6): read-only, consented, until when, and why */ support?: { orgId: string; until: string; reason: string; category: string } };
   // an org token is a member of exactly one org and of nothing else; a person's orgs are the identity service's
   const orgsOfP = async (person: Person): Promise<OrgRef[]> => { if (person.orgToken) { const o = await dir.orgById(person.orgToken.orgId); return o ? [o] : []; } return dir.orgsOf(person.id); };
+  // an invited person who signed in here instead of through the mail: the invitations the platform sent to their address
+  // that the directory still holds (a directory that lets invitations in at sign-in keeps none to show); the ones it no
+  // longer holds are forgotten, and an unreachable directory keeps them for the next look
+  type Invited = { id: string; org: { id: string; slug: string | null; name: string }; role: string; expiresAt: string | null };
+  const invitedP = async (person: Person): Promise<Invited[]> => {
+    if (!person.email || person.orgToken || person.support || !dir.mailsInvitations) return [];
+    const email = person.email.toLowerCase(); const noted = opts.store.invitedOf(email); if (!noted.length) return [];
+    const shown: Invited[] = []; const gone = new Set<string>();
+    for (const n of noted) {
+      let pending: PendingInvitation[]; try { pending = await dir.pendingInvitations(n.orgId); } catch { continue; }
+      const inv = pending.find((i) => i.id === n.id && i.email.toLowerCase() === email);
+      const org = inv && !(inv.expiresAt && Date.parse(inv.expiresAt) <= Date.now()) ? await dir.orgById(n.orgId) : null;
+      if (!inv || !org) { gone.add(n.id); continue; }
+      shown.push({ id: inv.id, org: { id: org.id, slug: org.slug, name: org.name }, role: inv.role, expiresAt: inv.expiresAt });
+    }
+    // read again at the write: an invitation noted while the directory answered stays
+    if (gone.size) opts.store.setInvited(email, opts.store.invitedOf(email).filter((n) => !gone.has(n.id)));
+    return shown;
+  };
+  const noteInvited = (orgId: string, inv: PendingInvitation, replaces?: string): void => {
+    if (!dir.mailsInvitations) return;
+    opts.store.setInvited(inv.email, [...opts.store.invitedOf(inv.email).filter((n) => !(n.orgId === orgId && (n.id === inv.id || n.id === replaces))), { orgId, id: inv.id }]);
+  };
   const memberOfP = async (person: Person, ref: string): Promise<OrgRef | null> => { if (person.orgToken) { const o = await dir.orgById(person.orgToken.orgId); return o && (o.id === ref || o.slug === ref) ? o : null; } return dir.memberOf(person.id, ref); };
   /** The CLI's pending sign-ins, by device code (the /-/cli doors). */
   type DeviceGrant = { userCode: string; name: string; expires: number; state: 'pending' | 'approved' | 'denied'; person?: Person };
@@ -273,10 +315,19 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
   };
   const redirect = (location: string): Response => new Response(null, { status: 302, headers: { location, 'cache-control': 'no-store' } });
 
-  /** The host inventory rows for the worlds an org holds (their tokens come from the host). */
+  /** Whether a person reaches a World of their org (architecture, "A World may be kept to some of its org"): an org's
+   *  admins always; everyone in it unless the World is kept to named members. An org token acts as the org and a
+   *  support session is the org's consented read, so neither is a member the World could be kept from. */
+  const mayReach = (person: Person, org: OrgRef, name: string): boolean => {
+    if (person.orgToken || person.support || isAdmin(org)) return true;
+    const members = opts.store.accessOf(org.id, name);
+    return members === null || members.includes(person.id);
+  };
+  /** The host inventory rows for the worlds a person reaches in their orgs (their tokens come from the host). */
   const rowsForPerson = async (person: Person): Promise<WorldRow[]> => {
     const wanted = new Map<string, string>(); // served name → host id
-    for (const org of await orgsOfP(person)) for (const w of opts.store.doc(org.id).worlds) wanted.set(w.name, w.host);
+    const kept = new Set<string>(); // the ones kept to named members
+    for (const org of await orgsOfP(person)) for (const w of opts.store.doc(org.id).worlds) if (mayReach(person, org, w.name)) { wanted.set(w.name, w.host); if (opts.store.accessOf(org.id, w.name) !== null) kept.add(w.name); }
     const rows: WorldRow[] = [];
     const byHost = new Map<string, WorldRow[]>();
     for (const host of opts.hosts) {
@@ -289,7 +340,7 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
       const row = byHost.get(hostId)?.find((r) => r.name === name);
       const host = hostOf(hostId);
       // the world's address is the HOST's enrolled origin + its name: what the platform reached it at
-      if (row && host) rows.push({ ...row, base: `${host.base}/${row.name}` });
+      if (row && host) rows.push({ ...row, base: `${host.base}/${row.name}`, ...(kept.has(name) ? { restricted: true } : {}) });
     }
     return rows.sort((a, b) => a.name.localeCompare(b.name));
   };
@@ -324,8 +375,10 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
   const scopeFor = (method: string, path: string): string | null => {
     const write = method !== 'GET' && method !== 'HEAD';
     if (path === '/-/tokens' || path.startsWith('/-/tokens/')) return write ? 'tokens:write' : 'tokens:read';
+    if (/^\/-\/worlds\/[^/]+\/[^/]+\/access$/.test(path)) return write ? 'members:write' : 'members:read'; // who reaches a World is the org's membership
     if (/^\/-\/worlds\/[^/]+\/[^/]+\/(token|open|previews\/[^/]+\/open)$/.test(path)) return 'worlds:read';
     if (path === '/-/worlds' || path.startsWith('/-/worlds/')) return write ? 'worlds:write' : 'worlds:read';
+    if (path.startsWith('/-/invitations/')) return 'orgs:write'; // joining an org is the person's own org change
     const org = /^\/-\/orgs(?:\/[^/]+(?:\/([^/]+))?)?/.exec(path); if (!org) return null;
     const part = org[1];
     if (part === 'members' || part === 'invitations') return write ? 'members:write' : 'members:read';
@@ -545,7 +598,8 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
           const org = orgRef ? await memberOfP(person, orgRef) : null;
           if (!org) return json({ error: 'not a member' }, 403);
           const name = `${org.slug ?? org.id}/${world}`; const held = opts.store.doc(org.id).worlds.find((w) => w.name === name);
-          if (!held) return json({ error: `no world ${name} in ${orgRef}` }, 404);
+          // a World kept from this member answers as one that is not there: its name is not theirs to learn
+          if (!held || !mayReach(person, org, name)) return json({ error: `no world ${name} in ${orgRef}` }, 404);
           const host = hostOf(held.host);
           if (!host) return json({ error: `the host ${held.host} that serves ${name} is not enrolled` }, 502);
           const gone = await fetch(`${host.base}/-/worlds/${name}`, { method: 'DELETE', headers: { 'x-volter-token': host.adminToken } });
@@ -590,7 +644,29 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
           if (!person) return unauthorized(request);
           const orgs = await orgsOfP(person);
           const session = { person, token: presentedToken(request) ?? '' };
-          return json({ person, orgs: orgs.map((o) => ({ ...o, worlds: opts.store.doc(o.id).worlds, security: opts.store.securityOf(o.id), held: heldBy(o.id, session), flags: flagsOf(o.id) })) });
+          return json({ person, orgs: orgs.map((o) => ({ ...o, worlds: opts.store.doc(o.id).worlds.filter((w) => mayReach(person, o, w.name)), security: opts.store.securityOf(o.id), held: heldBy(o.id, session), flags: flagsOf(o.id) })), invitations: await invitedP(person) });
+        }
+        // join an org one's address is invited to, here rather than at the identity service's page: the directory must
+        // name this person as the address's owner, as the platform's own directory lets an invitation in at sign-in
+        const joining = /^\/-\/invitations\/([^/]+)\/join$/.exec(path);
+        if (joining && request.method === 'POST') {
+          const person = (await sessionOf(request))?.person;
+          if (!person) return unauthorized(request);
+          const inv = (await invitedP(person)).find((i) => i.id === decodeURIComponent(joining[1]!));
+          if (!inv) return json({ error: 'no pending invitation to your address with that id' }, 404);
+          if ((await dir.userIdByEmail(person.email!)) !== person.id) return json({ error: `your Volter identity does not own ${person.email}: open the invitation's mail and accept it there` }, 403);
+          { const why = domainAllowed(inv.org.id, person.email!); if (why) return json({ error: why }, 403); } // the domains may have narrowed since
+          try {
+            // the invitation is used up first, so one an admin revokes meanwhile lets no one in; a member already is left as they are
+            await dir.revokeInvitation(inv.org.id, inv.id);
+            if (!(await dir.memberOf(person.id, inv.org.id))) {
+              await dir.addMember(inv.org.id, { sub: person.id });
+              if (inv.role === 'org:admin') await dir.setMemberRole(inv.org.id, person.id, 'org:admin');
+            }
+          } catch (e) { return json({ error: (e as Error).message }, 400); }
+          opts.store.setInvited(person.email!, opts.store.invitedOf(person.email!).filter((n) => n.id !== inv.id));
+          record({ event: 'MEMBER_JOIN', org: inv.org.id, actor: person, target: person.email!, data: { invitation: inv.id, role: inv.role } });
+          return json({ joined: inv.org.slug ?? inv.org.id, role: inv.role });
         }
         if (path === '/-/orgs' && request.method === 'POST') {
           const person = (await sessionOf(request))?.person;
@@ -718,7 +794,7 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
           if (part === 'invitations' && sub && request.method === 'DELETE') {
             if (!isAdmin(org)) return json({ error: 'only an admin of the org revokes invitations' }, 403);
             const inv = (await dir.pendingInvitations(org.id)).find((i) => i.id === sub); if (!inv) return json({ error: 'no such pending invitation' }, 404);
-            await dir.revokeInvitation(org.id, sub); record({ event: 'INVITE_REVOKE', org: org.id, actor: person, target: inv.email });
+            try { await dir.revokeInvitation(org.id, sub); } catch { return json({ error: 'no such pending invitation' }, 404); } record({ event: 'INVITE_REVOKE', org: org.id, actor: person, target: inv.email });
             return json({ revoked: inv.email });
           }
           // resend a pending invitation: a fresh one to the same address and role (the directory's id may change), mailed again
@@ -727,8 +803,9 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
             const inv = (await dir.pendingInvitations(org.id)).find((i) => i.id === sub); if (!inv) return json({ error: 'no such pending invitation' }, 404);
             if (inv.role.endsWith('admin') && !isAdmin(org)) return json({ error: 'only an admin resends an invitation to be an admin' }, 403);
             { const why = domainAllowed(org.id, inv.email); if (why) return json({ error: why }, 403); } // the domains may have narrowed since
-            await dir.revokeInvitation(org.id, sub);
+            try { await dir.revokeInvitation(org.id, sub); } catch { return json({ error: 'no such pending invitation' }, 404); }
             const again = await dir.inviteMember(org.id, inv.email, person.id, inv.role);
+            noteInvited(org.id, again, sub);
             if (!dir.mailsInvitations) await mail([again.email], `A reminder: you are invited to ${orgLabel(org.id, org.slug)} on Volter World`, `You are invited to the org ${orgLabel(org.id, org.slug)}. Sign in at ${opts.origin}/ with ${identity.name}, as ${again.email}, before ${(again.expiresAt ?? '').slice(0, 10)} to join it.`);
             record({ event: 'MEMBER_INVITE', org: org.id, actor: person, target: again.email, data: { pending: true, invitation: again.id, resent: true } });
             return json({ invited: again.email, pending: true, id: again.id, role: again.role, expiresAt: again.expiresAt }, 201);
@@ -779,7 +856,7 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
             }
             await dir.deleteOrg(org.id); record({ event: 'ORG_DELETE', org: org.id, actor: person, target: org.slug ?? org.name }); return json({ deleted: org.id });
           }
-          if (!part && request.method === 'GET') return json({ ...org, worlds: opts.store.doc(org.id).worlds });
+          if (!part && request.method === 'GET') return json({ ...org, worlds: opts.store.doc(org.id).worlds.filter((w) => mayReach(person, org, w.name)) }); // a kept World is listed only to its members
           return json({ error: `no such door: ${request.method} ${path}` }, 404);
         }
         // ── support and access (layer 6): the Help form, the consent, the operator's consented view ──
@@ -904,6 +981,38 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
         // branch of one of the org's Worlds, made and removed here with the World's own token, so CI's org token makes one
         // per pull request without a key of its own (a key would be replaced by the next job's, taking its branches); a
         // member opens one as themselves. A preview is an ordinary branch: its lifetime, keys and owner are a branch's.
+        // WHO REACHES A WORLD (architecture, "A World may be kept to some of its org"): an admin keeps a World to named members,
+        // or opens it to the whole org again; keeping it revokes, at once, the World keys held there by the members it leaves out
+        const accessDoor = /^\/-\/worlds\/([^/]+)\/([^/]+)\/access$/.exec(path);
+        if (accessDoor && (request.method === 'GET' || request.method === 'PUT')) {
+          const session = await sessionOf(request);
+          if (!session) return unauthorized(request);
+          const org = await memberOfP(session.person, accessDoor[1]!);
+          if (!org) return json({ error: `you are not a member of org ${accessDoor[1]}` }, 403);
+          const name = `${org.slug ?? org.id}/${accessDoor[2]}`;
+          if (!opts.store.doc(org.id).worlds.some((w) => w.name === name) || !mayReach(session.person, org, name)) return json({ error: `no world ${name} in your orgs` }, 404);
+          if (!isAdmin(org)) return json({ error: 'only an admin decides who reaches a World' }, 403);
+          if (request.method === 'GET') { const members = opts.store.accessOf(org.id, name); return json({ world: name, restricted: members !== null, members: members ?? [] }); }
+          if (session.person.support) return json({ error: 'a support session changes nothing' }, 403);
+          let body: { restricted?: unknown; members?: unknown }; try { body = (await request.json()) as typeof body; } catch { return json({ error: 'access: { restricted: boolean, members?: [userId] }' }, 400); }
+          if (typeof body.restricted !== 'boolean') return json({ error: 'access: { restricted: boolean, members?: [userId] }' }, 400);
+          const people = await dir.membersOf(org.id);
+          const asked = body.restricted ? (Array.isArray(body.members) ? body.members : []) : [];
+          const unknown = asked.filter((m) => typeof m !== 'string' || !people.some((p) => p.userId === m));
+          if (unknown.length) return json({ error: `not members of ${org.slug ?? org.id}: ${unknown.map(String).join(', ')}` }, 400);
+          const members = body.restricted ? (asked as string[]) : null;
+          opts.store.setAccess(org.id, name, members, session.person.id);
+          // everyone the World now leaves out loses the keys held for them there (and the previews those keys made)
+          let revoked = 0;
+          if (members !== null) {
+            for (const p of people) {
+              if (p.role.endsWith('admin') || members.includes(p.userId)) continue;
+              if (await revokeHeldIn(org.id, name, p.userId)) revoked += 1;
+            }
+          }
+          record({ event: 'WORLD_ACCESS_SET', org: org.id, actor: session.person, target: name, data: { restricted: members !== null, members: members?.length ?? null } });
+          return json({ world: name, restricted: members !== null, members: members ?? [], revokedFor: revoked });
+        }
         const previewDoor = /^\/-\/worlds\/([^/]+)\/([^/]+)\/previews(?:\/([^/]+)(\/open)?)?$/.exec(path);
         if (previewDoor) {
           const session = await sessionOf(request);
@@ -914,7 +1023,7 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
           const name = `${org.slug ?? org.id}/${previewDoor[2]}`;
           const label = previewDoor[3]; const opening = Boolean(previewDoor[4]);
           const held = opts.store.doc(org.id).worlds.find((w) => w.name === name);
-          if (!held) return json({ error: `no world ${name} in your orgs` }, 404);
+          if (!held || !mayReach(session.person, org, name)) return json({ error: `no world ${name} in your orgs` }, 404);
           const host = hostOf(held.host);
           if (!host) return json({ error: `the host ${held.host} that serves ${name} is not enrolled` }, 502);
           const inventory = async (): Promise<WorldRow[]> => { const r = await fetch(`${host.base}/-/worlds`, { headers: { 'x-volter-token': host.adminToken } }).catch(() => null); return r?.ok ? ((await r.json()) as { worlds: WorldRow[] }).worlds : []; };
@@ -1113,6 +1222,7 @@ export function createPlatform(opts: PlatformOptions): { fetch: (request: Reques
             // directory mails its own invitation, and the platform mails the one it keeps
             if (body.email && !body.sub && !(await dir.userIdByEmail(body.email))) {
               const inv = await dir.inviteMember(org.id, body.email, person.id, role);
+              noteInvited(org.id, inv);
               record({ event: 'MEMBER_INVITE', org: org.id, actor: person, target: body.email, data: { pending: true, invitation: inv.id, role } });
               if (!dir.mailsInvitations) await mail([inv.email], `${person.email ?? person.name ?? 'Someone'} invited you to ${orgLabel(org.id, org.slug)} on Volter World`, `You are invited to the org ${orgLabel(org.id, org.slug)}. Sign in at ${opts.origin}/ with ${identity.name}, as ${inv.email}, before ${(inv.expiresAt ?? '').slice(0, 10)} to join it.`);
               return json({ invited: body.email, pending: true, id: inv.id, expiresAt: inv.expiresAt }, 201);

package/src/store.ts

@@ -6,7 +6,7 @@
 // through the methods below, each one statement or one transaction.
 import { and, asc, eq, inArray } from 'drizzle-orm';
 import { openDatabase, type PlatformDb } from './db/open.ts';
-import { deliveries as deliveryRows, meta, orgSettings, orgWorlds, supportRequests, webhooks as webhookRows } from './db/schema.ts';
+import { deliveries as deliveryRows, meta, orgSettings, orgWorlds, supportRequests, webhooks as webhookRows, worldAccess } from './db/schema.ts';
 import type { Delivery, WebhookEndpoint } from './webhooks.ts';
 
 /** A world the org holds: it LIVES on a host — the platform records where, never its log. */
@@ -64,7 +64,22 @@ export class Store {
     catch (e) { if (/UNIQUE|PRIMARY KEY/i.test(String((e as Error).message))) throw new Error(`the org already holds a world named ${world.name}`); throw e; }
     return this.doc(orgId);
   }
-  removeWorld(orgId: string, name: string): OrgDoc { this.db.delete(orgWorlds).where(and(eq(orgWorlds.orgId, orgIdOf(orgId)), eq(orgWorlds.name, name))).run(); return this.doc(orgId); }
+  removeWorld(orgId: string, name: string): OrgDoc {
+    this.db.transaction((tx) => { tx.delete(orgWorlds).where(and(eq(orgWorlds.orgId, orgIdOf(orgId)), eq(orgWorlds.name, name))).run(); tx.delete(worldAccess).where(and(eq(worldAccess.orgId, orgIdOf(orgId)), eq(worldAccess.name, name))).run(); });
+    return this.doc(orgId);
+  }
+  /** Who a World is kept to: the listed members (admins reach it besides), or null for the whole org. */
+  accessOf(orgId: string, name: string): string[] | null {
+    const row = this.db.select({ members: worldAccess.members }).from(worldAccess).where(and(eq(worldAccess.orgId, orgIdOf(orgId)), eq(worldAccess.name, name))).get() as { members: string[] } | undefined;
+    return row ? row.members : null;
+  }
+  /** Keep a World to these members, or (null) open it to the whole org again. */
+  setAccess(orgId: string, name: string, members: string[] | null, setBy: string): void {
+    const where = and(eq(worldAccess.orgId, orgIdOf(orgId)), eq(worldAccess.name, name));
+    if (members === null) { this.db.delete(worldAccess).where(where).run(); return; }
+    const row = { members: [...new Set(members)].sort(), setBy, setAt: new Date().toISOString() };
+    this.db.insert(worldAccess).values({ orgId: orgIdOf(orgId), name, ...row }).onConflictDoUpdate({ target: [worldAccess.orgId, worldAccess.name], set: row }).run();
+  }
   /** Every org the platform holds a record for — the biller's roster. */
   orgIds(): string[] {
     const a = (this.db.selectDistinct({ id: orgWorlds.orgId }).from(orgWorlds).all() as Array<{ id: string }>).map((r) => r.id);
@@ -141,6 +156,10 @@ export class Store {
   // an org's previews, in its meta row (a handful per World, replaced whole)
   previewsOf(orgId: string): Preview[] { return this.metaOf<Preview[]>(`previews:${orgId}`) ?? []; }
   setPreviews(orgId: string, previews: Preview[]): void { this.setMeta(`previews:${orgId}`, previews); }
+  // the invitations the platform sent through a directory that lists them only by org (Volter's), by address: what
+  // an invited person who signs in here, instead of through the mail, is shown
+  invitedOf(email: string): Array<{ orgId: string; id: string }> { return this.metaOf<Array<{ orgId: string; id: string }>>(`invited:${email.toLowerCase()}`) ?? []; }
+  setInvited(email: string, list: Array<{ orgId: string; id: string }>): void { this.setMeta(`invited:${email.toLowerCase()}`, list); }
 
   // the platform's own position
   private metaOf<T>(key: string): T | null { return ((this.db.select().from(meta).where(eq(meta.key, key)).get() as { value: T } | undefined)?.value) ?? null; }

package/src/webhooks.ts

@@ -21,8 +21,8 @@ export type Delivery = {
 
 /** The catalog: the audit's events in dotted form, plus `ping` for the test button. */
 export const WEBHOOK_EVENTS: Readonly<Record<string, string>> = {
-  WORLD_PROVISION: 'world.provisioned', WORLD_DELETE: 'world.deleted', PREVIEW_CREATE: 'preview.created', PREVIEW_DELETE: 'preview.deleted',
-  MEMBER_INVITE: 'member.added', INVITE_REVOKE: 'member.invite_revoked', MEMBER_REMOVE: 'member.removed', MEMBER_ROLE: 'member.role_changed',
+  WORLD_PROVISION: 'world.provisioned', WORLD_DELETE: 'world.deleted', WORLD_ACCESS_SET: 'world.access_changed', PREVIEW_CREATE: 'preview.created', PREVIEW_DELETE: 'preview.deleted',
+  MEMBER_INVITE: 'member.added', MEMBER_JOIN: 'member.joined', INVITE_REVOKE: 'member.invite_revoked', MEMBER_REMOVE: 'member.removed', MEMBER_ROLE: 'member.role_changed',
   ORG_RENAME: 'org.renamed', PLAN_CHANGE: 'plan.changed',
   QUOTA_WARNED: 'quota.warned', QUOTA_RESTRICTED: 'quota.restricted', QUOTA_CLEARED: 'quota.cleared',
   IMPERSONATION: 'support.opened',