@volter/world-platform 2.0.0

package/src/sample.ts

@@ -0,0 +1,84 @@
+// THE SAMPLE WORLD (docs/contributing/architecture.md, "A new org sees a World working"): a World the platform
+// makes for an org that has none, seeded the way every World is — through the vendors' own APIs, as an app would call
+// them (never a handler faking a stored write) — so each vendor's screen shows an app's work in the first minute.
+//
+// The story: a small shop that sells a Pro plan. Stripe holds its customers, the plan and two paid orders; Slack holds
+// the workspace where the shop's app announces each sale. It runs once: a second run finds the story's first customer
+// and adds nothing.
+
+/** The vendors a sample World stands in for, in the order they are taken, those the host serves. Two, so it fits the
+ *  smallest plan. */
+export const SAMPLE_VENDORS = ['stripe', 'slack'] as const;
+export const SAMPLE_WORLD = 'sample';
+
+const CUSTOMERS = [
+  { name: 'Ada Lovelace', email: 'ada@example.com' },
+  { name: 'Grace Hopper', email: 'grace@example.com' },
+  { name: 'Alan Turing', email: 'alan@example.com' },
+] as const;
+
+type Call = (vendor: string, path: string, init: { method?: string; auth: string; form?: Record<string, string>; json?: unknown }) => Promise<Record<string, unknown>>;
+
+/** A caller for one World's vendor APIs: the World's token in `x-twins-key`, the vendor's own credential beside it. */
+function caller(base: string, token: string): Call {
+  return async (vendor, path, init) => {
+    const headers: Record<string, string> = { 'x-twins-key': token, authorization: init.auth };
+    let body: string | undefined;
+    if (init.form) { headers['content-type'] = 'application/x-www-form-urlencoded'; body = new URLSearchParams(init.form).toString(); }
+    if (init.json !== undefined) { headers['content-type'] = 'application/json'; body = JSON.stringify(init.json); }
+    const res = await fetch(`${base}/${vendor}${path}`, { method: init.method ?? (body ? 'POST' : 'GET'), headers, ...(body ? { body } : {}) });
+    const answer = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+    if (!res.ok) throw new Error(`${vendor} ${path} answered ${res.status}: ${JSON.stringify(answer).slice(0, 200)}`);
+    return answer;
+  };
+}
+
+const STRIPE = 'Bearer sk_test_sample';
+const BOT = 'Bearer xoxb-twin-bot';
+
+async function seedStripe(call: Call): Promise<string[]> {
+  const found = await call('stripe', `/v1/customers?email=${encodeURIComponent(CUSTOMERS[0].email)}`, { auth: STRIPE }) as { data?: unknown[] };
+  if (found.data?.length) return [];
+  const ids: string[] = [];
+  for (const c of CUSTOMERS) ids.push((await call('stripe', '/v1/customers', { auth: STRIPE, form: { name: c.name, email: c.email } })).id as string);
+  const product = await call('stripe', '/v1/products', { auth: STRIPE, form: { name: 'Pro plan', description: 'Everything in the shop, billed monthly' } });
+  await call('stripe', '/v1/prices', { auth: STRIPE, form: { product: product.id as string, unit_amount: '2900', currency: 'usd', 'recurring[interval]': 'month' } });
+  for (const customer of ids.slice(0, 2)) {
+    await call('stripe', '/v1/payment_intents', { auth: STRIPE, form: { amount: '2900', currency: 'usd', customer, payment_method: 'pm_card_visa', confirm: 'true', 'automatic_payment_methods[enabled]': 'true', 'automatic_payment_methods[allow_redirects]': 'never', description: 'Pro plan' } });
+  }
+  return ['3 customers', 'the Pro plan at $29 a month', '2 paid orders'];
+}
+
+async function seedSlack(call: Call): Promise<string[]> {
+  const channel = async (name: string): Promise<string> => {
+    const made = await call('slack', '/api/conversations.create', { auth: BOT, json: { name } }) as { ok?: boolean; error?: string; channel?: { id?: string } };
+    if (made.ok && made.channel?.id) return made.channel.id;
+    const listed = await call('slack', '/api/conversations.list', { auth: BOT, json: {} }) as { channels?: Array<{ id?: string; name?: string }> };
+    const id = listed.channels?.find((c) => c.name === name)?.id;
+    if (!id) throw new Error(`slack: #${name} was neither made nor found (${made.error ?? 'no answer'})`);
+    return id;
+  };
+  const general = await channel('general');
+  const sales = await channel('sales');
+  // a new channel already holds its "has joined" line (a subtype): only the app's own messages say the story ran
+  const history = await call('slack', '/api/conversations.history', { auth: BOT, json: { channel: sales } }) as { messages?: Array<{ subtype?: string }> };
+  if (history.messages?.some((m) => !m.subtype)) return [];
+  await call('slack', '/api/chat.postMessage', { auth: BOT, json: { channel: general, text: 'The shop is open: this workspace is where the shop\'s app says what it did.' } });
+  for (const c of CUSTOMERS.slice(0, 2)) await call('slack', '/api/chat.postMessage', { auth: BOT, json: { channel: sales, text: `New order: ${c.name} bought the Pro plan ($29.00)` } });
+  return ['#general and #sales', '3 messages from the shop\'s app'];
+}
+
+const SEEDERS: Record<string, (call: Call) => Promise<string[]>> = { stripe: seedStripe, slack: seedSlack };
+
+/** Seed a sample World at `base` (its vendor APIs under `<base>/<vendor>`) with its token; answers what each vendor
+ *  now holds, or why it holds nothing. A vendor that fails leaves the others seeded. */
+export async function seedSample(base: string, token: string, vendors: readonly string[]): Promise<Record<string, { seeded: string[] } | { error: string }>> {
+  const call = caller(base.replace(/\/+$/, ''), token);
+  const out: Record<string, { seeded: string[] } | { error: string }> = {};
+  for (const v of vendors) {
+    const seed = SEEDERS[v];
+    if (!seed) continue;
+    try { out[v] = { seeded: await seed(call) }; } catch (e) { out[v] = { error: (e as Error).message }; }
+  }
+  return out;
+}

package/src/store.ts

@@ -0,0 +1,154 @@
+// THE PLATFORM'S STORE (docs/reference/platform-api.md; docs/contributing/architecture.md, "The platform's state is
+// SQLite"): what the platform keeps about an org that the directory does not — the org's WORLDS (where each lives) and
+// its settings — and the platform's own position (the backup, the operator's notice, support requests, the webhook
+// queue). The org itself, its members and their roles are the directory's (directory.ts), keyed by its organization id.
+// Billing keeps its own records (apps/billing). Tables in the platform's database (db/schema.ts), read and written
+// through the methods below, each one statement or one transaction.
+import { and, asc, eq, inArray } from 'drizzle-orm';
+import { openDatabase, type PlatformDb } from './db/open.ts';
+import { deliveries as deliveryRows, meta, orgSettings, orgWorlds, supportRequests, webhooks as webhookRows } from './db/schema.ts';
+import type { Delivery, WebhookEndpoint } from './webhooks.ts';
+
+/** A world the org holds: it LIVES on a host — the platform records where, never its log. */
+export type OrgWorld = { name: string; host: string; base: string; provisionedAt: string };
+/** The org's security switches (layer 6: PostHog's members_can_invite / members_can_use_personal_api_keys, Twenty's approved domains). */
+export type Security = { membersCanInvite: boolean; membersCanUsePersonalTokens: boolean; approvedEmailDomains: string[] };
+export const DEFAULT_SECURITY: Security = { membersCanInvite: false, membersCanUsePersonalTokens: true, approvedEmailDomains: [] };
+/** Consent for support to open the org, for a while (layer 6: Supabase's allowSupportAccess, Twenty's allowImpersonation). */
+export type SupportAccess = { until: string; grantedBy: string; requestId: string };
+/** What the platform holds for one org: its Worlds and its settings. */
+export type OrgDoc = { id: string; worlds: OrgWorld[]; /** webhook endpoints (layer 7) */ webhooks?: WebhookEndpoint[]; /** labs (layer 8): early-access features on for this org, and the early-adopter switch that turns on every new one */ flags?: Record<string, boolean>; earlyAdopter?: boolean; security?: Security; supportAccess?: SupportAccess | null; };
+/** A support request as the Help form sent it (Supabase's fields), kept for the operator's page. */
+export type SupportRequest = { id: string; at: string; person: { id: string; email?: string }; org: string | null; world: string | null; category: string; severity: string; subject: string; message: string; status: 'open' | 'closed' };
+/** The platform's own position — the backup's last run and the operator's notice, and the support requests. */
+/** A preview (docs/contributing/architecture.md, "CI runs in a World"): a named branch of one of the org's Worlds,
+ *  made and removed by the platform for CI or a person; `label` names it within its World (`pr-12`). */
+/** A pull request's preview: a branch of `world`, made with a key of its own in the parent (`key`, its id), so revoking
+ *  that key, or the token or membership it was made for, ends the branch. */
+export type Preview = { label: string; world: string; branch: string; createdAt: string; expiresAt: string | null; createdBy: string; key?: string };
+export type PlatformDoc = { lastBackupAt: string | null; notice: { text: string; at: string } | null; support?: SupportRequest[] };
+
+const NAME = /^[a-z0-9][a-z0-9-]{0,38}$/;
+export function assertName(kind: string, value: string): string {
+  if (!NAME.test(value)) throw new Error(`${kind} must be lowercase letters, digits and dashes (1-39): got ${JSON.stringify(value)}`);
+  return value;
+}
+/** A Volter organization id (Better Auth's: letters and digits) is a name before it is a key. */
+const ORG_ID = /^[A-Za-z0-9_-]{1,80}$/;
+const orgIdOf = (orgId: string): string => { if (!ORG_ID.test(orgId)) throw new Error(`not an organization id: ${JSON.stringify(orgId)}`); return orgId; };
+const KEEP_DELIVERIES = 2000;
+const KEEP_SUPPORT = 500;
+
+export class Store {
+  readonly db: PlatformDb;
+  /** The store over the platform's database at `<dir>/platform.db`. */
+  constructor(dir: string) { this.db = openDatabase(dir); }
+
+  private settings(orgId: string) { return this.db.select().from(orgSettings).where(eq(orgSettings.orgId, orgId)).get() as (typeof orgSettings.$inferSelect) | undefined; }
+  private patchSettings(orgId: string, patch: Partial<typeof orgSettings.$inferInsert>): void {
+    this.db.insert(orgSettings).values({ orgId: orgIdOf(orgId), ...patch }).onConflictDoUpdate({ target: orgSettings.orgId, set: patch }).run();
+  }
+
+  /** What the platform holds for an org; an org the directory holds but the platform has not seen yet holds no Worlds. */
+  doc(orgId: string): OrgDoc {
+    orgIdOf(orgId);
+    const worlds = (this.db.select().from(orgWorlds).where(eq(orgWorlds.orgId, orgId)).orderBy(asc(orgWorlds.provisionedAt)).all() as Array<typeof orgWorlds.$inferSelect>)
+      .map((w) => ({ name: w.name, host: w.host, base: w.base, provisionedAt: w.provisionedAt }));
+    const s = this.settings(orgId);
+    const hooks = this.webhooksOf(orgId);
+    return { id: orgId, worlds, ...(hooks.length ? { webhooks: hooks } : {}), ...(s?.flags ? { flags: s.flags } : {}), ...(s?.earlyAdopter !== null && s?.earlyAdopter !== undefined ? { earlyAdopter: s.earlyAdopter } : {}), ...(s?.security ? { security: s.security } : {}), ...(s?.supportAccess !== undefined ? { supportAccess: s.supportAccess } : {}) };
+  }
+  /** Record a World the org holds; one name once (the primary key refuses a second). */
+  recordWorld(orgId: string, world: OrgWorld): OrgDoc {
+    try { this.db.insert(orgWorlds).values({ orgId: orgIdOf(orgId), ...world }).run(); }
+    catch (e) { if (/UNIQUE|PRIMARY KEY/i.test(String((e as Error).message))) throw new Error(`the org already holds a world named ${world.name}`); throw e; }
+    return this.doc(orgId);
+  }
+  removeWorld(orgId: string, name: string): OrgDoc { this.db.delete(orgWorlds).where(and(eq(orgWorlds.orgId, orgIdOf(orgId)), eq(orgWorlds.name, name))).run(); return this.doc(orgId); }
+  /** Every org the platform holds a record for — the biller's roster. */
+  orgIds(): string[] {
+    const a = (this.db.selectDistinct({ id: orgWorlds.orgId }).from(orgWorlds).all() as Array<{ id: string }>).map((r) => r.id);
+    const b = (this.db.select({ id: orgSettings.orgId }).from(orgSettings).all() as Array<{ id: string }>).map((r) => r.id);
+    return [...new Set([...a, ...b])].sort();
+  }
+  setSupportAccess(orgId: string, supportAccess: SupportAccess | null): OrgDoc { this.patchSettings(orgId, { supportAccess }); return this.doc(orgId); }
+  supportAccessOf(orgId: string): SupportAccess | null { const a = this.settings(orgIdOf(orgId))?.supportAccess ?? null; return a && Date.parse(a.until) > Date.now() ? a : null; }
+  setLabs(orgId: string, patch: { flags?: Record<string, boolean>; earlyAdopter?: boolean }): OrgDoc {
+    this.db.transaction((tx) => {
+      const s = tx.select().from(orgSettings).where(eq(orgSettings.orgId, orgId)).get() as (typeof orgSettings.$inferSelect) | undefined;
+      const next = { ...(patch.flags ? { flags: { ...(s?.flags ?? {}), ...patch.flags } } : {}), ...(patch.earlyAdopter !== undefined ? { earlyAdopter: patch.earlyAdopter } : {}) };
+      tx.insert(orgSettings).values({ orgId: orgIdOf(orgId), ...next }).onConflictDoUpdate({ target: orgSettings.orgId, set: next }).run();
+    });
+    return this.doc(orgId);
+  }
+  setSecurity(orgId: string, security: Security): OrgDoc { this.patchSettings(orgId, { security }); return this.doc(orgId); }
+  securityOf(orgId: string): Security { return { ...DEFAULT_SECURITY, ...(this.settings(orgIdOf(orgId))?.security ?? {}) }; }
+
+  // webhooks (layer 7)
+  webhooksOf(orgId: string): WebhookEndpoint[] {
+    return (this.db.select().from(webhookRows).where(eq(webhookRows.orgId, orgId)).orderBy(asc(webhookRows.createdAt)).all() as Array<typeof webhookRows.$inferSelect>)
+      .map(({ orgId: _o, ...w }) => w);
+  }
+  /** The org's endpoints, as a whole: those not named go, the named are written. */
+  setWebhooks(orgId: string, list: WebhookEndpoint[]): OrgDoc {
+    this.db.transaction((tx) => {
+      tx.delete(webhookRows).where(eq(webhookRows.orgId, orgIdOf(orgId))).run();
+      if (list.length) tx.insert(webhookRows).values(list.map((w) => ({ ...w, orgId }))).run();
+    });
+    return this.doc(orgId);
+  }
+  updateWebhook(orgId: string, id: string, patch: Partial<WebhookEndpoint>): WebhookEndpoint | null {
+    const { id: _id, ...set } = patch;
+    if (Object.keys(set).length) this.db.update(webhookRows).set(set).where(and(eq(webhookRows.orgId, orgId), eq(webhookRows.id, id))).run();
+    return this.webhooksOf(orgId).find((w) => w.id === id) ?? null;
+  }
+
+  // the webhook delivery queue and its recent history (layer 7), in the order it was queued
+  deliveries(): Delivery[] { return (this.db.select().from(deliveryRows).orderBy(asc(deliveryRows.seq)).all() as Array<typeof deliveryRows.$inferSelect>).map(({ seq: _s, ...d }) => d); }
+  /** The queue as a whole (the delivery pass's result): kept in the order given. */
+  setDeliveries(list: Delivery[]): void {
+    this.db.transaction((tx) => {
+      const keep = list.slice(-KEEP_DELIVERIES);
+      tx.delete(deliveryRows).run();
+      if (keep.length) tx.insert(deliveryRows).values(keep.map((d, i) => ({ ...d, seq: i }))).run();
+    });
+  }
+  enqueueDeliveries(items: Delivery[]): void {
+    if (!items.length) return;
+    this.db.transaction((tx) => {
+      const last = (tx.select({ seq: deliveryRows.seq }).from(deliveryRows).orderBy(asc(deliveryRows.seq)).all() as Array<{ seq: number }>).at(-1)?.seq ?? -1;
+      tx.insert(deliveryRows).values(items.map((d, i) => ({ ...d, seq: last + 1 + i }))).run();
+      const all = (tx.select({ id: deliveryRows.id }).from(deliveryRows).orderBy(asc(deliveryRows.seq)).all() as Array<{ id: string }>);
+      if (all.length > KEEP_DELIVERIES) tx.delete(deliveryRows).where(inArray(deliveryRows.id, all.slice(0, all.length - KEEP_DELIVERIES).map((r) => r.id))).run();
+    });
+  }
+
+  // support requests (layer 6)
+  addSupportRequest(r: SupportRequest): SupportRequest[] {
+    this.db.transaction((tx) => {
+      tx.insert(supportRequests).values(r).run();
+      const all = (tx.select({ id: supportRequests.id }).from(supportRequests).orderBy(asc(supportRequests.at)).all() as Array<{ id: string }>);
+      if (all.length > KEEP_SUPPORT) tx.delete(supportRequests).where(inArray(supportRequests.id, all.slice(0, all.length - KEEP_SUPPORT).map((x) => x.id))).run();
+    });
+    return this.supportRequests();
+  }
+  private supportRequests(): SupportRequest[] { return this.db.select().from(supportRequests).orderBy(asc(supportRequests.at)).all() as SupportRequest[]; }
+  setSupportStatus(id: string, status: SupportRequest['status']): SupportRequest | null {
+    this.db.update(supportRequests).set({ status }).where(eq(supportRequests.id, id)).run();
+    return (this.db.select().from(supportRequests).where(eq(supportRequests.id, id)).get() as SupportRequest | undefined) ?? null;
+  }
+
+  // an org's previews, in its meta row (a handful per World, replaced whole)
+  previewsOf(orgId: string): Preview[] { return this.metaOf<Preview[]>(`previews:${orgId}`) ?? []; }
+  setPreviews(orgId: string, previews: Preview[]): void { this.setMeta(`previews:${orgId}`, previews); }
+
+  // the platform's own position
+  private metaOf<T>(key: string): T | null { return ((this.db.select().from(meta).where(eq(meta.key, key)).get() as { value: T } | undefined)?.value) ?? null; }
+  private setMeta(key: string, value: unknown): void { this.db.insert(meta).values({ key, value }).onConflictDoUpdate({ target: meta.key, set: { value } }).run(); }
+  platform(): PlatformDoc { return { lastBackupAt: this.metaOf<string>('lastBackupAt'), notice: this.metaOf<{ text: string; at: string }>('notice'), support: this.supportRequests() }; }
+  setPlatform(patch: Partial<PlatformDoc>): PlatformDoc {
+    if ('lastBackupAt' in patch) this.setMeta('lastBackupAt', patch.lastBackupAt ?? null);
+    if ('notice' in patch) this.setMeta('notice', patch.notice ?? null);
+    return this.platform();
+  }
+}

package/src/tokens.ts

@@ -0,0 +1,94 @@
+// Personal access tokens (punchlist 2.4): a person's own credential to the platform — for the CLI
+// (`volter login`) and for scripts. Shown ONCE at creation; stored hashed (sha256) under the
+// platform's state; revocable; named. Accepted wherever a session is (platform.ts presentedToken).
+// Never a world token: a world's tokens are the host's, resolved through the platform by a member.
+import { createHash, randomBytes } from 'node:crypto';
+import { and, asc, eq, isNull } from 'drizzle-orm';
+import { openDatabase, type PlatformDb } from './db/open.ts';
+import { tokens as tokenRows } from './db/schema.ts';
+
+export type TokenRecord = { hash: string; userId: string; name: string; createdAt: string; last4: string; lastUsedAt?: string; /** ISO, or null for a token that never expires (layer 5: Sentry's thirty-day default) */ expiresAt?: string | null;
+  /** `object:action` scopes (layer 6: Sentry's `org:read`, PostHog's objects × actions); `['*']` is everything the holder may do */
+  scopes?: string[];
+  /** set on an ORG token (`tok_o_…`, layer 6: Polar's organization access token, Twenty's workspace key): the org it acts as; userId is then the admin who made it */
+  orgId?: string;
+  /** set on a SUPPORT session (`tok_su_…`, layer 6): the operator's one-hour, read-only, consented view of an org — Sentry's privileged session with its reason */
+  support?: { reason: string; category: string };
+  /** the World keys made for this token (`volter remote add`), each revoked with it */
+  worldKeys?: Array<{ world: string; keyId: string; command?: boolean }> };
+export const DEFAULT_TOKEN_DAYS = 30;
+export const SCOPE_OBJECTS = ['worlds', 'orgs', 'members', 'billing', 'tokens', 'activity'] as const;
+export const SCOPE_ACTIONS = ['read', 'write'] as const;
+export const ALL_SCOPES = SCOPE_OBJECTS.flatMap((o) => SCOPE_ACTIONS.map((a) => `${o}:${a}`));
+/** A scope list is valid when every entry is `*` or `<object>:<action>` from the catalog. */
+export function validScopes(scopes: unknown): scopes is string[] {
+  return Array.isArray(scopes) && scopes.length > 0 && scopes.every((s) => s === '*' || (typeof s === 'string' && (ALL_SCOPES as string[]).includes(s)));
+}
+/** Whether a token's scopes cover a needed `object:action` — `*` covers all, `x:write` covers `x:read`. */
+export function hasScope(scopes: string[] | undefined, need: string): boolean {
+  const list = scopes ?? ['*'];
+  if (list.includes('*') || list.includes(need)) return true;
+  const [obj, action] = need.split(':');
+  return action === 'read' && list.includes(`${obj}:write`);
+}
+const ORG_PREFIX = 'tok_o_';
+const SUPPORT_PREFIX = 'tok_su_';
+const PREFIX = 'tok_p_';
+const hash = (token: string): string => createHash('sha256').update(token).digest('hex');
+
+export class Tokens {
+  private readonly db: PlatformDb;
+  constructor(stateDir: string) { this.db = openDatabase(stateDir); }
+  private row(h: string): TokenRecord | null {
+    if (!/^[a-f0-9]{64}$/.test(h)) throw new Error('bad token hash');
+    const r = this.db.select().from(tokenRows).where(eq(tokenRows.hash, h)).get() as (typeof tokenRows.$inferSelect) | undefined;
+    return r ? recordOf(r) : null;
+  }
+  /** Mint a token for a person; the token itself is returned once and never stored. */
+  mint(userId: string, name: string, opts: { expiresInDays?: number | null; expiresInHours?: number; scopes?: string[]; orgId?: string; support?: { reason: string; category: string } } = {}): { token: string; record: TokenRecord } {
+    const token = `${opts.support ? SUPPORT_PREFIX : opts.orgId ? ORG_PREFIX : PREFIX}${randomBytes(24).toString('base64url')}`;
+    const days = opts.expiresInDays === undefined ? DEFAULT_TOKEN_DAYS : opts.expiresInDays;
+    const expiresAt = opts.expiresInHours !== undefined ? new Date(Date.now() + opts.expiresInHours * 3600 * 1000).toISOString() : days === null ? null : new Date(Date.now() + days * 24 * 3600 * 1000).toISOString();
+    const record: TokenRecord = { hash: hash(token), userId, name: name.slice(0, 80), createdAt: new Date().toISOString(), last4: token.slice(-4), expiresAt, scopes: opts.scopes ?? ['*'], ...(opts.orgId ? { orgId: opts.orgId } : {}), ...(opts.support ? { support: opts.support } : {}) };
+    this.db.insert(tokenRows).values({ hash: record.hash, userId, name: record.name, createdAt: record.createdAt, last4: record.last4, expiresAt, scopes: record.scopes, orgId: opts.orgId ?? null, support: opts.support ?? null }).run();
+    return { token, record };
+  }
+  static looksLike(token: string): boolean { return token.startsWith(PREFIX) || token.startsWith(ORG_PREFIX) || token.startsWith(SUPPORT_PREFIX); }
+  static isSupportToken(token: string): boolean { return token.startsWith(SUPPORT_PREFIX); }
+  static isOrgToken(token: string): boolean { return token.startsWith(ORG_PREFIX); }
+  /** The person a presented token belongs to, or null; `expired: true` for a token past its time (never touched). When
+   *  it was last used is kept to the minute: a token in constant use is not a write per request. */
+  lookup(token: string): (TokenRecord & { expired?: boolean }) | null {
+    if (!Tokens.looksLike(token)) return null;
+    const record = this.row(hash(token)); if (!record) return null;
+    if (record.expiresAt && Date.parse(record.expiresAt) <= Date.now()) return { ...record, expired: true };
+    const now = new Date();
+    if (!record.lastUsedAt || now.getTime() - Date.parse(record.lastUsedAt) >= 60_000) { this.db.update(tokenRows).set({ lastUsedAt: now.toISOString() }).where(eq(tokenRows.hash, record.hash)).run(); return { ...record, lastUsedAt: now.toISOString() }; }
+    return record;
+  }
+  /** An org's tokens (layer 6), newest last. */
+  listOrg(orgId: string): TokenRecord[] { return (this.db.select().from(tokenRows).where(and(eq(tokenRows.orgId, orgId), isNull(tokenRows.support))).orderBy(asc(tokenRows.createdAt)).all() as Array<typeof tokenRows.$inferSelect>).map(recordOf); }
+  revokeOrg(orgId: string, h: string): TokenRecord | null { const record = this.row(h); if (!record || record.orgId !== orgId) return null; this.db.delete(tokenRows).where(eq(tokenRows.hash, h)).run(); return record; }
+  /** Note the World key made for a token (one per World: a new one replaces the last). */
+  /** Record a World key made for this token, revoked with it: the command's one key per World `/token` hands out
+   *  (`command`, replacing only its own earlier one), or one more made at the key door beside the others. */
+  noteWorldKey(h: string, world: string, keyId: string, command = true): void {
+    this.db.transaction((tx) => {
+      const r = tx.select({ worldKeys: tokenRows.worldKeys }).from(tokenRows).where(eq(tokenRows.hash, h)).get() as { worldKeys: Array<{ world: string; keyId: string; command?: boolean }> | null } | undefined;
+      if (!r) return;
+      tx.update(tokenRows).set({ worldKeys: [...(r.worldKeys ?? []).filter((k) => k.keyId !== keyId && !(command && k.command && k.world === world)), { world, keyId, ...(command ? { command: true } : {}) }] }).where(eq(tokenRows.hash, h)).run();
+    });
+  }
+  list(userId: string): TokenRecord[] { return (this.db.select().from(tokenRows).where(and(eq(tokenRows.userId, userId), isNull(tokenRows.orgId))).orderBy(asc(tokenRows.createdAt)).all() as Array<typeof tokenRows.$inferSelect>).map(recordOf); }
+  /** Revoke one of a person's own tokens: the record it was (its World keys go with it, by the caller), or null. */
+  revoke(userId: string, h: string): TokenRecord | null {
+    // a person's own tokens only: an org's token (its maker's id beside it) is revoked through the org, by an admin now
+    const record = this.row(h); if (!record || record.userId !== userId || record.orgId) return null;
+    this.db.delete(tokenRows).where(eq(tokenRows.hash, h)).run(); return record;
+  }
+}
+
+/** A row as the record the platform reads (absent fields left out, as the JSON records had them). */
+function recordOf(r: typeof tokenRows.$inferSelect): TokenRecord {
+  return { hash: r.hash, userId: r.userId, name: r.name, createdAt: r.createdAt, last4: r.last4, expiresAt: r.expiresAt, ...(r.lastUsedAt ? { lastUsedAt: r.lastUsedAt } : {}), ...(r.scopes ? { scopes: r.scopes } : {}), ...(r.orgId ? { orgId: r.orgId } : {}), ...(r.support ? { support: r.support } : {}), ...(r.worldKeys ? { worldKeys: r.worldKeys } : {}) };
+}

package/src/webhooks.ts

@@ -0,0 +1,85 @@
+// 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';
+import type { AuditEvent } from './audit.ts';
+
+export type WebhookEndpoint = {
+  id: string; url: string; /** `whsec_` + base64 — kept so deliveries can be signed; shown to the person once */ secret: string;
+  events: string[]; description: string; createdAt: string;
+  consecutiveFailures: number; lastFailedAt: string | null; disabledAt: string | null;
+};
+export type Delivery = {
+  id: string; orgId: string; endpointId: string; eventId: string; event: string; body: string;
+  attempt: number; nextAt: string; /** the attempts made, newest last */ attempts: Array<{ at: string; status: number | null; ok: boolean; response: string }>;
+  state: 'pending' | 'delivered' | 'failed';
+};
+
+/** The catalog: the audit's events in dotted form, plus `ping` for the test button. */
+export const WEBHOOK_EVENTS: Readonly<Record<string, string>> = {
+  WORLD_PROVISION: 'world.provisioned', WORLD_DELETE: 'world.deleted', PREVIEW_CREATE: 'preview.created', PREVIEW_DELETE: 'preview.deleted',
+  MEMBER_INVITE: 'member.added', INVITE_REVOKE: 'member.invite_revoked', MEMBER_REMOVE: 'member.removed', MEMBER_ROLE: 'member.role_changed',
+  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: readonly string[] = [...new Set(Object.values(WEBHOOK_EVENTS))].sort();
+export const eventNameFor = (audit: AuditEvent): string | null => WEBHOOK_EVENTS[audit] ?? null;
+export function validEvents(events: unknown): events is string[] { 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: number): number => [30, 120, 600][attempt - 1] ?? 1200;
+
+export const newSecret = (): string => `whsec_${randomBytes(24).toString('base64')}`;
+export const newId = (prefix: string): string => `${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: string, id: string, timestamp: number, body: string): string {
+  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: string, headers: { id: string; timestamp: string; signature: string }, body: string, toleranceSeconds = 300): boolean {
+  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: string): boolean {
+  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: string, allowPrivate: boolean): Promise<string | null> {
+  if (allowPrivate) return null;
+  let host: string; try { host = new URL(url).hostname.replace(/^\[|\]$/g, ''); } catch { return 'not an address'; }
+  let addresses: string[];
+  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: WebhookEndpoint, d: Delivery, fetchImpl: typeof fetch = fetch, allowPrivate = false): Promise<{ status: number | null; ok: boolean; response: string }> {
+  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 as Error).message ?? e).slice(0, 2048) }; }
+  finally { clearTimeout(t); }
+}