@volter/world-platform 2.0.0

package/dist/src/sample.d.ts

@@ -0,0 +1,11 @@
+/** 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 declare const SAMPLE_VENDORS: readonly ["stripe", "slack"];
+export declare const SAMPLE_WORLD = "sample";
+/** 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 declare function seedSample(base: string, token: string, vendors: readonly string[]): Promise<Record<string, {
+    seeded: string[];
+} | {
+    error: string;
+}>>;

package/dist/src/sample.js

@@ -0,0 +1,93 @@
+// 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'];
+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' },
+];
+/** 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, token) {
+    return async (vendor, path, init) => {
+        const headers = { 'x-twins-key': token, authorization: init.auth };
+        let body;
+        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(() => ({})));
+        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) {
+    const found = await call('stripe', `/v1/customers?email=${encodeURIComponent(CUSTOMERS[0].email)}`, { auth: STRIPE });
+    if (found.data?.length)
+        return [];
+    const ids = [];
+    for (const c of CUSTOMERS)
+        ids.push((await call('stripe', '/v1/customers', { auth: STRIPE, form: { name: c.name, email: c.email } })).id);
+    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, 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) {
+    const channel = async (name) => {
+        const made = await call('slack', '/api/conversations.create', { auth: BOT, json: { name } });
+        if (made.ok && made.channel?.id)
+            return made.channel.id;
+        const listed = await call('slack', '/api/conversations.list', { auth: BOT, json: {} });
+        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 } });
+    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 = { 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, token, vendors) {
+    const call = caller(base.replace(/\/+$/, ''), token);
+    const out = {};
+    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.message };
+        }
+    }
+    return out;
+}

package/dist/src/store.d.ts

@@ -0,0 +1,110 @@
+import { type PlatformDb } from './db/open.js';
+import type { Delivery, WebhookEndpoint } from './webhooks.js';
+/** 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 declare const DEFAULT_SECURITY: Security;
+/** 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[];
+};
+export declare function assertName(kind: string, value: string): string;
+export declare class Store {
+    readonly db: PlatformDb;
+    /** The store over the platform's database at `<dir>/platform.db`. */
+    constructor(dir: string);
+    private settings;
+    private patchSettings;
+    /** 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;
+    /** Record a World the org holds; one name once (the primary key refuses a second). */
+    recordWorld(orgId: string, world: OrgWorld): OrgDoc;
+    removeWorld(orgId: string, name: string): OrgDoc;
+    /** Every org the platform holds a record for — the biller's roster. */
+    orgIds(): string[];
+    setSupportAccess(orgId: string, supportAccess: SupportAccess | null): OrgDoc;
+    supportAccessOf(orgId: string): SupportAccess | null;
+    setLabs(orgId: string, patch: {
+        flags?: Record<string, boolean>;
+        earlyAdopter?: boolean;
+    }): OrgDoc;
+    setSecurity(orgId: string, security: Security): OrgDoc;
+    securityOf(orgId: string): Security;
+    webhooksOf(orgId: string): WebhookEndpoint[];
+    /** The org's endpoints, as a whole: those not named go, the named are written. */
+    setWebhooks(orgId: string, list: WebhookEndpoint[]): OrgDoc;
+    updateWebhook(orgId: string, id: string, patch: Partial<WebhookEndpoint>): WebhookEndpoint | null;
+    deliveries(): Delivery[];
+    /** The queue as a whole (the delivery pass's result): kept in the order given. */
+    setDeliveries(list: Delivery[]): void;
+    enqueueDeliveries(items: Delivery[]): void;
+    addSupportRequest(r: SupportRequest): SupportRequest[];
+    private supportRequests;
+    setSupportStatus(id: string, status: SupportRequest['status']): SupportRequest | null;
+    previewsOf(orgId: string): Preview[];
+    setPreviews(orgId: string, previews: Preview[]): void;
+    private metaOf;
+    private setMeta;
+    platform(): PlatformDoc;
+    setPlatform(patch: Partial<PlatformDoc>): PlatformDoc;
+}

package/dist/src/store.js

@@ -0,0 +1,142 @@
+// 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 } from "./db/open.js";
+import { deliveries as deliveryRows, meta, orgSettings, orgWorlds, supportRequests, webhooks as webhookRows } from "./db/schema.js";
+export const DEFAULT_SECURITY = { membersCanInvite: false, membersCanUsePersonalTokens: true, approvedEmailDomains: [] };
+const NAME = /^[a-z0-9][a-z0-9-]{0,38}$/;
+export function assertName(kind, value) {
+    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) => { 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 {
+    db;
+    /** The store over the platform's database at `<dir>/platform.db`. */
+    constructor(dir) { this.db = openDatabase(dir); }
+    settings(orgId) { return this.db.select().from(orgSettings).where(eq(orgSettings.orgId, orgId)).get(); }
+    patchSettings(orgId, patch) {
+        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) {
+        orgIdOf(orgId);
+        const worlds = this.db.select().from(orgWorlds).where(eq(orgWorlds.orgId, orgId)).orderBy(asc(orgWorlds.provisionedAt)).all()
+            .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, world) {
+        try {
+            this.db.insert(orgWorlds).values({ orgId: orgIdOf(orgId), ...world }).run();
+        }
+        catch (e) {
+            if (/UNIQUE|PRIMARY KEY/i.test(String(e.message)))
+                throw new Error(`the org already holds a world named ${world.name}`);
+            throw e;
+        }
+        return this.doc(orgId);
+    }
+    removeWorld(orgId, name) { this.db.delete(orgWorlds).where(and(eq(orgWorlds.orgId, orgIdOf(orgId)), eq(orgWorlds.name, name))).run(); return this.doc(orgId); }
+    /** Every org the platform holds a record for — the biller's roster. */
+    orgIds() {
+        const a = this.db.selectDistinct({ id: orgWorlds.orgId }).from(orgWorlds).all().map((r) => r.id);
+        const b = this.db.select({ id: orgSettings.orgId }).from(orgSettings).all().map((r) => r.id);
+        return [...new Set([...a, ...b])].sort();
+    }
+    setSupportAccess(orgId, supportAccess) { this.patchSettings(orgId, { supportAccess }); return this.doc(orgId); }
+    supportAccessOf(orgId) { const a = this.settings(orgIdOf(orgId))?.supportAccess ?? null; return a && Date.parse(a.until) > Date.now() ? a : null; }
+    setLabs(orgId, patch) {
+        this.db.transaction((tx) => {
+            const s = tx.select().from(orgSettings).where(eq(orgSettings.orgId, orgId)).get();
+            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, security) { this.patchSettings(orgId, { security }); return this.doc(orgId); }
+    securityOf(orgId) { return { ...DEFAULT_SECURITY, ...(this.settings(orgIdOf(orgId))?.security ?? {}) }; }
+    // webhooks (layer 7)
+    webhooksOf(orgId) {
+        return this.db.select().from(webhookRows).where(eq(webhookRows.orgId, orgId)).orderBy(asc(webhookRows.createdAt)).all()
+            .map(({ orgId: _o, ...w }) => w);
+    }
+    /** The org's endpoints, as a whole: those not named go, the named are written. */
+    setWebhooks(orgId, list) {
+        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, id, patch) {
+        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() { return this.db.select().from(deliveryRows).orderBy(asc(deliveryRows.seq)).all().map(({ seq: _s, ...d }) => d); }
+    /** The queue as a whole (the delivery pass's result): kept in the order given. */
+    setDeliveries(list) {
+        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) {
+        if (!items.length)
+            return;
+        this.db.transaction((tx) => {
+            const last = tx.select({ seq: deliveryRows.seq }).from(deliveryRows).orderBy(asc(deliveryRows.seq)).all().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();
+            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) {
+        this.db.transaction((tx) => {
+            tx.insert(supportRequests).values(r).run();
+            const all = tx.select({ id: supportRequests.id }).from(supportRequests).orderBy(asc(supportRequests.at)).all();
+            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();
+    }
+    supportRequests() { return this.db.select().from(supportRequests).orderBy(asc(supportRequests.at)).all(); }
+    setSupportStatus(id, status) {
+        this.db.update(supportRequests).set({ status }).where(eq(supportRequests.id, id)).run();
+        return this.db.select().from(supportRequests).where(eq(supportRequests.id, id)).get() ?? null;
+    }
+    // an org's previews, in its meta row (a handful per World, replaced whole)
+    previewsOf(orgId) { return this.metaOf(`previews:${orgId}`) ?? []; }
+    setPreviews(orgId, previews) { this.setMeta(`previews:${orgId}`, previews); }
+    // the platform's own position
+    metaOf(key) { return (this.db.select().from(meta).where(eq(meta.key, key)).get()?.value) ?? null; }
+    setMeta(key, value) { this.db.insert(meta).values({ key, value }).onConflictDoUpdate({ target: meta.key, set: { value } }).run(); }
+    platform() { return { lastBackupAt: this.metaOf('lastBackupAt'), notice: this.metaOf('notice'), support: this.supportRequests() }; }
+    setPlatform(patch) {
+        if ('lastBackupAt' in patch)
+            this.setMeta('lastBackupAt', patch.lastBackupAt ?? null);
+        if ('notice' in patch)
+            this.setMeta('notice', patch.notice ?? null);
+        return this.platform();
+    }
+}

package/dist/src/tokens.d.ts

@@ -0,0 +1,69 @@
+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 declare const DEFAULT_TOKEN_DAYS = 30;
+export declare const SCOPE_OBJECTS: readonly ["worlds", "orgs", "members", "billing", "tokens", "activity"];
+export declare const SCOPE_ACTIONS: readonly ["read", "write"];
+export declare const ALL_SCOPES: string[];
+/** A scope list is valid when every entry is `*` or `<object>:<action>` from the catalog. */
+export declare function validScopes(scopes: unknown): scopes is string[];
+/** Whether a token's scopes cover a needed `object:action` — `*` covers all, `x:write` covers `x:read`. */
+export declare function hasScope(scopes: string[] | undefined, need: string): boolean;
+export declare class Tokens {
+    private readonly db;
+    constructor(stateDir: string);
+    private row;
+    /** 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;
+    };
+    static looksLike(token: string): boolean;
+    static isSupportToken(token: string): boolean;
+    static isOrgToken(token: string): boolean;
+    /** 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;
+    /** An org's tokens (layer 6), newest last. */
+    listOrg(orgId: string): TokenRecord[];
+    revokeOrg(orgId: string, h: string): TokenRecord | null;
+    /** 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?: boolean): void;
+    list(userId: string): TokenRecord[];
+    /** 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;
+}

package/dist/src/tokens.js

@@ -0,0 +1,96 @@
+// 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 } from "./db/open.js";
+import { tokens as tokenRows } from "./db/schema.js";
+export const DEFAULT_TOKEN_DAYS = 30;
+export const SCOPE_OBJECTS = ['worlds', 'orgs', 'members', 'billing', 'tokens', 'activity'];
+export const SCOPE_ACTIONS = ['read', 'write'];
+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) {
+    return Array.isArray(scopes) && scopes.length > 0 && scopes.every((s) => s === '*' || (typeof s === 'string' && ALL_SCOPES.includes(s)));
+}
+/** Whether a token's scopes cover a needed `object:action` — `*` covers all, `x:write` covers `x:read`. */
+export function hasScope(scopes, need) {
+    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) => createHash('sha256').update(token).digest('hex');
+export class Tokens {
+    db;
+    constructor(stateDir) { this.db = openDatabase(stateDir); }
+    row(h) {
+        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();
+        return r ? recordOf(r) : null;
+    }
+    /** Mint a token for a person; the token itself is returned once and never stored. */
+    mint(userId, name, opts = {}) {
+        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 = { 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) { return token.startsWith(PREFIX) || token.startsWith(ORG_PREFIX) || token.startsWith(SUPPORT_PREFIX); }
+    static isSupportToken(token) { return token.startsWith(SUPPORT_PREFIX); }
+    static isOrgToken(token) { 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) {
+        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) { return this.db.select().from(tokenRows).where(and(eq(tokenRows.orgId, orgId), isNull(tokenRows.support))).orderBy(asc(tokenRows.createdAt)).all().map(recordOf); }
+    revokeOrg(orgId, h) { 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, world, keyId, command = true) {
+        this.db.transaction((tx) => {
+            const r = tx.select({ worldKeys: tokenRows.worldKeys }).from(tokenRows).where(eq(tokenRows.hash, h)).get();
+            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) { return this.db.select().from(tokenRows).where(and(eq(tokenRows.userId, userId), isNull(tokenRows.orgId))).orderBy(asc(tokenRows.createdAt)).all().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, h) {
+        // 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) {
+    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/dist/src/webhooks.d.ts

@@ -0,0 +1,60 @@
+import type { AuditEvent } from './audit.js';
+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 declare const WEBHOOK_EVENTS: Readonly<Record<string, string>>;
+export declare const WEBHOOK_EVENT_NAMES: readonly string[];
+export declare const eventNameFor: (audit: AuditEvent) => string | null;
+export declare function validEvents(events: unknown): events is string[];
+export declare const MAX_ATTEMPTS = 10;
+export declare 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 declare const backoffSeconds: (attempt: number) => number;
+export declare const newSecret: () => string;
+export declare const newId: (prefix: string) => string;
+/** Standard Webhooks: HMAC-SHA256 over `id.timestamp.body` with the secret's base64 decoded, sent as `v1,<base64>`. */
+export declare function sign(secret: string, id: string, timestamp: number, body: string): string;
+/** What a receiver does: recompute and compare (constant time). */
+export declare function verify(secret: string, headers: {
+    id: string;
+    timestamp: string;
+    signature: string;
+}, body: string, toleranceSeconds?: number): boolean;
+/** Whether an address is this machine's, a private network's, link-local or carrier-grade NAT: never a webhook's target. */
+export declare function privateAddress(ip: string): boolean;
+/** 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 declare function refusedEndpoint(url: string, allowPrivate: boolean): Promise<string | 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 declare function attempt(endpoint: WebhookEndpoint, d: Delivery, fetchImpl?: typeof fetch, allowPrivate?: boolean): Promise<{
+    status: number | null;
+    ok: boolean;
+    response: string;
+}>;