@volter/world-platform 2.0.0

package/dist/src/identity.d.ts

@@ -0,0 +1,88 @@
+import { type OpenIdMetadata } from '@volter/identity';
+import type { SignedInPerson } from './directory.js';
+/** The Volter provider's settings (each from its `VOLTER_*` name when absent). */
+export type IdentityOptions = {
+    issuer?: string;
+    clientId?: string;
+    clientSecret?: string;
+};
+/** The access provider a platform signs people in with. */
+export type ProviderOptions = ({
+    kind: 'volter';
+} & IdentityOptions) | {
+    kind: 'oidc';
+    issuer?: string;
+    clientId?: string;
+    clientSecret?: string;
+    name?: string; /** the domains the issuer's organization owns and verified: an address in one counts as verified though the issuer sends no `email_verified` (Entra) */
+    trustEmailDomains?: string[];
+} | {
+    kind: 'github';
+    clientId?: string;
+    clientSecret?: string; /** GitHub's web address (GitHub Enterprise Server's); https://github.com by default */
+    web?: string; /** its REST API; https://api.github.com by default, `<web>/api/v3` for an Enterprise Server */
+    api?: string;
+};
+/** The platform's client at its provider: who it is there, and (Volter) a call through the product door. */
+export type Identity = {
+    kind: 'volter' | 'oidc' | 'github';
+    /** What a person is told they continue with: "Volter", "Google", the operator's name for their issuer. */
+    name: string;
+    issuer: string;
+    clientId: string;
+    clientSecret: string;
+    /** The person's own account page at the provider, when it has one. */
+    account?: string;
+    /** The issuer's discovery document (cached by `@volter/identity`; a failure is asked again). */
+    metadata: () => Promise<OpenIdMetadata>;
+    /** A product-door call with the platform's organizations token (Volter only); 404 answers null, any other refusal throws its words. */
+    call: <T>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, body?: unknown) => Promise<T | null>;
+    /** GitHub's web and API addresses, for the `github` provider. */
+    github?: {
+        web: string;
+        api: string;
+    };
+    /** The domains the operator says the issuer's organization owns (OIDC_TRUST_EMAIL_DOMAINS): an address in one, with no `email_verified`, counts as verified. */
+    trustEmailDomains?: string[];
+};
+export declare function providerClient(opts: ProviderOptions): Identity;
+/** The Volter provider (the settings, else the `VOLTER_*` names). */
+export declare const identityClient: (opts?: IdentityOptions) => Identity;
+export declare const SESSION_COOKIE = "volter_console_session";
+export declare const CALLBACK_PATH = "/-/sign-in/callback";
+export type SessionRecord = {
+    subject: string;
+    email?: string;
+    name?: string;
+    expiresAt: string;
+};
+/** The platform's sessions, by the SHA-256 of the cookie's id, in its database (in memory when it keeps no state). */
+export declare class Sessions {
+    private readonly db;
+    constructor(stateDir?: string);
+    private key;
+    start(person: {
+        subject: string;
+        email?: string;
+        name?: string;
+    }): string;
+    read(sessionId: string): SessionRecord | null;
+    end(sessionId: string): void;
+}
+export declare const sessionIdOf: (request: Request, origin: string) => string | undefined;
+export type Signed = {
+    userId: string;
+    sessionId: string;
+    email?: string;
+    name?: string;
+};
+/** Who a request is: the platform's session its cookie names, while it lasts. */
+export declare function whoIs(sessions: Sessions, request: Request, origin: string): Signed | null;
+/** Where a sign-in may return a person: a path of this platform (its pages, or `/-/…`), never another origin or a scheme. */
+export declare const signInReturn: (next: string | null | undefined) => string | undefined;
+/** Start signing in: the authorization code with PKCE (S256) at the provider. */
+export declare function beginSignIn(identity: Identity, origin: string, next?: string): Promise<Response>;
+/** The issuer's answer: the code traded with the client secret, the id token verified, the session started. */
+export declare function finishSignIn(identity: Identity, sessions: Sessions, origin: string, request: Request, landing: string, seen?: (person: SignedInPerson) => Promise<void>): Promise<Response>;
+/** Sign out: the platform's session ends and its cookie goes. */
+export declare function endSession(sessions: Sessions, origin: string, request: Request, landing: string): Response;

package/dist/src/identity.js

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

package/dist/src/labs.d.ts

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

package/dist/src/labs.js

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

package/dist/src/mail.d.ts

@@ -0,0 +1,16 @@
+export type Mail = {
+    to: string[];
+    subject: string;
+    text: string;
+};
+export type Mailer = {
+    send: (mail: Mail) => Promise<{
+        id: string | null;
+    }>;
+    from: string;
+};
+export declare function mailer(opts?: {
+    apiKey?: string;
+    from?: string;
+    log?: (line: string) => void;
+}): Mailer;

package/dist/src/mail.js

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

package/dist/src/pages.d.ts

@@ -0,0 +1,15 @@
+import { RESERVED_ORG_NAMES } from '../client/reserved.js';
+export { RESERVED_ORG_NAMES };
+export type Pages = {
+    handle: (request: Request) => Promise<Response | null>;
+};
+/** The platform's pages: `GET /-/app.js` (the client), `GET /-/styles.css` (the kit's, then the platform's),
+ *  `GET /-/brand/*` (the brand's tokens and faces) and the shell for any other GET outside `/-/` and `/.well-known/`;
+ *  null for anything else, which is a door's. */
+export declare function createPages(): Pages;
+/** A page that is one card, rendered on the server with the kit's styles: the command's approval, a refusal, a notice.
+ *  `inner` is HTML the caller has escaped. `csp` replaces the default policy (no script at all). */
+export declare function pageShell(title: string, inner: string, opts?: {
+    csp?: string;
+    status?: number;
+}): Response;

package/dist/src/pages.js

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