@volter/world-platform 2.0.0

package/dist/src/db/schema.js

@@ -0,0 +1,123 @@
+// THE PLATFORM'S STATE (docs/contributing/architecture.md, "The platform's state is SQLite"): one schema, whose
+// migrations `drizzle-kit generate` writes as plain SQL under ./migrations. Every table is the platform's own record:
+// a World's state is never here (it stays behind WorldStore). JSON columns hold only small nested lists.
+import { index, integer, primaryKey, sqliteTable, text } from 'drizzle-orm/sqlite-core';
+/** The Worlds an org holds, and where each lives: the platform records where, never a World's log. */
+export const orgWorlds = sqliteTable('org_worlds', {
+    orgId: text('org_id').notNull(),
+    name: text('name').notNull(),
+    host: text('host').notNull(),
+    base: text('base').notNull(),
+    provisionedAt: text('provisioned_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(),
+    security: text('security', { mode: 'json' }).$type(),
+    flags: text('flags', { mode: 'json' }).$type(),
+    earlyAdopter: integer('early_adopter', { mode: 'boolean' }),
+    supportAccess: text('support_access', { mode: 'json' }).$type(),
+});
+export const webhooks = sqliteTable('webhooks', {
+    id: text('id').primaryKey(),
+    orgId: text('org_id').notNull(),
+    url: text('url').notNull(),
+    secret: text('secret').notNull(),
+    events: text('events', { mode: 'json' }).$type().notNull(),
+    description: text('description').notNull(),
+    createdAt: text('created_at').notNull(),
+    consecutiveFailures: integer('consecutive_failures').notNull(),
+    lastFailedAt: text('last_failed_at'),
+    disabledAt: text('disabled_at'),
+}, (t) => [index('webhooks_org').on(t.orgId)]);
+export const deliveries = sqliteTable('deliveries', {
+    id: text('id').primaryKey(),
+    orgId: text('org_id').notNull(),
+    endpointId: text('endpoint_id').notNull(),
+    eventId: text('event_id').notNull(),
+    event: text('event').notNull(),
+    body: text('body').notNull(),
+    attempt: integer('attempt').notNull(),
+    nextAt: text('next_at').notNull(),
+    attempts: text('attempts', { mode: 'json' }).$type().notNull(),
+    state: text('state', { enum: ['pending', 'delivered', 'failed'] }).notNull(),
+    /** the order the queue keeps */
+    seq: integer('seq').notNull(),
+}, (t) => [index('deliveries_state').on(t.state, t.nextAt), index('deliveries_endpoint').on(t.endpointId)]);
+export const supportRequests = sqliteTable('support_requests', {
+    id: text('id').primaryKey(),
+    at: text('at').notNull(),
+    person: text('person', { mode: 'json' }).$type().notNull(),
+    org: text('org'),
+    world: text('world'),
+    category: text('category').notNull(),
+    severity: text('severity').notNull(),
+    subject: text('subject').notNull(),
+    message: text('message').notNull(),
+    status: text('status', { enum: ['open', 'closed'] }).notNull(),
+});
+/** The platform's own position: the last backup, the operator's notice; one row per key. */
+export const meta = sqliteTable('meta', { key: text('key').primaryKey(), value: text('value', { mode: 'json' }) });
+/** Personal, org and support tokens: only their hash is kept. */
+export const tokens = sqliteTable('tokens', {
+    hash: text('hash').primaryKey(),
+    userId: text('user_id').notNull(),
+    name: text('name').notNull(),
+    createdAt: text('created_at').notNull(),
+    last4: text('last4').notNull(),
+    lastUsedAt: text('last_used_at'),
+    expiresAt: text('expires_at'),
+    scopes: text('scopes', { mode: 'json' }).$type(),
+    orgId: text('org_id'),
+    support: text('support', { mode: 'json' }).$type(),
+    worldKeys: text('world_keys', { mode: 'json' }).$type(),
+}, (t) => [index('tokens_user').on(t.userId), index('tokens_org').on(t.orgId)]);
+/** The platform's browser sessions, by the SHA-256 of the cookie's id. */
+export const sessions = sqliteTable('sessions', {
+    idHash: text('id_hash').primaryKey(),
+    subject: text('subject').notNull(),
+    email: text('email'),
+    name: text('name'),
+    expiresAt: text('expires_at').notNull(),
+});
+/** The audit log: append-only, per org, in order. */
+export const audit = sqliteTable('audit', {
+    seq: integer('seq').primaryKey({ autoIncrement: true }),
+    org: text('org').notNull(),
+    at: text('at').notNull(),
+    event: text('event').notNull(),
+    actor: text('actor', { mode: 'json' }).notNull(),
+    target: text('target'),
+    data: text('data', { mode: 'json' }),
+}, (t) => [index('audit_org').on(t.org, t.seq)]);
+// ── the directory the platform keeps when its provider only signs people in (directory.ts localDirectory) ──
+export const people = sqliteTable('people', {
+    id: text('id').primaryKey(),
+    email: text('email'),
+    emailVerified: integer('email_verified', { mode: 'boolean' }).notNull(),
+    name: text('name'),
+    firstSeenAt: text('first_seen_at').notNull(),
+    lastSeenAt: text('last_seen_at').notNull(),
+}, (t) => [index('people_email').on(t.email)]);
+export const dirOrgs = sqliteTable('dir_orgs', {
+    id: text('id').primaryKey(),
+    slug: text('slug').notNull().unique(),
+    name: text('name').notNull(),
+    createdAt: text('created_at').notNull(),
+});
+export const dirMembers = sqliteTable('dir_members', {
+    orgId: text('org_id').notNull(),
+    userId: text('user_id').notNull(),
+    role: text('role', { enum: ['org:admin', 'org:member'] }).notNull(),
+}, (t) => [primaryKey({ columns: [t.orgId, t.userId] }), index('dir_members_user').on(t.userId)]);
+export const invitations = sqliteTable('invitations', {
+    id: text('id').primaryKey(),
+    orgId: text('org_id').notNull(),
+    email: text('email').notNull(),
+    role: text('role', { enum: ['org:admin', 'org:member'] }).notNull(),
+    inviterId: text('inviter_id').notNull(),
+    createdAt: text('created_at').notNull(),
+    expiresAt: text('expires_at').notNull(),
+}, (t) => [index('invitations_org').on(t.orgId), index('invitations_email').on(t.email)]);
+/** What an attached biller keeps (apps/billing), by its own keys: the platform names no plan or price. */
+export const billerRecords = sqliteTable('biller_records', { key: text('key').primaryKey(), value: text('value', { mode: 'json' }).notNull() });

package/dist/src/directory.d.ts

@@ -0,0 +1,75 @@
+import type { Identity } from './identity.js';
+export type OrgRef = {
+    id: string;
+    slug: string | null;
+    name: string;
+    role: string;
+};
+export type Member = {
+    id: string;
+    userId: string;
+    email: string | null;
+    name: string | null;
+    role: string;
+};
+export type PendingInvitation = {
+    id: string;
+    email: string;
+    role: string;
+    createdAt: string | null;
+    expiresAt: string | null;
+};
+export type Person = {
+    id: string;
+    email?: string;
+    name?: string;
+};
+/** Who a provider signed in, as its id token (or userinfo) named them. */
+export type SignedInPerson = {
+    subject: string;
+    email?: string;
+    emailVerified?: boolean;
+    name?: string;
+};
+export type Directory = {
+    /** The organizations a person belongs to, with their role, by slug. */
+    orgsOf: (userId: string) => Promise<OrgRef[]>;
+    /** An org a person belongs to, by id or slug — the only way the platform resolves a person's org. */
+    memberOf: (userId: string, ref: string) => Promise<OrgRef | null>;
+    /** An org by id or slug, whoever asks (an org token, the operator's claim). */
+    orgById: (ref: string) => Promise<OrgRef | null>;
+    /** Make an org named `name` (its slug) with the person as its admin. */
+    createOrg: (name: string, userId: string) => Promise<OrgRef>;
+    renameOrg: (orgId: string, name: string) => Promise<OrgRef>;
+    deleteOrg: (orgId: string) => Promise<void>;
+    membersOf: (orgId: string) => Promise<Member[]>;
+    /** Add a person the directory knows, by id or by email. */
+    addMember: (orgId: string, who: {
+        sub?: string;
+        email?: string;
+    }) => Promise<void>;
+    /** Remove a member; a directory that can refuses, in the same write, to leave the org without an admin (OnlyAdmin). */
+    removeMember: (orgId: string, userId: string) => Promise<void>;
+    /** Change a role; the org's only admin stepping down is refused as removeMember's is. */
+    setMemberRole: (orgId: string, userId: string, role: 'org:admin' | 'org:member') => Promise<void>;
+    /** Invite an address the directory does not know yet; it joins when that address signs in. */
+    inviteMember: (orgId: string, email: string, inviterUserId: string, role?: string) => Promise<PendingInvitation>;
+    pendingInvitations: (orgId: string) => Promise<PendingInvitation[]>;
+    revokeInvitation: (orgId: string, invitationId: string) => Promise<void>;
+    /** The person an address belongs to, when the directory knows it (verified). */
+    userIdByEmail: (email: string) => Promise<string | null>;
+    personById: (userId: string) => Promise<Person | null>;
+    /** A person signed in: the directory records them and lets their invitations in. */
+    seen: (person: SignedInPerson) => Promise<void>;
+    /** Whether the directory mails its own invitations (else the platform does). */
+    mailsInvitations: boolean;
+};
+export declare const isAdmin: (o: OrgRef) => boolean;
+export declare function volterDirectory(identity: Identity): Directory;
+/** Refused: the change would leave the org without an admin. */
+export declare class OnlyAdmin extends Error {
+    constructor();
+}
+/** The directory the platform keeps in its database (db/schema.ts people, dir_orgs, dir_members, invitations), for a
+ *  platform whose provider only signs people in. Each change is one statement or one transaction. */
+export declare function localDirectory(stateDir: string): Directory;

package/dist/src/directory.js

@@ -0,0 +1,199 @@
+// THE DIRECTORY (docs/contributing/architecture.md, "The hosted product": a platform has one access provider, which
+// brings its directory): who the people are, the orgs, their members, roles and invitations. The platform reads one
+// vocabulary through this interface and never learns which directory answers:
+//
+// - `volterDirectory`: the Volter identity service's (volter-ai/identity ADR-0002, "a product keeps its
+//   organizations here, with its own credential"), through its product door (`/api/organizations`, `/api/people`)
+//   with the platform's own `client_credentials` token. The service mails its own invitations.
+// - `localDirectory`: the platform's own, in its state directory, for an OpenID Connect provider that only signs
+//   people in (Google, Entra, Okta, Keycloak). A person is known once they have signed in; an invitation waits for
+//   the address to sign in with a verified email, and the platform mails it.
+//
+// Roles are one vocabulary here: `org:admin` and `org:member` (the identity service's `owner` and `admin` read as
+// `org:admin`).
+import { randomBytes } from 'node:crypto';
+import { and, asc, eq, gt, ne, or, sql } from 'drizzle-orm';
+import { openDatabase } from "./db/open.js";
+import { dirMembers, dirOrgs, invitations, people } from "./db/schema.js";
+export const isAdmin = (o) => o.role === 'org:admin' || o.role === 'admin';
+const readRole = (role) => (role.split(',').some((r) => r.trim() === 'owner' || r.trim() === 'admin') ? 'org:admin' : 'org:member');
+const writeRole = (role) => (role === 'org:admin' || role === 'admin' ? 'admin' : 'member');
+const seg = (s) => encodeURIComponent(s);
+export function volterDirectory(identity) {
+    const call = identity.call;
+    const invitationView = (inv) => ({ id: inv.id, email: inv.email, role: readRole(inv.role), createdAt: inv.createdAt ?? null, expiresAt: inv.expiresAt ?? null });
+    const userIdByEmail = async (email) => (await call('GET', `/api/people?email=${encodeURIComponent(email)}`))?.id ?? null;
+    const orgsOf = async (userId) => ((await call('GET', `/api/people/${seg(userId)}/organizations`)) ?? [])
+        .map((o) => ({ id: o.id, slug: o.slug, name: o.name, role: readRole(o.role ?? 'member') }))
+        .sort((a, b) => (a.slug ?? a.name).localeCompare(b.slug ?? b.name));
+    return {
+        mailsInvitations: true,
+        orgsOf,
+        memberOf: async (userId, ref) => (await orgsOf(userId)).find((o) => o.id === ref || o.slug === ref) ?? null,
+        // the service answers an org by id or by slug
+        async orgById(ref) { try {
+            const o = await call('GET', `/api/organizations/${seg(ref)}`);
+            return o ? { id: o.id, slug: o.slug, name: o.name, role: 'org:member' } : null;
+        }
+        catch {
+            return null;
+        } },
+        async createOrg(name, userId) {
+            const org = await call('POST', '/api/organizations', { name, slug: name, createdBy: userId });
+            if (!org)
+                throw new Error('the identity service has no organizations door');
+            return { id: org.id, slug: org.slug, name: org.name, role: 'org:admin' };
+        },
+        async renameOrg(orgId, name) {
+            const org = await call('PATCH', `/api/organizations/${seg(orgId)}`, { name }); // the slug stays: it is the served prefix of every World the org holds
+            if (!org)
+                throw new Error('no such organization');
+            return { id: org.id, slug: org.slug, name: org.name, role: 'org:admin' };
+        },
+        async deleteOrg(orgId) { await call('DELETE', `/api/organizations/${seg(orgId)}`); },
+        async membersOf(orgId) {
+            const rows = (await call('GET', `/api/organizations/${seg(orgId)}/members`)) ?? [];
+            return rows.map((m) => ({ id: m.id, userId: m.userId, email: m.email ?? null, name: m.name || null, role: readRole(m.role) }));
+        },
+        async addMember(orgId, who) {
+            let userId = who.sub;
+            if (!userId && who.email)
+                userId = (await userIdByEmail(who.email)) ?? undefined;
+            if (!userId)
+                throw new Error('no such person at the identity service: a member is named by Volter id or by an email that has a Volter identity');
+            if (!(await call('POST', `/api/organizations/${seg(orgId)}/members`, { userId, role: 'member' })))
+                throw new Error('no such organization');
+        },
+        async removeMember(orgId, userId) { await call('DELETE', `/api/organizations/${seg(orgId)}/members/${seg(userId)}`); },
+        async setMemberRole(orgId, userId, role) { if (!(await call('PATCH', `/api/organizations/${seg(orgId)}/members/${seg(userId)}`, { role: writeRole(role) })))
+            throw new Error('not a member'); },
+        async inviteMember(orgId, email, inviterUserId, role = 'org:member') {
+            const inv = await call('POST', `/api/organizations/${seg(orgId)}/invitations`, { email, role: writeRole(role), inviterId: inviterUserId });
+            if (!inv)
+                throw new Error('no such organization');
+            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)}`); },
+        userIdByEmail,
+        async personById(userId) {
+            try {
+                const p = await call('GET', `/api/people/${seg(userId)}`);
+                return p ? { id: p.id, ...(p.email ? { email: p.email } : {}), ...(p.name ? { name: p.name } : {}) } : null;
+            }
+            catch {
+                return null;
+            }
+        },
+        // the identity service keeps its people and accepts its own invitations
+        async seen() { },
+    };
+}
+/** Refused: the change would leave the org without an admin. */
+export class OnlyAdmin extends Error {
+    constructor() { super("the org's only admin"); }
+}
+// ── the platform's own, in its database ────────────────────────────────────────────────────────
+const INVITATION_DAYS = 7;
+/** The directory the platform keeps in its database (db/schema.ts people, dir_orgs, dir_members, invitations), for a
+ *  platform whose provider only signs people in. Each change is one statement or one transaction. */
+export function localDirectory(stateDir) {
+    const db = openDatabase(stateDir);
+    const orgRow = (ref) => db.select().from(dirOrgs).where(or(eq(dirOrgs.id, ref), eq(dirOrgs.slug, ref))).get();
+    const refOf = (o, role) => ({ id: o.id, slug: o.slug, name: o.name, role });
+    const mustOrg = (orgId) => { const o = db.select().from(dirOrgs).where(eq(dirOrgs.id, orgId)).get(); if (!o)
+        throw new Error('no such organization'); return o; };
+    const roleOf = (orgId, userId) => db.select({ role: dirMembers.role }).from(dirMembers).where(and(eq(dirMembers.orgId, orgId), eq(dirMembers.userId, userId))).get()?.role ?? null;
+    // the member is not an admin, or another admin remains
+    const keepsAnAdmin = (orgId, userId) => or(ne(dirMembers.role, 'org:admin'), sql `exists (select 1 from ${dirMembers} as other where other.org_id = ${orgId} and other.user_id <> ${userId} and other.role = 'org:admin')`);
+    const view = (i) => ({ id: i.id, email: i.email, role: i.role, createdAt: i.createdAt, expiresAt: i.expiresAt });
+    // only an address the provider verified names a person: an unverified one could be anyone's
+    const byEmail = (email) => db.select({ id: people.id }).from(people).where(and(eq(people.email, email.trim().toLowerCase()), eq(people.emailVerified, true))).get()?.id ?? null;
+    return {
+        mailsInvitations: false,
+        async orgsOf(userId) {
+            return db.select({ o: dirOrgs, role: dirMembers.role }).from(dirMembers).innerJoin(dirOrgs, eq(dirOrgs.id, dirMembers.orgId)).where(eq(dirMembers.userId, userId)).orderBy(asc(dirOrgs.slug)).all()
+                .map(({ o, role }) => refOf(o, role));
+        },
+        async memberOf(userId, r) { const o = orgRow(r); const role = o ? roleOf(o.id, userId) : null; return o && role ? refOf(o, role) : null; },
+        async orgById(r) { const o = orgRow(r); return o ? refOf(o, 'org:member') : null; },
+        async createOrg(name, userId) {
+            const id = `org_${randomBytes(9).toString('base64url').replace(/[^A-Za-z0-9]/g, 'x')}`;
+            try {
+                db.transaction((tx) => {
+                    tx.insert(dirOrgs).values({ id, slug: name, name, createdAt: new Date().toISOString() }).run();
+                    tx.insert(dirMembers).values({ orgId: id, userId, role: 'org:admin' }).run();
+                });
+            }
+            catch (e) {
+                if (/UNIQUE/i.test(String(e.message)))
+                    throw new Error(`an org named ${name} exists`);
+                throw e;
+            }
+            return { id, slug: name, name, role: 'org:admin' };
+        },
+        async renameOrg(orgId, name) { const o = mustOrg(orgId); db.update(dirOrgs).set({ name }).where(eq(dirOrgs.id, orgId)).run(); return refOf({ ...o, name }, 'org:admin'); },
+        async deleteOrg(orgId) {
+            db.transaction((tx) => { tx.delete(dirMembers).where(eq(dirMembers.orgId, orgId)).run(); tx.delete(invitations).where(eq(invitations.orgId, orgId)).run(); tx.delete(dirOrgs).where(eq(dirOrgs.id, orgId)).run(); });
+        },
+        async membersOf(orgId) {
+            mustOrg(orgId);
+            return db.select({ userId: dirMembers.userId, role: dirMembers.role, email: people.email, name: people.name }).from(dirMembers).leftJoin(people, eq(people.id, dirMembers.userId)).where(eq(dirMembers.orgId, orgId)).all()
+                .map((m) => ({ id: `${orgId}:${m.userId}`, userId: m.userId, email: m.email ?? null, name: m.name ?? null, role: m.role }));
+        },
+        async addMember(orgId, who) {
+            mustOrg(orgId);
+            const known = who.sub ? db.select({ id: people.id }).from(people).where(eq(people.id, who.sub)).get()?.id ?? null : null;
+            const userId = known ?? (who.email ? byEmail(who.email) : null);
+            if (!userId)
+                throw new Error('no such person here: a member is someone who has signed in to this platform (invite an address that has not)');
+            db.insert(dirMembers).values({ orgId, userId, role: 'org:member' }).onConflictDoNothing().run();
+        },
+        // one statement each: the check that another admin remains and the write cannot be split by a concurrent change
+        async removeMember(orgId, userId) {
+            mustOrg(orgId);
+            const r = db.delete(dirMembers).where(and(eq(dirMembers.orgId, orgId), eq(dirMembers.userId, userId), keepsAnAdmin(orgId, userId))).run();
+            if (!r.changes && roleOf(orgId, userId))
+                throw new OnlyAdmin();
+        },
+        async setMemberRole(orgId, userId, role) {
+            mustOrg(orgId);
+            const r = db.update(dirMembers).set({ role }).where(and(eq(dirMembers.orgId, orgId), eq(dirMembers.userId, userId), role === 'org:member' ? keepsAnAdmin(orgId, userId) : undefined)).run();
+            if (!r.changes) {
+                if (roleOf(orgId, userId))
+                    throw new OnlyAdmin();
+                throw new Error('not a member');
+            }
+        },
+        async inviteMember(orgId, email, inviterUserId, role = 'org:member') {
+            mustOrg(orgId);
+            const address = email.trim().toLowerCase();
+            if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(address))
+                throw new Error('not an email address');
+            const now = Date.now();
+            const inv = { id: `inv_${randomBytes(8).toString('hex')}`, orgId, email: address, role: (role === 'org:admin' ? 'org:admin' : 'org:member'), inviterId: inviterUserId, createdAt: new Date(now).toISOString(), expiresAt: new Date(now + INVITATION_DAYS * 86_400_000).toISOString() };
+            // a second invitation to an address replaces the first
+            db.transaction((tx) => { tx.delete(invitations).where(and(eq(invitations.orgId, orgId), eq(invitations.email, address))).run(); tx.insert(invitations).values(inv).run(); });
+            return view(inv);
+        },
+        async pendingInvitations(orgId) { return db.select().from(invitations).where(and(eq(invitations.orgId, orgId), gt(invitations.expiresAt, new Date().toISOString()))).orderBy(asc(invitations.createdAt)).all().map(view); },
+        async revokeInvitation(orgId, invitationId) { db.delete(invitations).where(and(eq(invitations.orgId, orgId), eq(invitations.id, invitationId))).run(); },
+        async userIdByEmail(email) { return byEmail(email); },
+        async personById(userId) { const p = db.select().from(people).where(eq(people.id, userId)).get(); return p ? { id: userId, ...(p.email ? { email: p.email } : {}), ...(p.name ? { name: p.name } : {}) } : null; },
+        async seen(person) {
+            const now = new Date().toISOString();
+            const email = person.email ? person.email.toLowerCase() : null;
+            db.transaction((tx) => {
+                tx.insert(people).values({ id: person.subject, email, emailVerified: Boolean(person.emailVerified), name: person.name ?? null, firstSeenAt: now, lastSeenAt: now })
+                    .onConflictDoUpdate({ target: people.id, set: { email, emailVerified: Boolean(person.emailVerified), name: person.name ?? null, lastSeenAt: now } }).run();
+                // an invitation lets in the person who signs in with its address, verified by the provider
+                if (email && person.emailVerified) {
+                    const due = tx.select().from(invitations).where(and(eq(invitations.email, email), gt(invitations.expiresAt, now))).all();
+                    for (const inv of due)
+                        tx.insert(dirMembers).values({ orgId: inv.orgId, userId: person.subject, role: inv.role }).onConflictDoNothing().run();
+                    tx.delete(invitations).where(eq(invitations.email, email)).run();
+                }
+            });
+        },
+    };
+}

package/dist/src/doors.d.ts

@@ -0,0 +1,16 @@
+export type Door = {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    /** who opens it */
+    who: 'anyone' | 'person' | 'admin' | 'operator';
+    /** the object:action a token needs, or none */
+    scope: string | null;
+    summary: string;
+    body?: string;
+    answers: string;
+};
+export declare const DOORS: readonly Door[];
+/** The table as OpenAPI 3.1. */
+export declare function openapi(origin: string): Record<string, unknown>;
+/** The table as the docs page. */
+export declare function platformApiMarkdown(): string;

package/dist/src/doors.js

@@ -0,0 +1,123 @@
+export const DOORS = [
+    { method: 'GET', path: '/-/health', who: 'anyone', scope: null, summary: 'Whether the platform is up, and which hosts it knows.', answers: '{ ok, hosts[] }' },
+    { method: 'GET', path: '/.well-known/jwks.json', who: 'anyone', scope: null, summary: 'The public keys this platform signs passes with, for the hosts that trust it.', answers: '{ keys[] }' },
+    { method: 'GET', path: '/-/platform', who: 'anyone', scope: null, summary: 'What the pages need before anyone signs in: the access provider people continue with (and their account page there, when it has one), whether the platform bills, whether the Help form is on, and the product site\'s address when there is one.', answers: '{ name, provider: { kind, name, account? }, billing, support, site? }' },
+    { method: 'GET', path: '/-/sign-in', who: 'anyone', scope: null, summary: 'Start signing in at the access provider (the authorization code with PKCE); `?next=` names a path of this platform to return to.', answers: '302 to the provider' },
+    { method: 'POST', path: '/-/sign-out', who: 'anyone', scope: null, summary: 'End your session here (not at the provider), from the platform\'s own page (a GET is refused with 405).', answers: '302 to the front page' },
+    { method: 'GET', path: '/-/status', who: 'anyone', scope: null, summary: 'The status page\'s source: each host up or down, the operator\'s notice, the clock\'s last runs.', answers: '{ ok, platform, hosts[], notice, clock, askedAt }' },
+    { method: 'POST', path: '/-/status/notice', who: 'operator', scope: null, summary: 'Set or clear the notice the status page shows.', body: '{ text | null }', answers: '{ notice }' },
+    { method: 'GET', path: '/-/openapi.json', who: 'anyone', scope: null, summary: 'This table as an OpenAPI 3.1 document.', answers: 'OpenAPI' },
+    { method: 'GET', path: '/-/vendors', who: 'person', scope: null, summary: 'The twins a new World may have: what the host Worlds are made on serves, as it answers.', answers: '{ host, vendors[] }' },
+    { method: 'GET', path: '/-/worlds', who: 'person', scope: 'worlds:read', summary: 'The worlds your orgs hold, with their addresses and twins.', answers: '{ worlds[] }' },
+    { method: 'POST', path: '/-/worlds', who: 'person', scope: 'worlds:write', summary: 'Provision a world into an org, on an enrolled host; where the platform bills, refused at the plan\'s limits with 402.', body: '{ org, world, vendors[] }', answers: '{ name, base, host }' },
+    { method: 'POST', path: '/-/worlds/sample', who: 'person', scope: 'worlds:write', summary: 'Make the org\'s sample World (`<org>/sample`, Stripe and Slack where the host serves them) and seed it through the vendors\' own APIs: a World like any other, metered and deletable; 409 when it exists.', body: '{ org }', answers: '{ name, base, host, seeded: { <vendor>: { seeded[] } | { error } } }' },
+    { method: 'DELETE', path: '/-/worlds/{org}/{world}', who: 'admin', scope: 'worlds:write', summary: 'Delete a world through its host.', answers: '{ deleted }' },
+    { method: 'GET', path: '/-/worlds/{org}/{world}/open', who: 'person', scope: 'worlds:read', summary: 'Open the world as yourself: a pass for it, signed for you and for the world\'s own origin, spent on a session there (write for a member, read for a support session or a token without worlds:write); 409 for a world whose host gives it no origin of its own. A redirect to the page with the pass in its fragment; JSON asks for the address.', answers: '303 to the world\'s page, or { url, scope, expiresIn }' },
+    { 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: '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}/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: '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 }' },
+    { method: 'DELETE', path: '/-/orgs/{org}', who: 'admin', scope: 'orgs:write', summary: 'Delete the org; refused while it holds worlds unless `?everything=1`, which deletes them through their hosts first.', answers: '{ deleted }' },
+    { method: 'GET', path: '/-/orgs/{org}/billing', who: 'person', scope: 'billing:read', summary: 'Where the platform bills: the org\'s plan, usage this period (and by day), restriction, pending checkout, the plans on offer.', answers: '{ plan, plans[], usage, usageByDay[], restriction, pendingCheckout, paid, lastTickAt }' },
+    { method: 'PATCH', path: '/-/orgs/{org}/billing', who: 'admin', scope: 'billing:write', summary: 'Where the platform bills, the spend cap (Team): on, the plan\'s hours restrict after the grace; off, hours beyond the plan are billed at the metered price.', body: '{ spendCap: boolean }', answers: '{ spendCap }' },
+    { method: 'POST', path: '/-/orgs/{org}/checkout', who: 'admin', scope: 'billing:write', summary: 'Where the platform bills: open (or answer the open) Polar checkout for the Team plan.', answers: '{ id, url, pending? }' },
+    { method: 'POST', path: '/-/orgs/{org}/billing-portal', who: 'admin', scope: 'billing:write', summary: 'Where the platform bills: a session for Polar\'s customer portal: invoices, payment method, cancellation.', answers: '{ url }' },
+    { method: 'GET', path: '/-/orgs/{org}/members', who: 'person', scope: 'members:read', summary: 'The members and their roles, and the pending invitations.', answers: '{ members[], pending[] }' },
+    { method: 'POST', path: '/-/orgs/{org}/members', who: 'admin', scope: 'members:write', summary: 'Add a member the directory knows, or invite an address it does not (pending until that address signs in; mailed), as a member or (by an admin) an admin. Members may invite by email when the security page allows; adding by id is an admin\'s, and answers to the approved domains by the person\'s address. Not both at once.', body: '{ email, role? } | { sub, role? }', answers: '{ added } | { invited, pending: true, id }' },
+    { method: 'PATCH', path: '/-/orgs/{org}/members/{userId}', who: 'admin', scope: 'members:write', summary: 'Change a member\'s role; the org\'s only admin may not become a member (409).', body: '{ role: admin | member }', answers: '{ userId, role }' },
+    { method: 'DELETE', path: '/-/orgs/{org}/members/{userId}', who: 'admin', scope: 'members:write', summary: 'Remove a member (an admin), or leave the org yourself (any member); the org\'s only admin cannot be removed or leave.', answers: '{ removed }' },
+    { method: 'POST', path: '/-/orgs/{org}/invitations/{id}/resend', who: 'admin', scope: 'members:write', summary: 'Send a pending invitation again: a fresh one to the same address and role, for another week (its id may change). An admin, or a member where the security page lets members invite, for a member\'s invitation only; the approved domains apply.', answers: '{ invited, pending, id, role, expiresAt }' },
+    { method: 'DELETE', path: '/-/orgs/{org}/invitations/{id}', who: 'admin', scope: 'members:write', summary: 'Revoke a pending invitation.', answers: '{ revoked }' },
+    { method: 'GET', path: '/-/orgs/{org}/tokens', who: 'admin', scope: 'tokens:read', summary: 'The org\'s tokens (for CI), without their secrets.', answers: '{ tokens[] }' },
+    { method: 'POST', path: '/-/orgs/{org}/tokens', who: 'admin', scope: 'tokens:write', summary: 'Make an org token: bound to the org, scoped (read only by default), expiring; shown once.', body: '{ name, scopes?, expiresInDays? }', answers: '{ token, id, scopes, expiresAt }' },
+    { method: 'DELETE', path: '/-/orgs/{org}/tokens/{id}', who: 'admin', scope: 'tokens:write', summary: 'Revoke an org token.', answers: '{ revoked }' },
+    { method: 'GET', path: '/-/orgs/{org}/security', who: 'person', scope: 'orgs:read', summary: 'The org\'s security switches.', answers: '{ security }' },
+    { method: 'PATCH', path: '/-/orgs/{org}/security', who: 'admin', scope: 'orgs:write', summary: 'Set the switches: members may invite, personal tokens allowed, approved email domains.', body: '{ membersCanInvite?, membersCanUsePersonalTokens?, approvedEmailDomains? }', answers: '{ security }' },
+    { method: 'GET', path: '/-/orgs/{org}/support-access', who: 'person', scope: 'orgs:read', summary: 'Whether, and until when, support may open the org.', answers: '{ supportAccess }' },
+    { method: 'DELETE', path: '/-/orgs/{org}/support-access', who: 'admin', scope: 'orgs:write', summary: 'Revoke support access.', answers: '{ revoked }' },
+    { method: 'GET', path: '/-/orgs/{org}/labs', who: 'person', scope: 'orgs:read', summary: 'The early-access features, which are on for the org, and the early-adopter switch.', answers: '{ features[], earlyAdopter, flags }' },
+    { method: 'PATCH', path: '/-/orgs/{org}/labs', who: 'admin', scope: 'orgs:write', summary: 'Turn an early-access feature on or off, or turn on every new one with the early-adopter switch.', body: '{ flags?: { key: boolean }, earlyAdopter? }', answers: '{ flags, earlyAdopter }' },
+    { method: 'GET', path: '/-/orgs/{org}/webhooks', who: 'admin', scope: 'orgs:read', summary: 'The org\'s webhook endpoints and their state, and the event names.', answers: '{ webhooks[], events[] }' },
+    { method: 'POST', path: '/-/orgs/{org}/webhooks', who: 'admin', scope: 'orgs:write', summary: 'Add an endpoint: a URL and the events it wants; the secret is answered once (Standard Webhooks signing).', body: '{ url, events?: ["*" | names], description? }', answers: '{ id, url, events, secret }' },
+    { method: 'PATCH', path: '/-/orgs/{org}/webhooks/{id}', who: 'admin', scope: 'orgs:write', summary: 'Change an endpoint\'s events or description, or enable/disable it.', body: '{ events?, description?, enabled? }', answers: '{ id, … }' },
+    { method: 'DELETE', path: '/-/orgs/{org}/webhooks/{id}', who: 'admin', scope: 'orgs:write', summary: 'Remove an endpoint.', answers: '{ deleted }' },
+    { method: 'POST', path: '/-/orgs/{org}/webhooks/{id}/test', who: 'admin', scope: 'orgs:write', summary: 'Send a `ping` event now and answer the delivery with its attempt.', answers: '{ delivery }' },
+    { method: 'GET', path: '/-/orgs/{org}/webhooks/{id}/deliveries', who: 'admin', scope: 'orgs:read', summary: 'The endpoint\'s last fifty deliveries, each attempt with its status and the response\'s first 2 KB.', answers: '{ deliveries[] }' },
+    { method: 'GET', path: '/-/orgs/{org}/audit', who: 'admin', scope: 'activity:read', summary: 'The org\'s activity: every admin act, newest first.', answers: '{ entries[] }' },
+    { method: 'GET', path: '/-/orgs/{org}/audit.jsonl', who: 'admin', scope: 'activity:read', summary: 'The activity as the file kept, one act a line.', answers: 'JSON lines' },
+    { method: 'GET', path: '/-/orgs/{org}/export', who: 'admin', scope: 'activity:read', summary: 'What the platform knows about the org: the record, the worlds, the members, the activity.', answers: 'JSON' },
+    { method: 'GET', path: '/-/tokens', who: 'person', scope: 'tokens:read', summary: 'Your personal access tokens, without their secrets.', answers: '{ tokens[] }' },
+    { method: 'POST', path: '/-/tokens', who: 'person', scope: 'tokens:write', summary: 'Make a personal access token: scoped, expiring (30 days by default); shown once.', body: '{ name, expiresInDays?, scopes? }', answers: '{ token, id, scopes, expiresAt }' },
+    { method: 'DELETE', path: '/-/tokens/{id}', who: 'person', scope: 'tokens:write', summary: 'Revoke one of your tokens.', answers: '{ revoked }' },
+    { method: 'POST', path: '/-/support', who: 'person', scope: 'orgs:write', summary: 'Write to support; an admin may allow support to open the org for a while.', body: '{ category, severity, subject, message, org?, world?, allowAccessDays? }', answers: '{ id, at, emailed, copyTo, access }' },
+    { method: 'POST', path: '/-/operator/sweep-members', who: 'operator', scope: null, summary: 'Revoke, in every org\'s Worlds, the keys (and the branches they made) of people who are no longer members of that org: someone removed at the identity service directly, not through the platform. The clock runs it hourly.', answers: '{ revoked }' },
+    { method: 'POST', path: '/-/meter/tick', who: 'operator', scope: null, summary: 'Run the hourly billing tick now (the clock runs it on its own); 404 where the platform does not bill.', answers: '{ ticked, worlds, inserted, duplicates, restrictions }' },
+    { method: 'POST', path: '/-/backup', who: 'operator', scope: null, summary: 'Archive the platform\'s state to the bucket now (the clock does it nightly).', answers: '{ key, bytes }' },
+    { method: 'GET', path: '/-/backups', who: 'operator', scope: null, summary: 'The archives in the bucket.', answers: '{ keys[] }' },
+    { method: 'POST', path: '/-/restore', who: 'operator', scope: null, summary: 'Restore the platform\'s state from an archive.', body: '{ key }', answers: '{ files }' },
+    { method: 'GET', path: '/-/hosts', who: 'operator', scope: null, summary: 'The hosts enrolled.', answers: '{ hosts[] }' },
+    { method: 'POST', path: '/-/hosts', who: 'operator', scope: null, summary: 'Enroll a host by address: its admin endpoints must answer the token.', body: '{ id, base, adminToken }', answers: '{ id, base }' },
+    { method: 'DELETE', path: '/-/hosts/{id}', who: 'operator', scope: null, summary: 'Stop provisioning onto a host; its worlds stay where they are.', answers: '{ removed }' },
+    { method: 'GET', path: '/-/operator/overview', who: 'operator', scope: null, summary: 'The operator\'s page source: orgs with plan, restriction, worlds, hosts and consents; support requests; the clock.', answers: '{ orgs[], support[], hosts[], clock, notice }' },
+    { method: 'GET', path: '/-/operator/unclaimed', who: 'operator', scope: null, summary: 'The worlds enrolled hosts serve that no org holds (made on a host before the platform, or on the host itself).', answers: '{ worlds: [{ host, name, twins, owner? }] }' },
+    { method: 'POST', path: '/-/operator/claim', who: 'operator', scope: null, summary: 'Claim a world an enrolled host serves into an org whose slug it is served under: without `confirm: true` only when its host already records that org as its owner (slugs are first come), and never when the host records another. The host records the owner; its apps keep their token. Recorded in the org\'s activity.', body: '{ world, org, confirm? }', answers: '{ name, org, host }' },
+    { method: 'POST', path: '/-/operator/open-org', who: 'operator', scope: null, summary: 'A one-hour read-only support session for an org that has allowed it, with a category and a reason; recorded in the org\'s activity.', body: '{ org, category, reason }', answers: '{ token, until, console }' },
+    { method: 'PATCH', path: '/-/operator/support/{id}', who: 'operator', scope: null, summary: 'Close or reopen a support request.', body: '{ status: open | closed }', answers: '{ request }' },
+];
+/** The table as OpenAPI 3.1. */
+export function openapi(origin) {
+    const paths = {};
+    for (const d of DOORS) {
+        const params = [...d.path.matchAll(/\{(\w+)\}/g)].map((m) => ({ name: m[1], in: 'path', required: true, schema: { type: 'string' } }));
+        const op = {
+            summary: d.summary,
+            description: `Who: ${d.who}.${d.scope ? ` A token needs \`${d.scope}\`.` : ''} Answers ${d.answers}.`,
+            security: d.who === 'anyone' ? [] : d.who === 'operator' ? [{ operatorToken: [] }] : [{ session: [] }, { token: d.scope ? [d.scope] : [] }],
+            ...(params.length ? { parameters: params } : {}),
+            ...(d.body ? { requestBody: { required: true, content: { 'application/json': { schema: { type: 'object', description: d.body } } } } } : {}),
+            responses: { '200': { description: d.answers }, ...(d.who !== 'anyone' ? { '401': { description: 'sign in, or the token expired' }, '403': { description: 'not yours, held by the org\'s security, or the token lacks the scope (named)' } } : {}), '429': { description: 'rate limited; Retry-After and X-RateLimit-* say when' } },
+        };
+        (paths[d.path] ??= {})[d.method.toLowerCase()] = op;
+    }
+    return {
+        openapi: '3.1.0',
+        info: { title: 'Volter World platform', version: '1', description: 'The hosted product\'s doors: orgs, worlds, members, billing, tokens, activity, support, and the operator\'s. Every twin\'s vendor API and every world\'s own endpoints are under the world\'s address, documented in the HTTP API reference.' },
+        servers: [{ url: origin }],
+        components: { securitySchemes: { session: { type: 'apiKey', in: 'cookie', name: 'volter_console_session', description: 'a signed-in browser session: the platform\'s own, started by signing in with its access provider' }, token: { type: 'http', scheme: 'bearer', description: 'a personal token (tok_p_), an org token (tok_o_) or a support session (tok_su_), with scopes object:action' }, operatorToken: { type: 'apiKey', in: 'header', name: 'x-volter-token', description: 'the platform\'s operator token' } } },
+        paths,
+    };
+}
+/** The table as the docs page. */
+export function platformApiMarkdown() {
+    const groups = [
+        ['The platform', (d) => /^\/-\/(health|status|openapi|platform$|vendors$)/.test(d.path) || d.path.startsWith('/.well-known/')],
+        ['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')],
+        ['Your tokens and support', (d) => d.path.startsWith('/-/tokens') || d.path === '/-/support'],
+        ['The operator\'s', (d) => d.who === 'operator' && !/^\/-\/status/.test(d.path)],
+    ];
+    const out = ['# Platform API', '', 'The hosted product\'s own endpoints, under `/-/` on the platform\'s address. A twin\'s vendor API and a world\'s own endpoints are under the world\'s address; see [HTTP API](./http-api.md). This page is generated from the endpoint table (`apps/platform/src/doors.ts`); `GET /-/openapi.json` is the same table as OpenAPI, and [platform-openapi.json](./platform-openapi.json) is that document committed, for tools.', '', 'Who opens an endpoint: **anyone**; a **person** signed in, or a token with the scope named; an **admin** of the org; the **operator** with the platform\'s token. A token without the scope is refused with 403 naming it; a held org answers 403 with the reason; everything above the rate limit answers 429 with `Retry-After`. A change made with the browser\x27s session (not a token) must come from the platform\x27s own pages (403 otherwise) with a JSON body (415 otherwise).', ''];
+    // every door is on the page: one no section takes is an error here, never a row quietly left out
+    const left = DOORS.filter((d) => !groups.some(([, pick]) => pick(d)));
+    if (left.length)
+        throw new Error(`doors in no section of the platform API page: ${left.map((d) => `${d.method} ${d.path}`).join(', ')}`);
+    for (const [title, pick] of groups) {
+        out.push(`## ${title}`, '', '| endpoint | who | scope | what it does | body → answer |', '|---|---|---|---|---|');
+        for (const d of DOORS.filter(pick))
+            out.push(`| \`${d.method} ${d.path}\` | ${d.who} | ${d.scope ? `\`${d.scope}\`` : '—'} | ${d.summary} | ${d.body ? `\`${d.body}\` → ` : ''}\`${d.answers}\` |`);
+        out.push('');
+    }
+    return `${out.join('\n')}\n`;
+}