@volter/world-platform 2.0.2 → 2.0.4

package/dist/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/dist/src/db/migrations.js

@@ -29,5 +29,11 @@ export const MIGRATIONS = [
             "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/dist/src/db/pack-migrations.js

@@ -8,7 +8,7 @@ const dir = join(import.meta.dir, 'migrations');
 const target = join(import.meta.dir, 'migrations.ts');
 export function packed() {
     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/dist/src/db/schema.d.ts

@@ -101,6 +101,110 @@ export declare const orgWorlds: import("drizzle-orm/sqlite-core").SQLiteTableWit
     };
     dialect: "sqlite";
 }>;
+/** 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 declare const worldAccess: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "world_access";
+    schema: undefined;
+    columns: {
+        orgId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "org_id";
+            tableName: "world_access";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        name: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "name";
+            tableName: "world_access";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        members: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "members";
+            tableName: "world_access";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: string[];
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: string[];
+        }>;
+        setBy: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "set_by";
+            tableName: "world_access";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        setAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "set_at";
+            tableName: "world_access";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+    };
+    dialect: "sqlite";
+}>;
 /** An org's settings: its security switches, labs and support consent (absent: the defaults). */
 export declare const orgSettings: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
     name: "org_settings";

package/dist/src/db/schema.js

@@ -10,6 +10,15 @@ export const orgWorlds = sqliteTable('org_worlds', {
     base: text('base').notNull(),
     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().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/dist/src/directory.js

@@ -74,7 +74,9 @@ export function volterDirectory(identity) {
             return invitationView(inv);
         },
         pendingInvitations: async (orgId) => ((await call('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/dist/src/doors.js

@@ -16,14 +16,17 @@ export const DOORS = [
     { 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 }' },
@@ -104,7 +107,7 @@ export function platformApiMarkdown() {
         ['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/dist/src/platform.js

@@ -192,21 +192,43 @@ export function createPlatform(opts) {
     /** 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, world, person) => {
+        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 () => {
         let revoked = 0;
         for (const orgId of opts.store.orgIds()) {
-            const gone = new Map();
+            const membership = new Map();
             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()).keys : [];
+                // the people holding keys in the World or in a live preview branch of it
+                const keys = [];
+                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()).keys);
+                }
+                const keptTo = opts.store.accessOf(orgId, w.name);
                 for (const person of new Set(keys.map((k) => k.person).filter((p) => typeof p === 'string' && !p.startsWith('org-token:')))) {
-                    if (!gone.has(person))
-                        gone.set(person, (await dir.memberOf(person, orgId).catch(() => 'unknown')) === 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);
+                    if (!membership.has(person))
+                        membership.set(person, await dir.memberOf(person, orgId).catch(() => 'unknown'));
+                    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;
                     }
                 }
@@ -215,11 +237,8 @@ export function createPlatform(opts) {
         return revoked;
     };
     const revokePersonKeys = async (orgId, subject) => {
-        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 = opts.billing ? opts.billing({
@@ -283,6 +302,41 @@ export function createPlatform(opts) {
         const o = await dir.orgById(person.orgToken.orgId);
         return o ? [o] : [];
     } return dir.orgsOf(person.id); };
+    const invitedP = async (person) => {
+        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 = [];
+        const gone = new Set();
+        for (const n of noted) {
+            let pending;
+            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, inv, replaces) => {
+        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, ref) => { if (person.orgToken) {
         const o = await dir.orgById(person.orgToken.orgId);
         return o && (o.id === ref || o.slug === ref) ? o : null;
@@ -309,12 +363,26 @@ export function createPlatform(opts) {
         return { person: { id: signed.userId, ...(signed.email ? { email: signed.email } : {}), ...(signed.name ? { name: signed.name } : {}) }, token };
     };
     const redirect = (location) => 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, org, name) => {
+        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) => {
         const wanted = new Map(); // served name → host id
+        const kept = new Set(); // the ones kept to named members
         for (const org of await orgsOfP(person))
             for (const w of opts.store.doc(org.id).worlds)
-                wanted.set(w.name, w.host);
+                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 = [];
         const byHost = new Map();
         for (const host of opts.hosts) {
@@ -330,7 +398,7 @@ export function createPlatform(opts) {
             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}` });
+                rows.push({ ...row, base: `${host.base}/${row.name}`, ...(kept.has(name) ? { restricted: true } : {}) });
         }
         return rows.sort((a, b) => a.name.localeCompare(b.name));
     };
@@ -387,10 +455,14 @@ export function createPlatform(opts) {
         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;
@@ -742,7 +814,8 @@ export function createPlatform(opts) {
                         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)
+                    // 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)
@@ -813,7 +886,40 @@ export function createPlatform(opts) {
                         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.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;
@@ -1063,7 +1169,12 @@ export function createPlatform(opts) {
                         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);
+                        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 });
                     }
@@ -1081,8 +1192,14 @@ export function createPlatform(opts) {
                             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 } });
@@ -1203,7 +1320,7 @@ export function createPlatform(opts) {
                         return json({ deleted: org.id });
                     }
                     if (!part && request.method === 'GET')
-                        return json({ ...org, worlds: opts.store.doc(org.id).worlds });
+                        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 ──
@@ -1443,6 +1560,56 @@ export function createPlatform(opts) {
                 // 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;
+                    try {
+                        body = (await request.json());
+                    }
+                    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 : 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);
@@ -1460,7 +1627,7 @@ export function createPlatform(opts) {
                     const label = previewDoor[3];
                     const opening = Boolean(previewDoor[4]);
                     const held = opts.store.doc(org.id).worlds.find((w) => w.name === name);
-                    if (!held)
+                    if (!held || !mayReach(session.person, org, name))
                         return json({ error: `no world ${name} in your orgs` }, 404);
                     const host = hostOf(held.host);
                     if (!host)
@@ -1762,6 +1929,7 @@ export function createPlatform(opts) {
                         // 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.`);

package/dist/src/store.d.ts

@@ -80,6 +80,10 @@ export declare class Store {
     /** Record a World the org holds; one name once (the primary key refuses a second). */
     recordWorld(orgId: string, world: OrgWorld): OrgDoc;
     removeWorld(orgId: string, name: string): OrgDoc;
+    /** 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;
+    /** 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;
     /** Every org the platform holds a record for — the biller's roster. */
     orgIds(): string[];
     setSupportAccess(orgId: string, supportAccess: SupportAccess | null): OrgDoc;
@@ -103,6 +107,14 @@ export declare class Store {
     setSupportStatus(id: string, status: SupportRequest['status']): SupportRequest | null;
     previewsOf(orgId: string): Preview[];
     setPreviews(orgId: string, previews: Preview[]): void;
+    invitedOf(email: string): Array<{
+        orgId: string;
+        id: string;
+    }>;
+    setInvited(email: string, list: Array<{
+        orgId: string;
+        id: string;
+    }>): void;
     private metaOf;
     private setMeta;
     platform(): PlatformDoc;

package/dist/src/store.js

@@ -6,7 +6,7 @@
 // through the methods below, each one statement or one transaction.
 import { and, asc, eq, inArray } from 'drizzle-orm';
 import { openDatabase } from "./db/open.js";
-import { deliveries as deliveryRows, meta, orgSettings, orgWorlds, supportRequests, webhooks as webhookRows } from "./db/schema.js";
+import { deliveries as deliveryRows, meta, orgSettings, orgWorlds, supportRequests, webhooks as webhookRows, worldAccess } from "./db/schema.js";
 export const DEFAULT_SECURITY = { membersCanInvite: false, membersCanUsePersonalTokens: true, approvedEmailDomains: [] };
 const NAME = /^[a-z0-9][a-z0-9-]{0,38}$/;
 export function assertName(kind, value) {
@@ -49,7 +49,25 @@ export class Store {
         }
         return this.doc(orgId);
     }
-    removeWorld(orgId, name) { this.db.delete(orgWorlds).where(and(eq(orgWorlds.orgId, orgIdOf(orgId)), eq(orgWorlds.name, name))).run(); return this.doc(orgId); }
+    removeWorld(orgId, name) {
+        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, name) {
+        const row = this.db.select({ members: worldAccess.members }).from(worldAccess).where(and(eq(worldAccess.orgId, orgIdOf(orgId)), eq(worldAccess.name, name))).get();
+        return row ? row.members : null;
+    }
+    /** Keep a World to these members, or (null) open it to the whole org again. */
+    setAccess(orgId, name, members, setBy) {
+        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() {
         const a = this.db.selectDistinct({ id: orgWorlds.orgId }).from(orgWorlds).all().map((r) => r.id);
@@ -128,6 +146,10 @@ export class Store {
     // an org's previews, in its meta row (a handful per World, replaced whole)
     previewsOf(orgId) { return this.metaOf(`previews:${orgId}`) ?? []; }
     setPreviews(orgId, previews) { 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) { return this.metaOf(`invited:${email.toLowerCase()}`) ?? []; }
+    setInvited(email, list) { this.setMeta(`invited:${email.toLowerCase()}`, list); }
     // the platform's own position
     metaOf(key) { return (this.db.select().from(meta).where(eq(meta.key, key)).get()?.value) ?? null; }
     setMeta(key, value) { this.db.insert(meta).values({ key, value }).onConflictDoUpdate({ target: meta.key, set: { value } }).run(); }

package/dist/src/webhooks.js

@@ -8,8 +8,8 @@ import { createHmac, randomBytes } from 'node:crypto';
 import { lookup } from 'node:dns/promises';
 /** The catalog: the audit's events in dotted form, plus `ping` for the test button. */
 export const WEBHOOK_EVENTS = {
-    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',