@volter/world-platform 2.0.0

package/src/doors.ts

@@ -0,0 +1,138 @@
+// The doors' table (layer 6): every door the platform answers, declared once — the OpenAPI document
+// (`GET /-/openapi.json`) and docs/reference/platform-api.md are this table rendered, and a drift check
+// holds platform.ts to it (Dub renders its document from its request schemas, Twenty from its metadata,
+// PostHog from its framework; here the table is the code that both routes and documents).
+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 const DOORS: readonly Door[] = [
+  { 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: string): Record<string, unknown> {
+  const paths: Record<string, Record<string, unknown>> = {};
+  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: Record<string, unknown> = {
+      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(): string {
+  const groups: Array<[string, (d: Door) => boolean]> = [
+    ['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`;
+}

package/src/identity.ts

@@ -0,0 +1,279 @@
+// SIGNING IN IS THE ACCESS PROVIDER'S (docs/contributing/architecture.md, "The hosted product"; docs/reference/
+// platform-api.md). A person signs in at the provider's issuer (the authorization code with PKCE) and the platform keeps
+// its own session for them, keyed by the issuer's `subject`, and nothing of the credential. A platform has one provider:
+//
+// - `volter`: Volter Identity. `VOLTER_ISSUER` (https://id.volter.ai by default), `VOLTER_CLIENT_ID` and
+//   `VOLTER_CLIENT_SECRET`, the client the operator registered for this platform. Its directory (directory.ts
+//   volterDirectory) is the service's, reached through its product door with this client's `client_credentials`
+//   token for `<issuer>/organizations` (volter-ai/identity ADR-0002). In a World the Volter identity twin is the
+//   issuer and the drive registers the client.
+// - `oidc`: any OpenID Connect issuer (Google, Microsoft Entra, Okta, Keycloak): `OIDC_ISSUER`, `OIDC_CLIENT_ID`,
+//   `OIDC_CLIENT_SECRET` and optionally `OIDC_NAME` (what the sign-in button says) and `OIDC_TRUST_EMAIL_DOMAINS` (the
+//   domains the issuer's organization owns and verified: an address in one counts as verified where the issuer sends
+//   no `email_verified`, as Entra does, so invitations can match it; any other address never does). It only signs people in; the
+//   platform keeps the directory itself (directory.ts localDirectory).
+// - `github`: GitHub, whose OAuth apps are OAuth 2.0 without OpenID Connect: `GITHUB_CLIENT_ID` and
+//   `GITHUB_CLIENT_SECRET`, and for GitHub Enterprise Server `GITHUB_URL` (its web address) and `GITHUB_API_URL`
+//   (`<GITHUB_URL>/api/v3`). The person is `GET /user` and their primary verified address `GET /user/emails`, read
+//   once with the token the code bought; the subject is `github:<numeric id>`, which a rename does not change.
+//   Sign-in only; the platform keeps the directory, as for `oidc`.
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { eq, lte } from 'drizzle-orm';
+import { openDatabase, type PlatformDb } from './db/open.ts';
+import { sessions as sessionRows } from './db/schema.ts';
+import { resolveIdentity, verifyIdentityToken, type OpenIdMetadata } from '@volter/identity';
+import type { SignedInPerson } from './directory.ts';
+
+/** The Volter provider's settings (each from its `VOLTER_*` name when absent). */
+export type IdentityOptions = { issuer?: string; clientId?: string; clientSecret?: string };
+/** The access provider a platform signs people in with. */
+export type ProviderOptions = ({ kind: 'volter' } & IdentityOptions) | { kind: 'oidc'; issuer?: string; clientId?: string; clientSecret?: string; name?: string; /** the domains the issuer's organization owns and verified: an address in one counts as verified though the issuer sends no `email_verified` (Entra) */ trustEmailDomains?: string[] } | { kind: 'github'; clientId?: string; clientSecret?: string; /** GitHub's web address (GitHub Enterprise Server's); https://github.com by default */ web?: string; /** its REST API; https://api.github.com by default, `<web>/api/v3` for an Enterprise Server */ api?: string };
+
+/** The platform's client at its provider: who it is there, and (Volter) a call through the product door. */
+export type Identity = {
+  kind: 'volter' | 'oidc' | 'github';
+  /** What a person is told they continue with: "Volter", "Google", the operator's name for their issuer. */
+  name: string;
+  issuer: string;
+  clientId: string;
+  clientSecret: string;
+  /** The person's own account page at the provider, when it has one. */
+  account?: string;
+  /** The issuer's discovery document (cached by `@volter/identity`; a failure is asked again). */
+  metadata: () => Promise<OpenIdMetadata>;
+  /** A product-door call with the platform's organizations token (Volter only); 404 answers null, any other refusal throws its words. */
+  call: <T>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, body?: unknown) => Promise<T | null>;
+  /** GitHub's web and API addresses, for the `github` provider. */
+  github?: { web: string; api: string };
+  /** The domains the operator says the issuer's organization owns (OIDC_TRUST_EMAIL_DOMAINS): an address in one, with no `email_verified`, counts as verified. */
+  trustEmailDomains?: string[];
+};
+
+/** The provider's name from its issuer, for the issuers people know by name. */
+const nameOf = (issuer: string): string => {
+  const host = (() => { try { return new URL(issuer).hostname; } catch { return issuer; } })();
+  if (host === 'accounts.google.com') return 'Google';
+  if (host === 'login.microsoftonline.com') return 'Microsoft';
+  if (/\.okta\.com$/.test(host)) return 'Okta';
+  return host;
+};
+
+export function providerClient(opts: ProviderOptions): Identity {
+  if (opts.kind === 'github') return githubClient(opts);
+  const volter = opts.kind === 'volter';
+  const env = (name: string): string | undefined => process.env[`${volter ? 'VOLTER' : 'OIDC'}_${name}`];
+  const issuer = (opts.issuer || env('ISSUER') || (volter ? 'https://id.volter.ai' : '')).replace(/\/+$/, '');
+  const clientId = opts.clientId ?? env('CLIENT_ID');
+  const clientSecret = opts.clientSecret ?? env('CLIENT_SECRET');
+  if (!issuer) throw new Error('no OpenID Connect issuer: set OIDC_ISSUER (https://accounts.google.com, your Entra or Okta issuer…)');
+  if (!clientId || !clientSecret) throw new Error(volter ? 'no Volter identity client: set VOLTER_CLIENT_ID and VOLTER_CLIENT_SECRET, the client registered for this platform at the identity service (VOLTER_ISSUER)' : `no client at ${issuer}: set OIDC_CLIENT_ID and OIDC_CLIENT_SECRET, the client registered for this platform there`);
+  const metadata = async (): Promise<OpenIdMetadata> => {
+    const known = await resolveIdentity(issuer);
+    const found = known.available ? known : await resolveIdentity(issuer, { fresh: true });
+    if (!found.available) throw new Error(found.reason);
+    return found.metadata;
+  };
+  // the organizations token (RFC 6749 §4.4), kept until a minute before it expires
+  let held: { token: string; until: number } | null = null;
+  const organizationsToken = async (): Promise<string> => {
+    if (held && Date.now() < held.until) return held.token;
+    const { token_endpoint } = await metadata();
+    const res = await fetch(token_endpoint, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+      body: new URLSearchParams({ grant_type: 'client_credentials', client_id: clientId, client_secret: clientSecret, scope: 'organizations', resource: `${issuer}/organizations` }).toString(),
+    });
+    const body = (await res.json().catch(() => ({}))) as { access_token?: string; expires_in?: number; error?: string; error_description?: string };
+    if (!res.ok || !body.access_token) throw new Error(`the identity service refused the platform's organizations token: ${body.error_description ?? body.error ?? res.status}`);
+    held = { token: body.access_token, until: Date.now() + Math.max(0, (body.expires_in ?? 3600) - 60) * 1000 };
+    return held.token;
+  };
+  const call = async <T>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, body?: unknown): Promise<T | null> => {
+    if (!volter) throw new Error('an OpenID Connect provider has no product door: the platform keeps the directory');
+    const res = await fetch(`${issuer}${path}`, { method, headers: { authorization: `Bearer ${await organizationsToken()}`, accept: 'application/json', ...(body === undefined ? {} : { 'content-type': 'application/json' }) }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
+    if (res.status === 404) return null;
+    const answer = (await res.json().catch(() => ({}))) as T & { error?: string };
+    if (!res.ok) throw new Error(answer.error ?? `the identity service answered ${res.status}`);
+    return answer;
+  };
+  const name = volter ? 'Volter' : (opts.name || env('NAME') || nameOf(issuer));
+  // only the domains the operator names, never every address: a tenant's admins can set any address on a user (nOAuth)
+  const trustEmailDomains = volter ? [] : ((opts.kind === 'oidc' ? opts.trustEmailDomains : undefined) ?? (env('TRUST_EMAIL_DOMAINS') ?? '').split(',')).map((d) => d.trim().toLowerCase().replace(/^@/, '')).filter((d) => /^[a-z0-9.-]+\.[a-z]{2,}$/.test(d));
+  return { kind: opts.kind, name, issuer, clientId, clientSecret, ...(volter ? { account: `${issuer}/` } : {}), ...(trustEmailDomains.length ? { trustEmailDomains } : {}), metadata, call };
+}
+
+/** GitHub as the provider: OAuth 2.0 at its web address, the person read from its REST API. */
+function githubClient(opts: Extract<ProviderOptions, { kind: 'github' }>): Identity {
+  // https, or http only on this machine: the client secret, the code and the person's token cross it
+  const url = (value: string, name: string): string => { let u: URL; try { u = new URL(value); } catch { throw new Error(`${name} is not an address: ${JSON.stringify(value)}`); } const local = u.hostname === 'localhost' || u.hostname.endsWith('.localhost') || u.hostname === '127.0.0.1' || u.hostname === '[::1]'; if (u.protocol !== 'https:' && !(u.protocol === 'http:' && local)) throw new Error(`${name} must be https (or http on this machine): ${JSON.stringify(value)}`); return value.replace(/\/+$/, ''); };
+  const web = url(opts.web || process.env.GITHUB_URL || 'https://github.com', 'GITHUB_URL');
+  const api = url(opts.api || process.env.GITHUB_API_URL || (web === 'https://github.com' ? 'https://api.github.com' : `${web}/api/v3`), 'GITHUB_API_URL');
+  const clientId = opts.clientId ?? process.env.GITHUB_CLIENT_ID;
+  const clientSecret = opts.clientSecret ?? process.env.GITHUB_CLIENT_SECRET;
+  if (!clientId || !clientSecret) throw new Error('no GitHub OAuth app: set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET, the OAuth app registered for this platform (its callback URL <platform>/-/sign-in/callback)');
+  const none = (): never => { throw new Error('GitHub is not an OpenID Connect issuer'); };
+  return { kind: 'github', name: 'GitHub', issuer: web, clientId, clientSecret, account: `${web}/settings/profile`, metadata: async () => none(), call: async () => none(), github: { web, api } };
+}
+
+/** The Volter provider (the settings, else the `VOLTER_*` names). */
+export const identityClient = (opts: IdentityOptions = {}): Identity => providerClient({ kind: 'volter', ...opts });
+
+// ── the platform's own session: a random id in an HttpOnly cookie, the record beside the tokens ──
+export const SESSION_COOKIE = 'volter_console_session';
+const STATE_COOKIE = 'volter_console_sign_in';
+const SESSION_SECONDS = 8 * 60 * 60;
+const STATE_SECONDS = 10 * 60;
+export const CALLBACK_PATH = '/-/sign-in/callback';
+
+export type SessionRecord = { subject: string; email?: string; name?: string; expiresAt: string };
+
+/** The platform's sessions, by the SHA-256 of the cookie's id, in its database (in memory when it keeps no state). */
+export class Sessions {
+  private readonly db: PlatformDb;
+  constructor(stateDir?: string) { this.db = openDatabase(stateDir); }
+  private key(sessionId: string): string { return createHash('sha256').update(sessionId).digest('hex'); }
+  start(person: { subject: string; email?: string; name?: string }): string {
+    const sessionId = randomBytes(32).toString('base64url');
+    const now = Date.now();
+    // the expired go as new ones start: the table holds live sessions, not a history
+    this.db.delete(sessionRows).where(lte(sessionRows.expiresAt, new Date(now).toISOString())).run();
+    this.db.insert(sessionRows).values({ idHash: this.key(sessionId), subject: person.subject, email: person.email ?? null, name: person.name ?? null, expiresAt: new Date(now + SESSION_SECONDS * 1000).toISOString() }).run();
+    return sessionId;
+  }
+  read(sessionId: string): SessionRecord | null {
+    const r = this.db.select().from(sessionRows).where(eq(sessionRows.idHash, this.key(sessionId))).get() as (typeof sessionRows.$inferSelect) | undefined;
+    if (!r) return null;
+    if (Date.parse(r.expiresAt) <= Date.now()) { this.end(sessionId); return null; }
+    return { subject: r.subject, ...(r.email ? { email: r.email } : {}), ...(r.name ? { name: r.name } : {}), expiresAt: r.expiresAt };
+  }
+  end(sessionId: string): void { this.db.delete(sessionRows).where(eq(sessionRows.idHash, this.key(sessionId))).run(); }
+}
+
+const cookieOf = (request: Request, name: string): string | undefined => {
+  for (const part of (request.headers.get('cookie') ?? '').split(';')) { const [k, ...v] = part.trim().split('='); if (k === name) return v.join('='); }
+  return undefined;
+};
+// over https a cookie is `__Host-`: set only by this origin, never by a sibling page on the same site (a World origin
+// under the same registrable domain cannot toss a session or a sign-in state of its own over the platform's)
+const cookieName = (origin: string, base: string): string => (origin.startsWith('https:') ? `__Host-${base}` : base);
+const cookie = (origin: string, name: string, value: string, _path: string, seconds: number): string => `${cookieName(origin, name)}=${value}; Path=/; HttpOnly; SameSite=Lax; Max-Age=${seconds}${origin.startsWith('https:') ? '; Secure' : ''}`;
+export const sessionIdOf = (request: Request, origin: string): string | undefined => cookieOf(request, cookieName(origin, SESSION_COOKIE));
+
+export type Signed = { userId: string; sessionId: string; email?: string; name?: string };
+
+/** Who a request is: the platform's session its cookie names, while it lasts. */
+export function whoIs(sessions: Sessions, request: Request, origin: string): Signed | null {
+  const sessionId = sessionIdOf(request, origin);
+  if (!sessionId) return null;
+  const s = sessions.read(sessionId);
+  return s ? { userId: s.subject, sessionId, ...(s.email ? { email: s.email } : {}), ...(s.name ? { name: s.name } : {}) } : null;
+}
+
+// the sign-in state (the state and the PKCE verifier) rides a short-lived cookie signed with the client secret
+const sign = (identity: Identity, payload: object): string => { const body = Buffer.from(JSON.stringify(payload)).toString('base64url'); return `${body}.${createHmac('sha256', identity.clientSecret).update(body).digest('base64url')}`; };
+const unsign = <T>(identity: Identity, value: string | undefined): T | null => {
+  if (!value) return null;
+  const [body, mac, extra] = value.split('.');
+  if (!body || !mac || extra !== undefined) return null;
+  const want = Buffer.from(createHmac('sha256', identity.clientSecret).update(body).digest('base64url')); const got = Buffer.from(mac);
+  if (want.length !== got.length || !timingSafeEqual(want, got)) return null;
+  try { const p = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as T & { exp?: number }; return typeof p.exp === 'number' && p.exp > Date.now() / 1000 ? p : null; } catch { return null; }
+};
+const text = (body: string, status: number): Response => new Response(body, { status, headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' } });
+
+/** Where a sign-in may return a person: a path of this platform (its pages, or `/-/…`), never another origin or a scheme. */
+export const signInReturn = (next: string | null | undefined): string | undefined => (next && /^\/(?![/\\])[A-Za-z0-9/_?=&%.~-]*$/.test(next) ? next : undefined);
+/** Start signing in: the authorization code with PKCE (S256) at the provider. */
+export async function beginSignIn(identity: Identity, origin: string, next?: string): Promise<Response> {
+  let authorize: string;
+  if (identity.github) authorize = `${identity.github.web}/login/oauth/authorize`;
+  else { try { authorize = (await identity.metadata()).authorization_endpoint; } catch (e) { return text(`Signing in is unavailable: ${(e as Error).message}`, 503); } }
+  const state = randomBytes(16).toString('base64url');
+  const verifier = randomBytes(48).toString('base64url');
+  const challenge = createHash('sha256').update(verifier).digest('base64url');
+  const target = new URL(authorize);
+  // GitHub: the profile and the addresses, nothing of the person's repositories
+  const asked: Record<string, string> = identity.github ? { scope: 'read:user user:email', allow_signup: 'true' } : { response_type: 'code', scope: 'openid profile email' };
+  target.search = new URLSearchParams({ client_id: identity.clientId, redirect_uri: `${origin}${CALLBACK_PATH}`, ...asked, state, code_challenge: challenge, code_challenge_method: 'S256' }).toString();
+  const back = signInReturn(next);
+  const pending = sign(identity, { state, verifier, exp: Math.floor(Date.now() / 1000) + STATE_SECONDS, ...(back ? { next: back } : {}) });
+  return new Response(null, { status: 302, headers: { location: target.toString(), 'cache-control': 'no-store', 'set-cookie': cookie(origin, STATE_COOKIE, pending, CALLBACK_PATH, STATE_SECONDS) } });
+}
+
+/** The issuer's answer: the code traded with the client secret, the id token verified, the session started. */
+export async function finishSignIn(identity: Identity, sessions: Sessions, origin: string, request: Request, landing: string, seen?: (person: SignedInPerson) => Promise<void>): Promise<Response> {
+  const url = new URL(request.url);
+  const expected = unsign<{ state: string; verifier: string; next?: string }>(identity, cookieOf(request, cookieName(origin, STATE_COOKIE)));
+  const supplied = url.searchParams.get('state') ?? '';
+  if (!expected || !supplied || supplied.length !== expected.state.length || !timingSafeEqual(Buffer.from(supplied), Buffer.from(expected.state))) return text('Sign-in refused: the sign-in expired or did not start here. Sign in again.', 401);
+  if (url.searchParams.get('error')) return text(`Sign-in did not complete: ${url.searchParams.get('error_description') ?? url.searchParams.get('error')}`, 401);
+  const code = url.searchParams.get('code');
+  if (!code) return text('Sign-in did not complete.', 401);
+  const person = identity.github ? await githubPerson(identity, identity.github, origin, code, expected.verifier) : await oidcPerson(identity, origin, code, expected.verifier);
+  if (person instanceof Response) return person;
+  // the directory knows the person before their session opens: an invitation to their address lets them in now
+  if (seen) { try { await seen(person); } catch (e) { return text(`Signing in is unavailable: ${(e as Error).message}`, 503); } }
+  const sessionId = sessions.start({ subject: person.subject, ...(person.email ? { email: person.email } : {}), ...(person.name ? { name: person.name } : {}) });
+  const headers = new Headers({ location: signInReturn(expected.next) ?? landing, 'cache-control': 'no-store' });
+  headers.append('set-cookie', cookie(origin, SESSION_COOKIE, sessionId, '/', SESSION_SECONDS));
+  headers.append('set-cookie', cookie(origin, STATE_COOKIE, '', CALLBACK_PATH, 0));
+  return new Response(null, { status: 302, headers });
+}
+
+/** An OpenID Connect provider's answer: the code traded with the client secret, the id token verified. */
+async function oidcPerson(identity: Identity, origin: string, code: string, verifier: string): Promise<SignedInPerson | Response> {
+  let meta: OpenIdMetadata;
+  try { meta = await identity.metadata(); } catch (e) { return text(`Signing in is unavailable: ${(e as Error).message}`, 503); }
+  const res = await fetch(meta.token_endpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+    body: new URLSearchParams({ grant_type: 'authorization_code', code, code_verifier: verifier, redirect_uri: `${origin}${CALLBACK_PATH}`, client_id: identity.clientId, client_secret: identity.clientSecret }).toString(),
+  });
+  const tokens = (await res.json().catch(() => ({}))) as { id_token?: string; access_token?: string };
+  if (!res.ok || !tokens.id_token) return text('Sign-in refused: the authorization code was not accepted.', 401);
+  let person;
+  try { person = await verifyIdentityToken(tokens.id_token, { issuer: identity.issuer, audience: identity.clientId }); } catch { return text('Sign-in refused: the identity token did not verify.', 401); }
+  // the id token names the person; their email and name, when it does not carry them, are the userinfo's (the scopes granted them)
+  let known: { email?: string; email_verified?: boolean; name?: string; sub?: string } = {};
+  if ((!person.email || !person.name) && tokens.access_token && meta.userinfo_endpoint) {
+    const info = await fetch(meta.userinfo_endpoint, { headers: { authorization: `Bearer ${tokens.access_token}`, accept: 'application/json' } }).catch(() => null);
+    if (info?.ok) known = (await info.json().catch(() => ({}))) as typeof known;
+    if (known.sub !== person.subject) known = {};
+  }
+  const email = person.email ?? known.email; const name = person.name ?? known.name;
+  // whether the provider vouches for the address: the one that says it (the id token for its own email, else the userinfo)
+  // an issuer that says nothing about an address vouches for it only in a domain its operator named (OIDC_TRUST_EMAIL_DOMAINS)
+  const said = person.email ? person.emailVerified : known.email_verified;
+  const domain = (email ?? '').split('@')[1]?.toLowerCase() ?? '';
+  const emailVerified = said === true || (said === undefined && domain !== '' && (identity.trustEmailDomains ?? []).includes(domain));
+  return { subject: person.subject, ...(email ? { email } : {}), emailVerified, ...(name ? { name } : {}) };
+}
+
+/** GitHub's answer: the code traded for a token (JSON asked for; GitHub's default answer is a form), then the person
+ *  and their primary verified address read with it. The token is used for these two reads and kept nowhere. */
+async function githubPerson(identity: Identity, gh: { web: string; api: string }, origin: string, code: string, verifier: string): Promise<SignedInPerson | Response> {
+  const res = await fetch(`${gh.web}/login/oauth/access_token`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' },
+    body: new URLSearchParams({ client_id: identity.clientId, client_secret: identity.clientSecret, code, code_verifier: verifier, redirect_uri: `${origin}${CALLBACK_PATH}` }).toString(),
+  }).catch(() => null);
+  const token = (await res?.json().catch(() => ({})) ?? {}) as { access_token?: string; error?: string; error_description?: string };
+  if (!res?.ok || !token.access_token) return text(`Sign-in refused: GitHub did not accept the code${token.error_description ? ` (${token.error_description})` : ''}.`, 401);
+  const read = async <T>(path: string): Promise<T | null> => {
+    const r = await fetch(`${gh.api}${path}`, { headers: { authorization: `Bearer ${token.access_token}`, accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'user-agent': 'volter-world-platform' } }).catch(() => null);
+    return r?.ok ? ((await r.json().catch(() => null)) as T | null) : null;
+  };
+  const user = await read<{ id?: number; login?: string; name?: string | null }>('/user');
+  if (!user || typeof user.id !== 'number') return text('Sign-in refused: GitHub did not say who signed in.', 401);
+  // the primary address only when GitHub has verified it: an unverified one could be anyone's
+  const emails = (await read<Array<{ email: string; primary: boolean; verified: boolean }>>('/user/emails')) ?? [];
+  const primary = emails.find((e) => e.primary && e.verified) ?? emails.find((e) => e.verified);
+  return { subject: `github:${user.id}`, ...(primary ? { email: primary.email, emailVerified: true } : {}), ...(user.name || user.login ? { name: user.name || user.login! } : {}) };
+}
+
+/** Sign out: the platform's session ends and its cookie goes. */
+export function endSession(sessions: Sessions, origin: string, request: Request, landing: string): Response {
+  const sessionId = sessionIdOf(request, origin);
+  if (sessionId) sessions.end(sessionId);
+  return new Response(null, { status: 302, headers: { location: landing, 'cache-control': 'no-store', 'set-cookie': cookie(origin, SESSION_COOKIE, '', '/', 0) } });
+}

package/src/labs.ts

@@ -0,0 +1,8 @@
+// Labs: the early-access features an org turns on (platform.ts, `/-/orgs/<org>/labs`).
+/** Early-access features (layer 8: Twenty's lab of public flags with a title and a description, Sentry's Early Adopter switch,
+ *  Cal.com's opt-in features). A new surface lands here first; an org turns it on, or turns on everything with Early adopter. */
+export const EARLY_FEATURES = [
+  { key: 'webhooks', name: 'Webhooks', description: 'Events the org raises — a world provisioned, a member added, the plan changed — sent to an address of yours, signed.', since: '2026-09-08' },
+  { key: 'usage_by_day', name: 'Usage by day', description: 'A bar per day of the period, under the org\'s meters.', since: '2026-09-08' },
+] as const;
+export type EarlyFeatureKey = (typeof EARLY_FEATURES)[number]['key'];

package/src/mail.ts

@@ -0,0 +1,27 @@
+// The platform's own mail (punchlist 3.6): what the identity service and Polar do not send (an
+// invitation is the identity service's mail, and a receipt Polar's) — a member added, a
+// world deleted, the quota warning, the grace notice. Resend's UNMODIFIED SDK through the world's
+// boundary: the resend twin in rehearsal (its inbox mirror shows every mail), real Resend in
+// production with a verified sending domain (OWNER: the domain). No RESEND_API_KEY → the mail is
+// written to the log, never invented.
+import { Resend } from 'resend';
+
+export type Mail = { to: string[]; subject: string; text: string };
+export type Mailer = { send: (mail: Mail) => Promise<{ id: string | null }>; from: string };
+
+export function mailer(opts: { apiKey?: string; from?: string; log?: (line: string) => void } = {}): Mailer {
+  const from = opts.from ?? 'Volter World <noreply@volter.world>'; // --mail-from names another sender
+  const key = opts.apiKey ?? process.env.RESEND_API_KEY;
+  const log = opts.log ?? ((line: string) => process.stdout.write(`${line}\n`));
+  if (!key) return { from, send: async (mail) => { log(`mail (no RESEND_API_KEY, not sent)  to ${mail.to.join(', ')}  ${mail.subject}`); return { id: null }; } };
+  const resend = new Resend(key);
+  return {
+    from,
+    send: async (mail) => {
+      const { data, error } = await resend.emails.send({ from, to: mail.to, subject: mail.subject, text: mail.text });
+      if (error) { log(`mail failed  to ${mail.to.join(', ')}  ${mail.subject}: ${error.message}`); return { id: null }; }
+      log(`mail sent  to ${mail.to.join(', ')}  ${mail.subject}  ${data?.id ?? ''}`);
+      return { id: data?.id ?? null };
+    },
+  };
+}

package/src/pages.ts

@@ -0,0 +1,69 @@
+// THE PLATFORM'S PAGES as the platform serves them (docs/contributing/architecture.md, "The hosted product"): one React
+// client (client/platform.tsx) behind one shell at the root of the platform's origin — `/`, `/<org>`, `/<org>/members`,
+// `/account`… — its bundle and styles under `/-/`, and a card page for what is served without the client (the command's
+// approval, a refusal). The styles are the kit's (@volter/world-console, the dashboard's package) then the platform's
+// own, so the platform and a World's pages read as one product. No third-party script is ever served here: the site's
+// tags stay on the site.
+import { readFileSync } from 'node:fs';
+import { bundleClient } from '@volter/world-core';
+import { brandAsset, kitCss, WORLD_LOGO } from '@volter/world-console';
+import { RESERVED_ORG_NAMES } from '../client/reserved.ts';
+
+export { RESERVED_ORG_NAMES };
+
+/** A file URL's path as the filesystem names it: decoded, and without the leading slash before a Windows drive (`/C:/…`). */
+const pathOf = (url: URL): string => decodeURIComponent(url.pathname).replace(/^\/([A-Za-z]:)/, '$1');
+const CLIENT_ENTRY = () => pathOf(new URL('../client/platform.tsx', import.meta.url)); // lazy: never a top-level import.meta.url URL
+const CLIENT_CSS = () => pathOf(new URL('../client/platform.css', import.meta.url));
+const attr = (v: string): string => v.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const HEAD = (title: string): string => `<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${attr(title)}</title><link rel="icon" type="image/svg+xml" href="${WORLD_LOGO}"><link rel="stylesheet" href="/-/brand/tokens.css"><link rel="stylesheet" href="/-/styles.css">`;
+const SHELL_CSP = "default-src 'self'; img-src 'self' data: https://brand.volter.ai; style-src 'self' 'unsafe-inline'; font-src 'self'; script-src 'self'; connect-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'";
+
+/** The catalog's vendors, most used first, for the page's vendor picker: `vendor:s` for a supported twin, `vendor:p` for a
+ *  preview. Read once from the repo's generated index (generated/index.json) where it is beside the platform; elsewhere
+ *  the page offers its short list and takes any name typed. */
+let catalog: string | null = null;
+const vendors = (): string => {
+  if (catalog !== null) return catalog;
+  try {
+    const index = JSON.parse(readFileSync(pathOf(new URL('../../../generated/index.json', import.meta.url)), 'utf8')) as { rows: Array<{ rank: number; vendor: string; exists: boolean; status?: string }> };
+    catalog = index.rows.filter((r) => r.exists && /^[a-z0-9-]+$/.test(r.vendor)).sort((a, b) => a.rank - b.rank).map((r) => `${r.vendor}:${r.status === 'Supported' ? 's' : 'p'}`).join(',');
+  } catch { catalog = ''; }
+  return catalog;
+};
+
+/** The operator's consented support view is opened with its token in the address (`/?support=tok_su_…`): only a
+ *  support token's shape is carried into the page, and only as an attribute. */
+const SUPPORT_TOKEN = /^tok_su_[A-Za-z0-9_-]{16,128}$/;
+
+export type Pages = { handle: (request: Request) => Promise<Response | null> };
+
+/** The platform's pages: `GET /-/app.js` (the client), `GET /-/styles.css` (the kit's, then the platform's),
+ *  `GET /-/brand/*` (the brand's tokens and faces) and the shell for any other GET outside `/-/` and `/.well-known/`;
+ *  null for anything else, which is a door's. */
+export function createPages(): Pages {
+  return {
+    async handle(request) {
+      if (request.method !== 'GET' && request.method !== 'HEAD') return null;
+      const url = new URL(request.url);
+      const path = url.pathname;
+      if (path === '/-/app.js') {
+        try { return new Response(await bundleClient(CLIENT_ENTRY()), { headers: { 'content-type': 'text/javascript; charset=utf-8', 'cache-control': 'no-cache' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (path === '/-/styles.css') return new Response(`${kitCss()}\n${readFileSync(CLIENT_CSS(), 'utf8')}`, { headers: { 'content-type': 'text/css; charset=utf-8', 'cache-control': 'no-cache' } });
+      if (path.startsWith('/-/brand/')) return brandAsset(path.slice('/-/brand/'.length));
+      if (path.startsWith('/-/') || path === '/-' || path.startsWith('/.well-known/')) return null;
+      const support = url.searchParams.get('support') ?? '';
+      const token = SUPPORT_TOKEN.test(support) ? ` data-token="${attr(support)}"` : '';
+      return new Response(`<!doctype html>\n<html lang="en"><head>${HEAD('Volter World')}</head><body><div id="root"${token} data-vendors="${attr(vendors())}"></div><script type="module" src="/-/app.js"></script></body></html>`, { headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer', 'content-security-policy': SHELL_CSP } });
+    },
+  };
+}
+
+/** A page that is one card, rendered on the server with the kit's styles: the command's approval, a refusal, a notice.
+ *  `inner` is HTML the caller has escaped. `csp` replaces the default policy (no script at all). */
+export function pageShell(title: string, inner: string, opts: { csp?: string; status?: number } = {}): Response {
+  const html = `<!doctype html>\n<html lang="en"><head>${HEAD(title)}</head><body class="portal"><main class="card"><p class="brand"><img src="${WORLD_LOGO}" alt="" width="22" height="22"> Volter World</p>${inner}</main></body></html>`;
+  return new Response(html, { status: opts.status ?? 200, headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': opts.csp ?? "default-src 'self'; img-src 'self' https://brand.volter.ai; style-src 'self' 'unsafe-inline'; font-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'" } });
+}