@volter/world-platform 2.0.0

package/dist/src/webhooks.js

@@ -0,0 +1,92 @@
+// Webhooks out (layer 7) — the peers' shape, read in their code (HOSTED-PRODUCT-COMPLETENESS.md,
+// "webhooks out"): an endpoint is a URL, a secret shown once and the events it wants (Dub, Cal.com,
+// Twenty); events are `object.verb` with a `{ id, event, createdAt, data }` body (Dub); deliveries are
+// signed with Standard Webhooks (Polar: webhook-id, webhook-timestamp, webhook-signature), retried
+// with backoff up to ten attempts (Polar's WEBHOOK_MAX_RETRIES) and kept with their response; twenty
+// consecutive failures disable the endpoint and the admins are emailed (Dub's threshold).
+import { createHmac, randomBytes } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+/** The catalog: the audit's events in dotted form, plus `ping` for the test button. */
+export const WEBHOOK_EVENTS = {
+    WORLD_PROVISION: 'world.provisioned', WORLD_DELETE: 'world.deleted', PREVIEW_CREATE: 'preview.created', PREVIEW_DELETE: 'preview.deleted',
+    MEMBER_INVITE: 'member.added', INVITE_REVOKE: 'member.invite_revoked', MEMBER_REMOVE: 'member.removed', MEMBER_ROLE: 'member.role_changed',
+    ORG_RENAME: 'org.renamed', PLAN_CHANGE: 'plan.changed',
+    QUOTA_WARNED: 'quota.warned', QUOTA_RESTRICTED: 'quota.restricted', QUOTA_CLEARED: 'quota.cleared',
+    IMPERSONATION: 'support.opened',
+};
+export const WEBHOOK_EVENT_NAMES = [...new Set(Object.values(WEBHOOK_EVENTS))].sort();
+export const eventNameFor = (audit) => WEBHOOK_EVENTS[audit] ?? null;
+export function validEvents(events) { return Array.isArray(events) && events.length > 0 && events.every((e) => typeof e === 'string' && (WEBHOOK_EVENT_NAMES.includes(e) || e === '*')); }
+export const MAX_ATTEMPTS = 10;
+export const DISABLE_AFTER = 20;
+/** Seconds until the next attempt after attempt n (1-based): 30 s, 2 min, 10 min, then 20 min (Polar's cap). */
+export const backoffSeconds = (attempt) => [30, 120, 600][attempt - 1] ?? 1200;
+export const newSecret = () => `whsec_${randomBytes(24).toString('base64')}`;
+export const newId = (prefix) => `${prefix}_${randomBytes(8).toString('hex')}`;
+/** Standard Webhooks: HMAC-SHA256 over `id.timestamp.body` with the secret's base64 decoded, sent as `v1,<base64>`. */
+export function sign(secret, id, timestamp, body) {
+    const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
+    return `v1,${createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest('base64')}`;
+}
+/** What a receiver does: recompute and compare (constant time). */
+export function verify(secret, headers, body, toleranceSeconds = 300) {
+    const ts = Number(headers.timestamp);
+    if (!Number.isFinite(ts) || Math.abs(Date.now() / 1000 - ts) > toleranceSeconds)
+        return false;
+    const expected = sign(secret, headers.id, ts, body).slice(3);
+    return headers.signature.split(' ').some((part) => { const [v, sig] = part.split(','); if (v !== 'v1' || !sig)
+        return false; const a = Buffer.from(sig, 'base64'); const b = Buffer.from(expected, 'base64'); return a.length === b.length && a.equals(b); });
+}
+/** Whether an address is this machine's, a private network's, link-local or carrier-grade NAT: never a webhook's target. */
+export function privateAddress(ip) {
+    const v4 = /^(?:::ffff:)?(\d+)\.(\d+)\.(\d+)\.(\d+)$/.exec(ip);
+    if (v4) {
+        const [a, b] = [Number(v4[1]), Number(v4[2])];
+        return a === 0 || a === 10 || a === 127 || (a === 100 && b >= 64 && b <= 127) || (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || a >= 224;
+    }
+    const v6 = ip.toLowerCase();
+    return v6 === '::' || v6 === '::1' || v6.startsWith('fc') || v6.startsWith('fd') || v6.startsWith('fe8') || v6.startsWith('fe9') || v6.startsWith('fea') || v6.startsWith('feb');
+}
+/** Why an endpoint may not be delivered to (its name resolves to an address inside a network), or null. A platform may
+ *  deliver inside its own network only where its operator allows it (VOLTER_WEBHOOKS_ALLOW_PRIVATE=1, or a local run). */
+export async function refusedEndpoint(url, allowPrivate) {
+    if (allowPrivate)
+        return null;
+    let host;
+    try {
+        host = new URL(url).hostname.replace(/^\[|\]$/g, '');
+    }
+    catch {
+        return 'not an address';
+    }
+    let addresses;
+    try {
+        addresses = (await lookup(host, { all: true })).map((a) => a.address);
+    }
+    catch {
+        return `${host} does not resolve`;
+    }
+    const inside = addresses.find(privateAddress);
+    return inside ? `${host} resolves to ${inside}, inside a network: a webhook goes to a public address` : null;
+}
+/** One attempt at one delivery; the caller keeps the record. Redirects are not followed (a public name answering with an
+ *  inside address would carry the event there). */
+export async function attempt(endpoint, d, fetchImpl = fetch, allowPrivate = false) {
+    const refused = await refusedEndpoint(endpoint.url, allowPrivate);
+    if (refused)
+        return { status: null, ok: false, response: refused };
+    const timestamp = Math.floor(Date.now() / 1000);
+    const c = new AbortController();
+    const t = setTimeout(() => c.abort(), 10_000);
+    try {
+        const r = await fetchImpl(endpoint.url, { method: 'POST', headers: { 'content-type': 'application/json', 'user-agent': 'volter-world webhooks', 'webhook-id': d.eventId, 'webhook-timestamp': String(timestamp), 'webhook-signature': sign(endpoint.secret, d.eventId, timestamp, d.body) }, body: d.body, signal: c.signal, redirect: 'manual' });
+        const text = (await r.text().catch(() => '')).slice(0, 2048);
+        return { status: r.status, ok: r.ok, response: r.status >= 300 && r.status < 400 ? `a redirect (${r.status}), not followed` : text };
+    }
+    catch (e) {
+        return { status: null, ok: false, response: String(e.message ?? e).slice(0, 2048) };
+    }
+    finally {
+        clearTimeout(t);
+    }
+}

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@volter/world-platform",
+  "version": "2.0.0",
+  "description": "The Volter World platform: people and orgs through an access provider (Volter Identity, GitHub, or any OpenID Connect issuer), members and invitations, tokens, Worlds made on enrolled hosts, and opening a World for a person with a pass. Open and self-hostable; serves its own pages and never a twin.",
+  "keywords": [
+    "volter",
+    "world",
+    "platform",
+    "orgs",
+    "oidc",
+    "self-hosted"
+  ],
+  "author": "Volter (https://github.com/volter-ai)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.13"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/platform.d.ts",
+      "default": "./dist/src/platform.js"
+    }
+  },
+  "bin": {
+    "volter-platform": "dist/src/cli.js"
+  },
+  "scripts": {
+    "test": "bun test src/*.uitest.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/publish/build.mjs",
+    "prepack": "node ../../scripts/publish/prepare-publish.mjs prepack",
+    "postpack": "node ../../scripts/publish/prepare-publish.mjs postpack"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1081.0",
+    "@volter/identity": "^0.1.0",
+    "@volter/world-access": "2.0.0",
+    "@volter/world-console": "2.0.2",
+    "@volter/world-core": "2.0.2",
+    "drizzle-orm": "0.45.3",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "resend": "^6.26.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.20",
+    "@types/node": "^24.0.0",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.7",
+    "@volter/twin-volteridentity": "0.1.2",
+    "@volter/world-host": "2.0.2",
+    "@volter/world-runtime": "2.0.2",
+    "@volter/world-tooling": "0.1.0",
+    "drizzle-kit": "0.31.11",
+    "playwright": "^1.61.0",
+    "typescript": "^5.9.0"
+  },
+  "files": [
+    "src",
+    "client",
+    "README.md",
+    "LICENSE",
+    "!**/*.test.ts",
+    "!**/*.uitest.ts",
+    "!src/rehearsal.ts",
+    "!census.json",
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/world.git",
+    "directory": "apps/platform"
+  }
+}

package/src/audit.ts

@@ -0,0 +1,26 @@
+// The platform's audit log (punchlist 4.1, written now so layer 2's acts land in it): a catalog of
+// named admin acts, append-only per org, one row per act — Sentry's shape in World's words. A table in
+// the platform's database (db/schema.ts `audit`), in the order the acts happened.
+import { and, desc, eq } from 'drizzle-orm';
+import { openDatabase, type PlatformDb } from './db/open.ts';
+import { audit as auditRows } from './db/schema.ts';
+
+export const AUDIT_EVENTS = ['ORG_CREATE', 'ORG_RENAME', 'ORG_DELETE', 'MEMBER_INVITE', 'INVITE_REVOKE', 'MEMBER_REMOVE', 'MEMBER_ROLE', 'WORLD_PROVISION', 'WORLD_DELETE', 'WORLD_OPEN', 'WORLD_CLAIM', 'PREVIEW_CREATE', 'PREVIEW_DELETE', 'TOKEN_CREATE', 'TOKEN_REVOKE', 'ORG_TOKEN_CREATE', 'ORG_TOKEN_REVOKE', 'SECURITY_CHANGE', 'SUPPORT_REQUEST', 'SUPPORT_ACCESS_GRANTED', 'SUPPORT_ACCESS_REVOKED', 'IMPERSONATION', 'WEBHOOK_CREATE', 'WEBHOOK_CHANGE', 'WEBHOOK_DELETE', 'WEBHOOK_DISABLED', 'SPEND_CAP_CHANGE', 'LABS_CHANGE', 'REMINDER_SENT', 'PLAN_CHECKOUT', 'PLAN_CHANGE', 'QUOTA_WARNED', 'QUOTA_RESTRICTED', 'QUOTA_CLEARED'] as const;
+export type AuditEvent = (typeof AUDIT_EVENTS)[number];
+export type AuditEntry = { at: string; event: AuditEvent; org: string; actor: { id: string; email?: string } | { operator: true } | { platform: true }; target?: string; data?: Record<string, unknown> };
+
+export class Audit {
+  private readonly db: PlatformDb;
+  constructor(stateDir: string) { this.db = openDatabase(stateDir); }
+  record(entry: Omit<AuditEntry, 'at'>): AuditEntry {
+    if (!/^[A-Za-z0-9_-]{1,80}$/.test(entry.org)) throw new Error('bad org id');
+    const full: AuditEntry = { at: new Date().toISOString(), ...entry };
+    this.db.insert(auditRows).values({ org: full.org, at: full.at, event: full.event, actor: full.actor, target: full.target ?? null, data: full.data ?? null }).run();
+    return full;
+  }
+  /** The org's log, newest first, at most `limit` entries. */
+  read(org: string, limit = 200): AuditEntry[] {
+    return (this.db.select().from(auditRows).where(and(eq(auditRows.org, org))).orderBy(desc(auditRows.seq)).limit(limit).all() as Array<typeof auditRows.$inferSelect>)
+      .map((r) => ({ at: r.at, event: r.event as AuditEvent, org: r.org, actor: r.actor as AuditEntry['actor'], ...(r.target !== null ? { target: r.target } : {}), ...(r.data !== null && r.data !== undefined ? { data: r.data as Record<string, unknown> } : {}) }));
+  }
+}

package/src/backup.ts

@@ -0,0 +1,73 @@
+// Backups of the platform's state (punchlist 4.4): everything under the state directory — the org
+// records, personal tokens, the audit logs, the enrolled providers, the operator token — as ONE
+// JSON archive, put into an S3 bucket through the UNMODIFIED @aws-sdk/client-s3: the aws twin in
+// rehearsal, real S3 (or any S3-compatible store) in production, named by the vendor's own
+// AWS_* env; the bucket is named on the command line (--backup-bucket). The database goes in as a snapshot SQLite
+// makes of itself (VACUUM INTO), never its live file; a restore stages it, and the platform puts it in place when it
+// next starts (db/open.ts).
+import { CreateBucketCommand, GetObjectCommand, HeadBucketCommand, ListObjectsV2Command, PutObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { sql } from 'drizzle-orm';
+import { DB_FILE, openDatabase, RESTORE_FILE } from './db/open.ts';
+
+export type Archive = { madeAt: string; files: Record<string, string> }; // path → base64
+export type BackupOptions = { bucket?: string; prefix?: string; client?: S3Client };
+
+/** The state directory as one archive: every regular file, base64, keyed by its relative path; the database as a
+ *  consistent snapshot of itself (its live file and write-ahead log are never read mid-write). */
+export function archiveOf(stateDir: string): Archive {
+  const files: Record<string, string> = {};
+  const live = new Set([DB_FILE, `${DB_FILE}-wal`, `${DB_FILE}-shm`, RESTORE_FILE]);
+  const walk = (dir: string): void => { for (const e of readdirSync(dir)) { const p = join(dir, e); const st = statSync(p); if (st.isDirectory()) walk(p); else if (st.isFile() && !(dir === stateDir && live.has(e))) files[relative(stateDir, p)] = readFileSync(p).toString('base64'); } };
+  walk(stateDir);
+  const snapshot = join(tmpdir(), `platform-${randomBytes(6).toString('hex')}.db`);
+  try { openDatabase(stateDir).run(sql.raw(`VACUUM INTO '${snapshot.replace(/'/g, "''")}'`)); files[DB_FILE] = readFileSync(snapshot).toString('base64'); }
+  finally { rmSync(snapshot, { force: true }); }
+  return { madeAt: new Date().toISOString(), files };
+}
+/** Write an archive back: the files as they were, and the database staged beside the live one, put in place when the
+ *  platform next starts (it has the live one open now). */
+export function restoreArchive(stateDir: string, archive: Archive): number {
+  let n = 0;
+  for (const [rel, b64] of Object.entries(archive.files)) {
+    if (rel.includes('..')) continue;
+    const p = join(stateDir, rel === DB_FILE ? RESTORE_FILE : rel); mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, Buffer.from(b64, 'base64')); n++;
+  }
+  return n;
+}
+
+export class Backups {
+  private readonly s3: S3Client; private readonly bucket: string; private readonly prefix: string;
+  constructor(opts: BackupOptions = {}) {
+    const bucket = opts.bucket;
+    if (!bucket) throw new Error('backups: no bucket named (--backup-bucket)');
+    this.bucket = bucket; this.prefix = opts.prefix ?? 'platform-state/';
+    this.s3 = opts.client ?? new S3Client({ region: process.env.AWS_REGION || 'us-east-1', ...(process.env.AWS_ENDPOINT_URL ? { endpoint: process.env.AWS_ENDPOINT_URL, forcePathStyle: true } : {}) }); // a blank region (the world mints AWS_REGION empty) is the default region
+  }
+  private async ensureBucket(): Promise<void> {
+    try { await this.s3.send(new HeadBucketCommand({ Bucket: this.bucket })); } catch { await this.s3.send(new CreateBucketCommand({ Bucket: this.bucket })); }
+  }
+  /** Put the archive; answers its key. */
+  async backup(stateDir: string): Promise<{ key: string; files: number; bytes: number }> {
+    await this.ensureBucket();
+    const archive = archiveOf(stateDir); const body = JSON.stringify(archive);
+    const key = `${this.prefix}${archive.madeAt.replace(/[:.]/g, '-')}.json`;
+    await this.s3.send(new PutObjectCommand({ Bucket: this.bucket, Key: key, Body: body, ContentType: 'application/json' }));
+    return { key, files: Object.keys(archive.files).length, bytes: body.length };
+  }
+  async list(): Promise<string[]> {
+    await this.ensureBucket();
+    const r = await this.s3.send(new ListObjectsV2Command({ Bucket: this.bucket, Prefix: this.prefix }));
+    return (r.Contents ?? []).map((o) => o.Key!).filter(Boolean).sort();
+  }
+  /** Fetch an archive and write its files back into the state directory. */
+  async restore(stateDir: string, key: string): Promise<{ key: string; files: number; madeAt: string; restart: string }> {
+    const r = await this.s3.send(new GetObjectCommand({ Bucket: this.bucket, Key: key }));
+    const text = await r.Body!.transformToString();
+    const archive = JSON.parse(text) as Archive;
+    return { key, files: restoreArchive(stateDir, archive), madeAt: archive.madeAt, restart: 'the database is staged: restart the platform to put it in place' };
+  }
+}

package/src/biller.ts

@@ -0,0 +1,45 @@
+// THE BILLER (docs/contributing/architecture.md, "The hosted product": billing is Volter's alone, `apps/billing`).
+// The platform names no plan, price or meter: it asks an attached biller what an org may do, tells it what happened,
+// and passes the org's billing doors through. With no biller attached nothing is limited and no billing door answers.
+// This module is the whole contract, types only: the platform depends on no biller's code.
+import type { AuditEntry } from './audit.ts';
+
+/** What the platform lends a biller: its record of each org's Worlds, the org's admins, its mail and its audit log. */
+export type BillerContext = {
+  /** This platform's public origin: where a checkout returns and a mail links. */
+  origin: string;
+  /** Every org the platform holds a record for, by Volter organization id (the tick's roster). */
+  orgIds: () => string[];
+  /** The Worlds an org holds now, by served name. */
+  worldsOf: (orgId: string) => string[];
+  /** The org's admins' addresses. */
+  adminsOf: (orgId: string) => Promise<string[]>;
+  /** The platform's mail (best effort). */
+  mail: (to: string[], subject: string, text: string) => Promise<void>;
+  /** An act on the org's audit log (and its webhooks). */
+  record: (entry: Omit<AuditEntry, 'at'>) => void;
+  /** Where a person manages billing: the platform's page for the org. */
+  billingPage: (org: { id: string; slug: string | null }) => string;
+  /** Where the biller keeps what it knows (a pending checkout, the restriction, usage by day), by its own keys: the
+   *  platform's database, which names no plan or price. */
+  records: { get: <T>(key: string) => T | null; put: (key: string, value: unknown) => void };
+};
+
+export type Biller = {
+  /** Before a World is made for an org: null when it may be, else the refusal the person reads (402). */
+  admit: (orgId: string, want: { twins: number }) => Promise<Response | null>;
+  /** A World was made (metered once, by its name). */
+  worldMade: (orgId: string, name: string) => Promise<void>;
+  /** `/-/orgs/<org>/<verb>` for the biller's verbs, the org resolved and the person a member of it. */
+  door: (request: Request, verb: string, ctx: { org: { id: string; slug: string | null }; admin: boolean; person: { id: string; email?: string } }) => Promise<Response>;
+  /** The verbs `door` answers under an org. */
+  verbs: readonly string[];
+  /** The hourly work: usage metered, every org through its quota, reminders sent. */
+  tick: () => Promise<Record<string, unknown>>;
+  /** The operator's line for an org: its plan and restriction, in words. */
+  summary: (orgId: string) => Promise<{ plan: string; restriction: string | null }>;
+  /** When the tick last ran. */
+  lastTickAt: () => string | null;
+};
+
+export type BillerFactory = (ctx: BillerContext) => Biller;

package/src/cli.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// volter-platform — the Volter World platform as a PROCESS: an app in a world.
+//
+//   volter-platform serve --dir <state> [--port P] [--host H] [--url <origin reached at>] [--provider volter|oidc|github] [--site <front door origin>]
+//
+// Its substrate is its state directory and its listener. People sign in through ONE access provider
+// (identity.ts): `volter`, Volter Identity (VOLTER_ISSUER, and the client registered for this platform
+// there: VOLTER_CLIENT_ID and VOLTER_CLIENT_SECRET — in a world, the identity twin and the client the
+// drive registered on it), or `oidc`, any OpenID Connect issuer (OIDC_ISSUER, OIDC_CLIENT_ID,
+// OIDC_CLIENT_SECRET, OIDC_NAME), or `github`, a GitHub OAuth app (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, and
+// GITHUB_URL / GITHUB_API_URL for GitHub Enterprise Server); for both the platform keeps the directory in its state.
+// Without --provider, OIDC_ISSUER in the env chooses `oidc`, else `volter`; GitHub is chosen only by name. Volter's biller (apps/billing) is attached when
+// POLAR_ACCESS_TOKEN is in the env; without it nothing is limited or priced.
+// The hosts it provisions onto are ENROLLED through the operator's door (POST /-/hosts), kept in
+// `<state>/providers.json` as `{ hosts: [{ id, base, adminToken }] }`.
+import { Backups } from './backup.ts';
+import { mailer } from './mail.ts';
+import { chmodSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { makeSigningKey, type SigningKey } from '@volter/world-access';
+import { join, resolve } from 'node:path';
+import { servePlatform, operatorTokenFor, type HostProvider, type Providers } from './platform.ts';
+import type { BillerFactory } from './biller.ts';
+import { writeFileSync } from 'node:fs';
+import { Store } from './store.ts';
+
+const [cmd, ...rest] = process.argv.slice(2);
+const value = (flag: string): string | undefined => { const i = rest.indexOf(flag); return i >= 0 ? rest[i + 1] : undefined; };
+const usage = 'volter-platform serve --dir <state> [--port P] [--host H] [--url <origin>] [--provider volter|oidc|github] [--site <front door origin>] [--backup-bucket <s3 bucket>] [--mail-from <sender>] [--tick-every <seconds>] [--backup-at <HH:MM UTC>] [--deliver-every <seconds>] [--support-to <address>] [--client-ip-header <name>]\n';
+
+if (cmd !== 'serve' || !value('--dir')) { process.stderr.write(usage); process.exit(2); }
+const dir = resolve(value('--dir')!);
+const providersPath = join(dir, 'providers.json');
+const providers: Providers = existsSync(providersPath) ? { hosts: [], ...(JSON.parse(readFileSync(providersPath, 'utf8')) as Partial<Providers>) } : { hosts: [] };
+const hosts: HostProvider[] = providers.hosts;
+// nothing enrolled yet is fine: the operator enrolls hosts through the door (POST /-/hosts)
+
+// the key passes are signed with, kept beside the operator token (owner-only): made once, then the same key, so a
+// restart does not strand the hosts that cached its public half
+const signingKeyPath = join(dir, 'signing-key.json');
+const signingKey: SigningKey = existsSync(signingKeyPath) ? (JSON.parse(readFileSync(signingKeyPath, 'utf8')) as SigningKey) : await (async () => {
+  const made = await makeSigningKey();
+  mkdirSync(dir, { recursive: true }); writeFileSync(signingKeyPath, `${JSON.stringify(made)}\n`, { mode: 0o600 });
+  return made;
+})();
+
+const provider = value('--provider') ?? (process.env.OIDC_ISSUER ? 'oidc' : 'volter');
+if (provider !== 'volter' && provider !== 'oidc' && provider !== 'github') { process.stderr.write(`--provider is volter, oidc or github, not ${provider}\n${usage}`); process.exit(2); }
+// Volter's biller, only where Polar is configured: a self-hosted platform carries no billing. It is Volter's and not
+// published, so it is named by a string the build does not follow; where it is absent the platform refuses to start
+// rather than run unmetered while Polar was meant to bill.
+type BillerModule = { createBiller: (opts: { notify?: (note: { kind: string; org: string; meter: string; graceEnds?: string }) => void }) => BillerFactory };
+const BILLER = '@volter/world-billing';
+const billing: BillerFactory | undefined = process.env.POLAR_ACCESS_TOKEN
+  ? await (import(BILLER) as Promise<BillerModule>).then(
+      (m) => m.createBiller({ notify: (note) => process.stdout.write(`notify  ${note.kind}  org ${note.org}  ${note.meter}${note.graceEnds ? `  grace ends ${note.graceEnds}` : ''}\n`) }),
+      (): never => { process.stderr.write(`POLAR_ACCESS_TOKEN is set, but Volter's biller (${BILLER}) is not installed here. It is private to Volter and not published: Volter's platform runs from its repository's workspace, where it resolves (deploy/RUNBOOK.md). A self-hosted platform bills nothing: unset POLAR_ACCESS_TOKEN.\n`); process.exit(2); },
+    )
+  : undefined;
+
+// https, or http only on this machine: over plain http on a public name the session cookies cannot be `__Host-` (a sibling
+// name could set its own), and they would travel in clear
+{
+  const url = value('--url');
+  if (url) {
+    let at: URL; try { at = new URL(url); } catch { process.stderr.write(`--url ${url} is not an address\n`); process.exit(2); }
+    const local = at.hostname === 'localhost' || at.hostname.endsWith('.localhost') || at.hostname === '127.0.0.1' || at.hostname === '[::1]';
+    if (at.protocol !== 'https:' && !(at.protocol === 'http:' && local)) { process.stderr.write(`--url ${url}: the platform is reached over https (or http on this machine's loopback)\n`); process.exit(2); }
+  }
+}
+
+const host = value('--host') ?? '127.0.0.1';
+// reached at a public address with no proxy header named: unauthenticated requests share one rate-limit bucket (no client
+// names its own address), so one noisy caller slows every sign-in; the deploy's proxy header gives each client its own
+{
+  const url = value('--url');
+  const local = url ? ((h) => h === 'localhost' || h.endsWith('.localhost') || h === '127.0.0.1' || h === '[::1]')(new URL(url).hostname) : true;
+  if (!value('--client-ip-header') && !local) process.stderr.write("warning  no --client-ip-header: requests without a token share one rate-limit bucket. Name the header your proxy sets to the client's address (cf-connecting-ip on Cloudflare, x-forwarded-for behind a proxy that appends to it).\n");
+}
+const served = await servePlatform({
+  host, port: Number(value('--port') ?? 0), ...(value('--url') ? { origin: value('--url')! } : {}),
+  mail: mailer(value('--mail-from') ? { from: value('--mail-from')! } : {}), // Resend through the boundary when RESEND_API_KEY is in the env; the log otherwise
+  ...(value('--backup-bucket') ? { backups: new Backups({ bucket: value('--backup-bucket')! }) } : {}), // S3 through the boundary: the aws twin in rehearsal
+  provider: { kind: provider },
+  ...(billing ? { billing } : {}),
+  ...(value('--site') ? { siteUrl: value('--site')! } : {}), // the front door: its docs, and the terms accepted at org creation
+  store: new Store(dir),
+  ...(value('--support-to') ? { supportTo: value('--support-to')! } : {}), // where the Help form's mail goes (layer 6)
+  ...(value('--client-ip-header') ? { clientIpHeader: value('--client-ip-header')! } : {}), // the header the deploy's proxy sets to the client's address
+  clock: { ...(value('--tick-every') ? { tickEverySeconds: Number(value('--tick-every')) } : {}), ...(value('--backup-at') ? { backupAt: value('--backup-at')! } : {}), ...(value('--deliver-every') ? { deliverEverySeconds: Number(value('--deliver-every')) } : {}) }, // the platform's own clock (layer 5; webhook deliveries, layer 7)
+  stateDir: dir,
+  hosts,
+  // the enrolled hosts' admin tokens: owner-only, as the operator token and the signing key are
+  onProviders: (p) => { writeFileSync(providersPath, `${JSON.stringify(p, null, 2)}\n`, { mode: 0o600 }); chmodSync(providersPath, 0o600); },
+  signingKey,
+});
+const origin = served.url;
+process.stdout.write(`platform ready  ${origin}  (${hosts.length} host${hosts.length === 1 ? '' : 's'} enrolled; sign-in ${provider}; ${billing ? 'billing attached' : 'no billing'})\noperator token  ${operatorTokenFor(dir)}\n`);
+const shutdown = (): void => { void served.stop().finally(() => process.exit(0)); };
+process.on('SIGTERM', shutdown); process.on('SIGINT', shutdown);

package/src/db/migrations/0000_init.sql

@@ -0,0 +1,143 @@
+CREATE TABLE `audit` (
+	`seq` integer PRIMARY KEY AUTOINCREMENT NOT NULL,
+	`org` text NOT NULL,
+	`at` text NOT NULL,
+	`event` text NOT NULL,
+	`actor` text NOT NULL,
+	`target` text,
+	`data` text
+);
+--> statement-breakpoint
+CREATE INDEX `audit_org` ON `audit` (`org`,`seq`);--> statement-breakpoint
+CREATE TABLE `biller_records` (
+	`key` text PRIMARY KEY NOT NULL,
+	`value` text NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `deliveries` (
+	`id` text PRIMARY KEY NOT NULL,
+	`org_id` text NOT NULL,
+	`endpoint_id` text NOT NULL,
+	`event_id` text NOT NULL,
+	`event` text NOT NULL,
+	`body` text NOT NULL,
+	`attempt` integer NOT NULL,
+	`next_at` text NOT NULL,
+	`attempts` text NOT NULL,
+	`state` text NOT NULL,
+	`seq` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `deliveries_state` ON `deliveries` (`state`,`next_at`);--> statement-breakpoint
+CREATE INDEX `deliveries_endpoint` ON `deliveries` (`endpoint_id`);--> statement-breakpoint
+CREATE TABLE `dir_members` (
+	`org_id` text NOT NULL,
+	`user_id` text NOT NULL,
+	`role` text NOT NULL,
+	PRIMARY KEY(`org_id`, `user_id`)
+);
+--> statement-breakpoint
+CREATE INDEX `dir_members_user` ON `dir_members` (`user_id`);--> statement-breakpoint
+CREATE TABLE `dir_orgs` (
+	`id` text PRIMARY KEY NOT NULL,
+	`slug` text NOT NULL,
+	`name` text NOT NULL,
+	`created_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `dir_orgs_slug_unique` ON `dir_orgs` (`slug`);--> statement-breakpoint
+CREATE TABLE `invitations` (
+	`id` text PRIMARY KEY NOT NULL,
+	`org_id` text NOT NULL,
+	`email` text NOT NULL,
+	`role` text NOT NULL,
+	`inviter_id` text NOT NULL,
+	`created_at` text NOT NULL,
+	`expires_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `invitations_org` ON `invitations` (`org_id`);--> statement-breakpoint
+CREATE INDEX `invitations_email` ON `invitations` (`email`);--> statement-breakpoint
+CREATE TABLE `meta` (
+	`key` text PRIMARY KEY NOT NULL,
+	`value` text
+);
+--> statement-breakpoint
+CREATE TABLE `org_settings` (
+	`org_id` text PRIMARY KEY NOT NULL,
+	`security` text,
+	`flags` text,
+	`early_adopter` integer,
+	`support_access` text
+);
+--> statement-breakpoint
+CREATE TABLE `org_worlds` (
+	`org_id` text NOT NULL,
+	`name` text NOT NULL,
+	`host` text NOT NULL,
+	`base` text NOT NULL,
+	`provisioned_at` text NOT NULL,
+	PRIMARY KEY(`org_id`, `name`)
+);
+--> statement-breakpoint
+CREATE TABLE `people` (
+	`id` text PRIMARY KEY NOT NULL,
+	`email` text,
+	`email_verified` integer NOT NULL,
+	`name` text,
+	`first_seen_at` text NOT NULL,
+	`last_seen_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX `people_email` ON `people` (`email`);--> statement-breakpoint
+CREATE TABLE `sessions` (
+	`id_hash` text PRIMARY KEY NOT NULL,
+	`subject` text NOT NULL,
+	`email` text,
+	`name` text,
+	`expires_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `support_requests` (
+	`id` text PRIMARY KEY NOT NULL,
+	`at` text NOT NULL,
+	`person` text NOT NULL,
+	`org` text,
+	`world` text,
+	`category` text NOT NULL,
+	`severity` text NOT NULL,
+	`subject` text NOT NULL,
+	`message` text NOT NULL,
+	`status` text NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE `tokens` (
+	`hash` text PRIMARY KEY NOT NULL,
+	`user_id` text NOT NULL,
+	`name` text NOT NULL,
+	`created_at` text NOT NULL,
+	`last4` text NOT NULL,
+	`last_used_at` text,
+	`expires_at` text,
+	`scopes` text,
+	`org_id` text,
+	`support` text,
+	`world_keys` text
+);
+--> statement-breakpoint
+CREATE INDEX `tokens_user` ON `tokens` (`user_id`);--> statement-breakpoint
+CREATE INDEX `tokens_org` ON `tokens` (`org_id`);--> statement-breakpoint
+CREATE TABLE `webhooks` (
+	`id` text PRIMARY KEY NOT NULL,
+	`org_id` text NOT NULL,
+	`url` text NOT NULL,
+	`secret` text NOT NULL,
+	`events` text NOT NULL,
+	`description` text NOT NULL,
+	`created_at` text NOT NULL,
+	`consecutive_failures` integer NOT NULL,
+	`last_failed_at` text,
+	`disabled_at` text
+);
+--> statement-breakpoint
+CREATE INDEX `webhooks_org` ON `webhooks` (`org_id`);