@volter/twin-github 0.1.2 → 2.0.0

package/dist/src/npm-registry.js

@@ -0,0 +1,47 @@
+// GITHUB PACKAGES' NPM REGISTRY — npm.pkg.github.com, where `npm publish` puts a package scoped to its owner
+// (docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-npm-registry). A publish is a PUT
+// of the package document (its name, its versions and their tarballs as attachments) at /@owner/name; a first publish
+// makes the package, a later one adds its version, and republishing a version is refused. The REST API reads and
+// deletes what was published (semantics/packages.ts).
+//
+// Where the documentation stops and the twin decides: a published package is private, as GitHub makes a user's new
+// package; the tarball's bytes are not kept.
+import { applyTwinWrite } from '@volter/world-core';
+import { GITHUB_WORLD_USER, githubState, nextSeq } from "./github-twin.js";
+const SERVICE = 'github';
+/** npm.pkg.github.com's publish, or undefined for any other request. */
+export function githubNpmRegistry(flow) {
+    return async (request) => {
+        const m = /^\/@([^/]+)(?:\/|%2[fF])([^/]+)$/.exec(new URL(request.url).pathname);
+        return m && request.method === 'PUT' ? publish(request, decodeURIComponent(m[1]), decodeURIComponent(m[2]), flow) : undefined;
+    };
+}
+/** `npm publish` of a package's versions, as npm.pkg.github.com answers it. */
+async function publish(request, owner, name, flow) {
+    if (owner !== GITHUB_WORLD_USER)
+        return Response.json({ error: `Permission denied: you cannot publish to @${owner}` }, { status: 403 });
+    let doc;
+    try {
+        doc = (await request.json());
+    }
+    catch {
+        return Response.json({ error: 'Invalid package document' }, { status: 400 });
+    }
+    const versions = Object.keys(doc.versions ?? {});
+    if (!versions.length)
+        return Response.json({ error: 'No version to publish' }, { status: 400 });
+    const at = flow.now();
+    const st = githubState(flow.root);
+    const write = (w) => applyTwinWrite(SERVICE, { ...w, occurredAt: at, actor: { kind: 'human', id: owner } }, flow.root);
+    const published = st.packageVersions.filter((v) => v.owner === owner && v.package_type === 'npm' && v.package_name === name).map((v) => v.name);
+    const again = versions.find((v) => published.includes(v));
+    if (again)
+        return Response.json({ error: `You cannot publish over the previously published version ${again}.` }, { status: 409 });
+    if (!st.packages.some((p) => p.owner === owner && p.package_type === 'npm' && p.name === name)) {
+        await write({ operation: 'package.create', subjectType: 'package', subjectId: `package:${nextSeq('package', flow.root)}`, fields: { name, package_type: 'npm', owner, visibility: 'private', created_at: at, updated_at: at } });
+    }
+    for (const version of versions) {
+        await write({ operation: 'package_version.create', subjectType: 'package_version', subjectId: `packageversion:${nextSeq('packageversion', flow.root)}`, fields: { package_name: name, package_type: 'npm', owner, name: version, created_at: at, updated_at: at } });
+    }
+    return Response.json({ ok: true }, { status: 201 });
+}

package/dist/src/screens/app-installation.d.ts

@@ -0,0 +1,3 @@
+import { type Flow } from './oauth.js';
+/** github.com/apps/{slug}/installations/new, or undefined for any other request. */
+export declare function githubAppInstallationFlow(flow: Flow): (request: Request) => Promise<Response | undefined>;

package/dist/src/screens/app-installation.js

@@ -0,0 +1,166 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A GITHUB APP'S INSTALLATION — a hosted flow (docs/contributing/architecture.md, "Screens"): the page at
+// github.com/apps/{slug}/installations/new, held to the round trip GitHub documents
+// (docs.github.com/apps/using-github-apps/installing-a-github-app-from-a-third-party and
+// docs.github.com/apps/creating-github-apps/about-creating-github-apps/about-the-setup-url): an application sends
+// the person who will install it to the page (with an optional `state`); the person picks the account, all of its
+// repositories or only some, sees the permissions and events the app asks for, and installs. GitHub then records
+// the installation, sends the app its `installation` webhook (action `created`), and redirects to the app's setup
+// URL with `installation_id` and `setup_action=install` (and the `state` it was given). An app that asks to
+// authorize its installer (request_oauth_on_install) gets a `code` on that redirect as well, redeemed at
+// /login/oauth/access_token like a consent's (src/screens/oauth.tsx), and GitHub sends the person to its callback
+// URL rather than its setup URL. With no setup URL the person lands on the app's page. The page is authored
+// from @volter/world-ui's pieces under GitHub's skin (oauth.tsx's); nothing of GitHub's page is copied.
+//
+// Where the documentation stops and the twin decides: apps are registered through the twin's door
+// (`POST /_twin/apps`; GitHub's settings UI has no API). The person is who signed in (src/screens/session.tsx); a
+// visitor not signed in is sent to the sign-in first. The accounts offered are the person's own and the organizations they
+// own (an admin membership: an organization's creator is its first admin). The repository picker lists the chosen account's repositories; choosing
+// another account reloads the page for it (a plain form, no script). An account that already has the app is
+// told so and not installed again (GitHub sends that person to the installation's settings page instead).
+import { applyTwinWriteAtomic } from '@volter/world-core';
+import { CONSENT_CSS, flowPage } from '@volter/world-ui';
+import { githubApps, githubState, toGithubAppInstallation } from "../github-twin.js";
+import { emitGithubAppEvent } from "../github-events.js";
+import { errorPage, mintOAuthCode, redirect, SKIN } from "./oauth.js";
+import { signedIn, toSignIn } from "./session.js";
+const SERVICE = 'github';
+const PAGE = /^\/apps\/([^/]+)\/installations\/new$/;
+// The page's own layout over the consent's (a choice of account, a radio pair and a repository list).
+const INSTALL_CSS = `
+.install-section { padding: 12px 0; border-top: 1px solid #d1d9e0; }
+.install-section:first-child { border-top: 0; }
+.install-section h2 { font-size: 14px; margin: 0 0 8px; }
+.install-choice { display: block; padding: 4px 0; }
+.install-choice small { display: block; margin-left: 22px; color: #59636e; }
+.install-repos { list-style: none; margin: 4px 0 0 22px; padding: 0; }
+.install-account { display: flex; gap: 8px; align-items: center; }
+.install-account select { flex: 1; font: inherit; padding: 4px; }
+.install-account button { font: inherit; padding: 4px 12px; border-radius: 6px; border: 1px solid #d1d9e0; background: #f6f8fa; }
+`;
+// GitHub's names for an app's permissions, as its install page lists them (read / read and write / admin).
+const ACCESS = { read: 'Read-only', write: 'Read and write', admin: 'Admin' };
+const TITLES = {
+    contents: 'Contents', metadata: 'Metadata', issues: 'Issues', pull_requests: 'Pull requests', checks: 'Checks', statuses: 'Commit statuses',
+    deployments: 'Deployments', actions: 'Actions', workflows: 'Workflows', administration: 'Administration', members: 'Members', secrets: 'Secrets',
+    environments: 'Environments', pages: 'Pages', packages: 'Packages', repository_hooks: 'Webhooks', security_events: 'Code scanning alerts',
+};
+function permissionsOf(app) {
+    const out = Object.entries({ metadata: 'read', ...app.permissions }).map(([k, v]) => ({
+        title: TITLES[k] ?? k.replace(/_/g, ' ').replace(/^./, (c) => c.toUpperCase()), detail: `${ACCESS[v] ?? v} access`,
+    }));
+    if (app.events.length)
+        out.push({ title: 'Events', detail: app.events.join(', '), help: 'This app will be sent these webhook events.' });
+    return out;
+}
+async function paramsOf(request) {
+    const url = new URL(request.url);
+    const fields = Object.fromEntries(url.searchParams);
+    const repositories = url.searchParams.getAll('repositories');
+    if (request.method !== 'POST')
+        return { fields, repositories };
+    const text = await request.text();
+    if (!text)
+        return { fields, repositories };
+    if ((request.headers.get('content-type') ?? '').includes('json')) {
+        try {
+            for (const [k, v] of Object.entries(JSON.parse(text))) {
+                if (k === 'repositories' && Array.isArray(v))
+                    repositories.push(...v.map(String));
+                else if (v !== undefined && v !== null)
+                    fields[k] = String(v);
+            }
+            return { fields, repositories };
+        }
+        catch { /* read as form fields, as GitHub reads an unparseable body */ }
+    }
+    const form = new URLSearchParams(text);
+    for (const [k, v] of form)
+        if (k !== 'repositories')
+            fields[k] = v;
+    repositories.push(...form.getAll('repositories'));
+    return { fields, repositories };
+}
+/** The accounts the person may install on: their own, then the organizations they own. */
+function accountsOf(login, root) {
+    const st = githubState(root);
+    const owned = st.orgs.filter((o) => st.orgMembers.some((m) => m.org === o.login && m.login === login && m.role === 'admin'));
+    return [{ login, type: 'User' }, ...owned.map((o) => ({ login: o.login, type: 'Organization' }))];
+}
+const reposOf = (account, root) => githubState(root).repos.filter((r) => r.owner === account);
+const appOf = (slug, root) => githubApps(root).find((a) => a.slug === slug);
+const installed = (app, account, root) => githubState(root).appInstallations.some((i) => i.app_slug === app.slug && i.account_login === account);
+function page(app, p, flow, notice) {
+    const login = p.login;
+    const accounts = accountsOf(login, flow.root);
+    const account = accounts.find((a) => a.login === p.target_login) ?? accounts[0];
+    const repos = reposOf(account.login, flow.root);
+    const already = installed(app, account.login, flow.root);
+    const keep = { ...(p.state !== undefined ? { state: p.state } : {}) };
+    const verb = app.request_oauth_on_install ? 'Install & Authorize' : 'Install';
+    return flowPage({
+        title: `Install ${app.name}`,
+        status: notice?.status ?? 200,
+        css: [CONSENT_CSS, SKIN, INSTALL_CSS],
+        body: (_jsxs("main", { className: "consent", children: [_jsxs("div", { className: "consent-badges", "aria-hidden": "true", children: [_jsx("span", { className: "consent-badge", children: app.name.slice(0, 1).toUpperCase() }), _jsx("span", { className: "consent-link" }), _jsx("span", { className: "consent-badge consent-vendor" })] }), _jsx("h1", { className: "consent-heading", children: `Install ${app.name}` }), _jsxs("div", { className: "consent-box", children: [_jsxs("form", { method: "get", action: `/apps/${app.slug}/installations/new`, className: "install-section install-account", children: [Object.entries(keep).map(([name, value]) => _jsx("input", { type: "hidden", name: name, value: value }, name)), _jsx("label", { htmlFor: "target_login", children: "Install on" }), _jsx("select", { id: "target_login", name: "target_login", defaultValue: account.login, children: accounts.map((a) => _jsx("option", { value: a.login, children: a.login }, a.login)) }), _jsx("button", { type: "submit", children: "Switch account" })] }), notice ? _jsx("p", { className: "consent-note", role: "alert", children: notice.message }) : null, already ? (_jsx("p", { className: "install-section", children: `${app.name} is already installed on ${account.login}.` })) : (_jsxs("form", { method: "post", action: `/apps/${app.slug}/installations/new`, className: "consent-form", children: [Object.entries({ ...keep, target_login: account.login }).map(([name, value]) => _jsx("input", { type: "hidden", name: name, value: value }, name)), _jsxs("fieldset", { className: "install-section", children: [_jsx("legend", { children: _jsx("h2", { children: `for these repositories of ${account.login}:` }) }), _jsxs("label", { className: "install-choice", children: [_jsx("input", { type: "radio", name: "repository_selection", value: "all", defaultChecked: true }), " All repositories", _jsx("small", { children: "This applies to all current and future repositories owned by the resource owner." })] }), _jsxs("label", { className: "install-choice", children: [_jsx("input", { type: "radio", name: "repository_selection", value: "selected" }), " Only select repositories", _jsx("small", { children: "Select at least one repository." })] }), _jsx("ul", { className: "install-repos", "aria-label": "Select repositories", children: repos.map((r) => (_jsx("li", { children: _jsxs("label", { children: [_jsx("input", { type: "checkbox", name: "repositories", value: r.name }), " ", r.full_name] }) }, r.full_name))) })] }), _jsxs("div", { className: "install-section", children: [_jsx("h2", { children: "with these permissions:" }), _jsx("ul", { className: "consent-permissions", children: permissionsOf(app).map((perm) => (_jsxs("li", { className: "consent-permission", children: [_jsx("strong", { className: "consent-permission-title", children: perm.title }), " ", _jsx("small", { children: perm.detail })] }, perm.title))) })] }), _jsxs("div", { className: "consent-actions", children: [_jsx("button", { type: "submit", name: "install", value: "0", className: "consent-deny", children: "Cancel" }), _jsx("button", { type: "submit", name: "install", value: "1", className: "consent-allow", children: verb })] })] }))] })] })),
+    });
+}
+/** The person's answer: an installation and the redirect GitHub sends, or back to the app's page. */
+async function install(app, params, flow) {
+    const p = params.fields;
+    const home = `https://github.com/apps/${app.slug}`;
+    if (p.install !== '1')
+        return redirect(home, {});
+    const login = p.login;
+    const account = accountsOf(login, flow.root).find((a) => a.login === (p.target_login ?? login));
+    if (!account)
+        return errorPage(404, 'Not Found');
+    if (installed(app, account.login, flow.root))
+        return page(app, p, flow, { status: 422, message: `${app.name} is already installed on ${account.login}.` });
+    const selection = p.repository_selection === 'selected' ? 'selected' : 'all';
+    const owned = reposOf(account.login, flow.root);
+    const chosen = selection === 'selected' ? owned.filter((r) => params.repositories.includes(r.name) || params.repositories.includes(r.full_name)) : [];
+    if (selection === 'selected' && !chosen.length)
+        return page(app, p, flow, { status: 422, message: 'Select at least one repository.' });
+    const at = flow.now();
+    const fields = {
+        account_login: account.login, account_type: account.type, target_type: account.type, app_id: app.id, app_slug: app.slug,
+        repository_selection: selection, repositories: chosen.map((r) => r.full_name), permissions: { metadata: 'read', ...app.permissions }, events: app.events,
+        created_at: at, updated_at: at,
+    };
+    const { value: id } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const n = resources.filter((r) => r.type === 'app_installation').reduce((m, r) => Math.max(m, Number(/^installation:(\d+)$/.exec(r.id)?.[1] ?? 0)), 0) + 1;
+        return { kind: 'write', value: n, write: { operation: 'app_installation.create', subjectType: 'app_installation', subjectId: `installation:${n}`, fields, occurredAt: at, actor: { kind: 'human', id: login } } };
+    }, flow.root);
+    const made = githubState(flow.root).appInstallations.find((i) => i.id === id);
+    try {
+        await emitGithubAppEvent(app, 'installation', {
+            action: 'created', installation: toGithubAppInstallation(made),
+            repositories: (selection === 'all' ? owned : chosen).map((r) => ({ id: r.id, name: r.name, full_name: r.full_name, private: r.private ?? false })),
+            sender: { login, type: 'User' },
+        }, { occurredAt: at, ...(flow.root !== undefined ? { root: flow.root } : {}) });
+    }
+    catch { /* a delivery failure never fails the installation, as on GitHub */ }
+    const oauth = app.request_oauth_on_install;
+    const target = (oauth ? app.callback_url ?? app.setup_url : app.setup_url) ?? home;
+    const code = oauth && target !== home ? await mintOAuthCode({ client_id: app.client_id, login, scope: '', redirect_uri: target }, flow) : undefined;
+    return target === home ? redirect(home, {}) : redirect(target, { code, installation_id: String(id), setup_action: 'install', state: p.state });
+}
+/** github.com/apps/{slug}/installations/new, or undefined for any other request. */
+export function githubAppInstallationFlow(flow) {
+    return async (request) => {
+        const match = PAGE.exec(new URL(request.url).pathname.replace(/\/+$/, ''));
+        if (!match || (request.method !== 'GET' && request.method !== 'POST'))
+            return undefined;
+        const app = appOf(decodeURIComponent(match[1]), flow.root);
+        if (!app)
+            return errorPage(404, 'Not Found');
+        // the person is the session's, whatever the request names
+        const person = signedIn(request, flow.root);
+        if (!person)
+            return toSignIn(request);
+        const params = await paramsOf(request);
+        params.fields.login = person;
+        return request.method === 'GET' ? page(app, params.fields, flow) : install(app, params, flow);
+    };
+}

package/dist/src/screens/app-manifest.d.ts

@@ -0,0 +1,3 @@
+import { type Flow } from './oauth.js';
+/** github.com's new-app-from-a-manifest page, or undefined for any other request. */
+export declare function githubAppManifestFlow(flow: Flow): (request: Request) => Promise<Response | undefined>;

package/dist/src/screens/app-manifest.js

@@ -0,0 +1,81 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// A GITHUB APP FROM A MANIFEST — a hosted flow (docs/contributing/architecture.md, "Screens"): the page at
+// github.com/settings/apps/new and github.com/organizations/{org}/settings/apps/new, held to the round trip GitHub
+// documents (docs.github.com/apps/sharing-github-apps/registering-a-github-app-from-a-manifest): an application posts
+// a form holding its `manifest` (JSON) to the page, with an optional `state`; the person sees the app it describes
+// and creates it; GitHub registers the app, owned by the organization or the person, and redirects to the manifest's
+// `redirect_url` with a temporary `code` (and the `state`), which the application exchanges within an hour, once, at
+// POST /app-manifests/{code}/conversions (semantics/apps.ts) for the app's id, private key and secrets.
+//
+// Where the documentation stops and the twin decides: the person is who signed in (src/screens/session.tsx), and a
+// visitor not signed in is sent to the sign-in first; only an owner (an admin) of the organization may register an app for it. The app's slug is
+// its name, lower-cased with runs of other characters as hyphens. A manifest the page cannot read, or one with no name
+// or url, is shown as an error rather than registered.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite } from '@volter/world-core';
+import { CONSENT_CSS, flowPage } from '@volter/world-ui';
+import { githubState, registerGithubApp } from "../github-twin.js";
+import { errorPage, redirect, SKIN } from "./oauth.js";
+import { signedIn, toSignIn } from "./session.js";
+const SERVICE = 'github';
+const PAGE = /^\/(?:organizations\/([^/]+)\/)?settings\/apps\/new$/;
+async function fieldsOf(request) {
+    const fields = Object.fromEntries(new URL(request.url).searchParams);
+    if (request.method === 'POST')
+        for (const [k, v] of new URLSearchParams(await request.text()))
+            fields[k] = v;
+    return fields;
+}
+const slugOf = (name) => name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+function confirm(owner, manifest, raw, fields, action) {
+    const permissions = Object.entries(manifest.default_permissions ?? {});
+    return flowPage({
+        title: 'Create GitHub App',
+        css: [CONSENT_CSS, SKIN],
+        body: (_jsxs("main", { className: "consent", children: [_jsxs("h1", { className: "consent-heading", children: ["Create GitHub App for ", _jsx("strong", { children: owner })] }), _jsxs("div", { className: "consent-box", children: [_jsxs("p", { children: [_jsx("strong", { children: manifest.name }), " ", manifest.url ? _jsx("small", { children: manifest.url }) : null] }), manifest.description ? _jsx("p", { className: "consent-note", children: manifest.description }) : null, _jsxs("ul", { className: "consent-permissions", children: [permissions.map(([k, v]) => _jsxs("li", { className: "consent-permission", children: [_jsx("strong", { className: "consent-permission-title", children: k.replace(/_/g, ' ') }), " ", _jsx("small", { children: v })] }, k)), manifest.default_events?.length ? _jsxs("li", { className: "consent-permission", children: [_jsx("strong", { className: "consent-permission-title", children: "Events" }), " ", _jsx("small", { children: manifest.default_events.join(', ') })] }) : null] }), _jsxs("form", { method: "post", action: action, children: [_jsx("input", { type: "hidden", name: "manifest", value: raw }), fields.state !== undefined ? _jsx("input", { type: "hidden", name: "state", value: fields.state }) : null, _jsx("div", { className: "consent-actions", children: _jsxs("button", { type: "submit", name: "create", value: "1", className: "consent-allow", children: ["Create GitHub App for ", owner] }) })] })] })] })),
+    });
+}
+/** github.com's new-app-from-a-manifest page, or undefined for any other request. */
+export function githubAppManifestFlow(flow) {
+    return async (request) => {
+        const path = new URL(request.url).pathname.replace(/\/+$/, '');
+        const match = PAGE.exec(path);
+        if (!match || request.method !== 'POST')
+            return undefined;
+        const login = signedIn(request, flow.root);
+        if (!login)
+            return toSignIn(request);
+        const fields = await fieldsOf(request);
+        const org = match[1] ? decodeURIComponent(match[1]) : undefined;
+        const st = githubState(flow.root);
+        if (org && !st.orgMembers.some((m) => m.org === org && m.login === login && m.role === 'admin' && m.state === 'active'))
+            return errorPage(404, 'Not Found');
+        let manifest;
+        try {
+            manifest = JSON.parse(fields.manifest ?? '');
+        }
+        catch {
+            return errorPage(422, 'The manifest is not valid JSON.');
+        }
+        if (!manifest.name || !manifest.url)
+            return errorPage(422, 'A manifest needs a name and a url.');
+        if (fields.create !== '1')
+            return confirm(org ?? login, manifest, fields.manifest, fields, path);
+        const at = flow.now();
+        const slug = slugOf(manifest.name);
+        const secret = (what) => createHash('sha256').update(`app:${slug}:${what}`).digest('hex');
+        const made = await registerGithubApp({
+            slug, name: manifest.name, owner: org ?? login, description: manifest.description ?? null, url: manifest.url,
+            permissions: manifest.default_permissions ?? {}, events: manifest.default_events ?? [],
+            ...(manifest.setup_url ? { setup_url: manifest.setup_url } : {}), ...(manifest.callback_urls?.[0] ? { callback_url: manifest.callback_urls[0] } : {}),
+            request_oauth_on_install: manifest.request_oauth_on_install === true,
+            ...(manifest.hook_attributes?.url && manifest.hook_attributes.active !== false ? { hook_attributes: { url: manifest.hook_attributes.url }, webhook_secret: secret('webhook').slice(0, 40) } : {}),
+        }, at, flow.root);
+        if (!made.app)
+            return errorPage(422, `An app named ${manifest.name} already exists.`);
+        // the temporary code the application exchanges once, within an hour, for the app's credentials
+        const code = secret(`code:${at}`).slice(0, 20);
+        await applyTwinWrite(SERVICE, { operation: 'app_manifest_code.create', subjectType: 'app_manifest_code', subjectId: `manifestcode:${code}`, fields: { code, app_slug: slug, created_at: at, used: false }, occurredAt: at, actor: { kind: 'human', id: login } }, flow.root);
+        return manifest.redirect_url ? redirect(manifest.redirect_url, { code, state: fields.state }) : redirect(`https://github.com/apps/${slug}`, {});
+    };
+}

package/dist/src/screens/oauth.d.ts

@@ -0,0 +1,15 @@
+/** The scopes a request names, as GitHub keeps them: known, once each, sorted. */
+export declare function normalizeScopes(raw: string | undefined): string[];
+export declare const SKIN = "\nbody { background: #f6f8fa; color: #1f2328; }\n.consent-badge { background: #ffffff; border: 1px solid #d1d9e0; color: #59636e; }\n.consent-vendor { background: #1f2328; }\n.consent-link { border-color: #d1d9e0; }\n.consent-box { background: #ffffff; border-color: #d1d9e0; }\n.consent-who small, .consent-permission summary small, .consent-note { color: #59636e; }\n.consent-actions { border-color: #d1d9e0; }\n.consent-deny { background: #f6f8fa; border-color: #d1d9e0; color: #25292e; }\n.consent-allow { background: #1f883d; border-color: rgba(31,35,40,0.15); color: #ffffff; }\n";
+export type Flow = {
+    root?: string;
+    now: () => string;
+};
+export declare function redirect(to: string, params: Record<string, string | undefined>): Response;
+export declare function errorPage(status: number, message: string): Response;
+/** A code for `client_id`, bound to `login`, the scopes and the redirect_uri, redeemable once at
+ *  /login/oauth/access_token within ten minutes: what a consent issues, and what a GitHub App's
+ *  installation issues when it asks to authorize its installer (src/screens/app-installation.tsx). */
+export declare function mintOAuthCode(p: Record<string, string>, flow: Flow): Promise<string>;
+/** github.com's OAuth paths, or undefined for any other request. */
+export declare function githubOAuthFlow(flow: Flow): (request: Request) => Promise<Response | undefined>;

package/dist/src/screens/oauth.js

@@ -0,0 +1,257 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// GITHUB'S OAUTH WEB FLOW — a hosted flow (docs/contributing/architecture.md, "Screens"): the consent
+// screen at github.com/login/oauth/authorize and the code exchange at github.com/login/oauth/access_token,
+// held to the round trip GitHub documents (docs.github.com/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps):
+// the application sends its user to the consent with client_id, redirect_uri, scope, state and an optional
+// PKCE challenge; the user's answer redirects back with `code` and `state`, or `error=access_denied`; the
+// application exchanges the code once, within ten minutes, for a token scoped as consented, answered in the
+// format its Accept header asks for. The consent is authored from @volter/world-ui's piece under GitHub's
+// skin; nothing of GitHub's page is copied. Consenting is a move no API call makes: the grant it leaves is
+// the user's (writes with the token are theirs, GET /user names them).
+//
+// Where the documentation stops and the twin decides: the World has no OAuth app registry (apps are made in
+// GitHub's settings UI), so any client_id is an app named by its id, and a redirect_uri is required rather
+// than defaulting to a registered callback. The person is who signed in (src/screens/session.tsx); a visitor not
+// signed in is sent to the sign-in first, with the `login` the application suggests prefilled there, as GitHub's
+// `login` parameter does. A PKCE verifier that does not match answers bad_verification_code.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, applyTwinWriteAtomic, twinResources } from '@volter/world-core';
+import { Consent, CONSENT_CSS, flowPage } from '@volter/world-ui';
+import { signedIn, toSignIn } from "./session.js";
+const SERVICE = 'github';
+const CODE_TTL_MS = 10 * 60 * 1000;
+const DOCS = 'https://docs.github.com/apps/managing-oauth-apps/troubleshooting-oauth-app-access-token-request-errors';
+const GROUPS = [
+    { title: 'Repositories', levels: [
+            { scope: 'repo', detail: 'Public and private', help: 'This application will be able to read and write all public and private repository data.' },
+            { scope: 'public_repo', detail: 'Public repositories', help: 'This application will be able to read and write all public repository data.' },
+            { scope: 'repo:status', detail: 'Commit statuses', help: 'This application will be able to read and write commit statuses.' },
+            { scope: 'repo_deployment', detail: 'Deployment statuses', help: 'This application will be able to read and write deployment statuses.' },
+            { scope: 'repo:invite', detail: 'Repository invitations', help: 'This application will be able to accept and decline repository invitations.' },
+            { scope: 'security_events', detail: 'Security events', help: 'This application will be able to read and write security events.' },
+        ] },
+    { title: 'Workflow', levels: [{ scope: 'workflow', detail: 'Update GitHub Action workflow files', help: 'This application will be able to add and update GitHub Actions workflow files.' }] },
+    { title: 'Delete repositories', levels: [{ scope: 'delete_repo', detail: 'Delete repositories', help: 'This application will be able to delete administrable repositories.' }] },
+    { title: 'Organizations and teams', levels: [
+            { scope: 'admin:org', detail: 'Admin access', help: 'This application will be able to fully manage your organizations, their teams and memberships.' },
+            { scope: 'write:org', detail: 'Read and write access', help: 'This application will be able to read and write organization and team membership.' },
+            { scope: 'read:org', detail: 'Read-only access', help: 'This application will be able to read your organization, team membership, and private project boards.' },
+        ] },
+    { title: 'Organization webhooks', levels: [{ scope: 'admin:org_hook', detail: 'Admin access', help: 'This application will be able to manage organization webhooks.' }] },
+    { title: 'Repository webhooks and services', levels: [
+            { scope: 'admin:repo_hook', detail: 'Admin access', help: 'This application will be able to manage repository webhooks and services.' },
+            { scope: 'write:repo_hook', detail: 'Read and write access', help: 'This application will be able to read and write repository webhooks.' },
+            { scope: 'read:repo_hook', detail: 'Read-only access', help: 'This application will be able to read repository webhooks.' },
+        ] },
+    { title: 'Public SSH keys', levels: [
+            { scope: 'admin:public_key', detail: 'Admin access', help: 'This application will be able to fully manage your public SSH keys.' },
+            { scope: 'write:public_key', detail: 'Read and write access', help: 'This application will be able to read and create public SSH keys.' },
+            { scope: 'read:public_key', detail: 'Read-only access', help: 'This application will be able to read your public SSH keys.' },
+        ] },
+    { title: 'GPG keys', levels: [
+            { scope: 'admin:gpg_key', detail: 'Admin access', help: 'This application will be able to fully manage your GPG keys.' },
+            { scope: 'write:gpg_key', detail: 'Read and write access', help: 'This application will be able to read and create GPG keys.' },
+            { scope: 'read:gpg_key', detail: 'Read-only access', help: 'This application will be able to read your GPG keys.' },
+        ] },
+    { title: 'Gists', levels: [{ scope: 'gist', detail: 'Read and write access', help: 'This application will be able to create gists.' }] },
+    { title: 'Notifications', levels: [{ scope: 'notifications', detail: 'Read-only access', help: 'This application will be able to read your notifications.' }] },
+    { title: 'Packages', levels: [
+            { scope: 'delete:packages', detail: 'Delete access', help: 'This application will be able to delete packages.' },
+            { scope: 'write:packages', detail: 'Read and write access', help: 'This application will be able to upload and publish packages.' },
+            { scope: 'read:packages', detail: 'Read-only access', help: 'This application will be able to download and install packages.' },
+        ] },
+    { title: 'Projects', levels: [
+            { scope: 'project', detail: 'Read and write access', help: 'This application will be able to read and write your projects.' },
+            { scope: 'read:project', detail: 'Read-only access', help: 'This application will be able to read your projects.' },
+        ] },
+    { title: 'Codespaces', levels: [{ scope: 'codespace', detail: 'Full control', help: 'This application will be able to create and manage your codespaces.' }] },
+];
+// Personal user data combines what it is given rather than taking the strongest.
+const USER_PARTS = [
+    { scope: 'user:follow', words: 'Follow users' },
+    { scope: 'read:user', words: 'Profile information (read-only)' },
+    { scope: 'user:email', words: 'Email addresses (read-only)' },
+];
+const KNOWN = new Set(['user', ...USER_PARTS.map((p) => p.scope), ...GROUPS.flatMap((g) => g.levels.map((l) => l.scope))]);
+/** The scopes a request names, as GitHub keeps them: known, once each, sorted. */
+export function normalizeScopes(raw) {
+    return [...new Set((raw ?? '').split(/[\s,]+/).filter((s) => KNOWN.has(s)))].sort();
+}
+function permissionsFor(scopes) {
+    const out = [];
+    if (scopes.includes('user'))
+        out.push({ title: 'Personal user data', detail: 'Full access', help: 'This application will be able to read and write all user data.' });
+    else {
+        const parts = USER_PARTS.filter((p) => scopes.includes(p.scope));
+        if (parts.length)
+            out.push({ title: 'Personal user data', detail: parts.map((p) => p.words).join(', '), help: 'This application will be able to read the user data listed.' });
+    }
+    for (const g of GROUPS) {
+        const level = g.levels.find((l) => scopes.includes(l.scope));
+        if (level)
+            out.push({ title: g.title, detail: level.detail, help: level.help });
+    }
+    if (!out.length)
+        out.push({ title: 'Public data only', detail: 'Limited access to your public data', help: 'This application will be able to identify you and read public information.' });
+    return out;
+}
+// GitHub's skin over the consent: Primer's colours and its green primary button.
+export const SKIN = `
+body { background: #f6f8fa; color: #1f2328; }
+.consent-badge { background: #ffffff; border: 1px solid #d1d9e0; color: #59636e; }
+.consent-vendor { background: #1f2328; }
+.consent-link { border-color: #d1d9e0; }
+.consent-box { background: #ffffff; border-color: #d1d9e0; }
+.consent-who small, .consent-permission summary small, .consent-note { color: #59636e; }
+.consent-actions { border-color: #d1d9e0; }
+.consent-deny { background: #f6f8fa; border-color: #d1d9e0; color: #25292e; }
+.consent-allow { background: #1f883d; border-color: rgba(31,35,40,0.15); color: #ffffff; }
+`;
+const LOGIN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
+const parses = (u) => { try {
+    return !!u && !!new URL(u);
+}
+catch {
+    return false;
+} };
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+async function paramsOf(request) {
+    const url = new URL(request.url);
+    const out = Object.fromEntries(url.searchParams);
+    if (request.method !== 'POST')
+        return out;
+    const text = await request.text();
+    if (!text)
+        return out;
+    if ((request.headers.get('content-type') ?? '').includes('json')) {
+        try {
+            for (const [k, v] of Object.entries(JSON.parse(text)))
+                if (v !== undefined && v !== null)
+                    out[k] = String(v);
+            return out;
+        }
+        catch { /* GitHub reads an unparseable body as form fields */ }
+    }
+    return { ...out, ...Object.fromEntries(new URLSearchParams(text)) };
+}
+export function redirect(to, params) {
+    const url = new URL(to);
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined)
+            url.searchParams.set(k, v);
+    return new Response(null, { status: 302, headers: { location: url.toString() } });
+}
+export function errorPage(status, message) {
+    return flowPage({ title: 'GitHub', status, css: [CONSENT_CSS, SKIN], body: _jsx("main", { className: "consent", children: _jsx("h1", { className: "consent-heading", children: message }) }) });
+}
+/** The token answer in the format the Accept header asks for: JSON, XML, or GitHub's default form encoding. */
+function tokenAnswer(request, fields) {
+    const accept = request.headers.get('accept') ?? '';
+    if (accept.includes('application/json'))
+        return Response.json(fields);
+    if (accept.includes('xml'))
+        return new Response(`<OAuth>${Object.entries(fields).map(([k, v]) => `<${k}>${v.replace(/[<>&]/g, '')}</${k}>`).join('')}</OAuth>`, { headers: { 'content-type': 'application/xml; charset=utf-8' } });
+    return new Response(new URLSearchParams(fields).toString(), { headers: { 'content-type': 'application/x-www-form-urlencoded; charset=utf-8' } });
+}
+const tokenError = (request, error, description, anchor) => tokenAnswer(request, { error, error_description: description, error_uri: `${DOCS}#${anchor}` });
+const grantsOf = (root) => twinResources(SERVICE, root).filter((r) => r.type === 'oauth_grant' && r.deleted !== true);
+async function consent(request, flow) {
+    const p = await paramsOf(request);
+    if (!p.client_id)
+        return errorPage(404, 'Not Found');
+    if (!parses(p.redirect_uri))
+        return errorPage(400, 'The redirect_uri is not associated with this application.');
+    const login = signedIn(request, flow.root);
+    if (!login)
+        return toSignIn(request, p.login && LOGIN.test(p.login) ? p.login : undefined);
+    const scopes = normalizeScopes(p.scope);
+    const fields = { client_id: p.client_id, redirect_uri: p.redirect_uri, scope: scopes.join(','), ...(p.state !== undefined ? { state: p.state } : {}), ...(p.code_challenge ? { code_challenge: p.code_challenge, code_challenge_method: p.code_challenge_method ?? 'plain' } : {}) };
+    // GitHub asks once: a user who already granted this app every scope requested goes straight back with a code.
+    const held = grantsOf(flow.root).filter((g) => g.client_id === p.client_id && g.login === login).flatMap((g) => (Array.isArray(g.scopes) ? g.scopes : []));
+    if (held.length && scopes.every((s) => held.includes(s)))
+        return issue(fields, flow);
+    return flowPage({
+        title: `Authorize application`,
+        css: [CONSENT_CSS, SKIN],
+        body: (_jsx(Consent, { heading: `Authorize ${p.client_id}`, app: { name: p.client_id }, request: `wants to access your ${login} account`, permissions: permissionsFor(scopes), action: "/login/oauth/authorize", fields: fields, deny: { name: 'authorize', value: '0', label: 'Cancel' }, allow: { name: 'authorize', value: '1', label: `Authorize ${login}` }, note: `Authorizing will redirect to ${new URL(p.redirect_uri).origin}` })),
+    });
+}
+/** The consenting person's answer: a code for the application, or its refusal. */
+async function answer(request, flow) {
+    const p = await paramsOf(request);
+    if (!p.client_id || !parses(p.redirect_uri))
+        return errorPage(400, 'The redirect_uri is not associated with this application.');
+    if (p.authorize !== '1') {
+        return redirect(p.redirect_uri, { error: 'access_denied', error_description: 'The user has denied your application access.', error_uri: 'https://docs.github.com/apps/managing-oauth-apps/troubleshooting-authorization-request-errors/#access-denied', state: p.state });
+    }
+    const login = signedIn(request, flow.root);
+    if (!login)
+        return toSignIn(request);
+    return issue({ ...p, login, scope: normalizeScopes(p.scope).join(',') }, flow);
+}
+async function issue(p, flow) {
+    const code = await mintOAuthCode(p, flow);
+    return redirect(p.redirect_uri, { code, state: p.state });
+}
+/** A code for `client_id`, bound to `login`, the scopes and the redirect_uri, redeemable once at
+ *  /login/oauth/access_token within ten minutes: what a consent issues, and what a GitHub App's
+ *  installation issues when it asks to authorize its installer (src/screens/app-installation.tsx). */
+export async function mintOAuthCode(p, flow) {
+    const at = flow.now();
+    const { value: code } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const n = resources.filter((r) => r.type === 'oauth_code').length + 1;
+        const code = hex(`oauthcode:${p.client_id}:${p.login}:${at}:${n}`).slice(0, 20);
+        const fields = { code, client_id: p.client_id, login: p.login, scopes: p.scope ? p.scope.split(',') : [], redirect_uri: p.redirect_uri, created_at: at, ...(p.code_challenge ? { code_challenge: p.code_challenge, code_challenge_method: p.code_challenge_method ?? 'plain' } : {}) };
+        return { kind: 'write', value: code, write: { operation: 'oauth_code.create', subjectType: 'oauth_code', subjectId: `oauthcode:${code}`, fields, occurredAt: at, actor: { kind: 'human', id: p.login } } };
+    }, flow.root);
+    return code;
+}
+/** The application's exchange: the code, once, within ten minutes, from the app it was issued to. */
+async function exchange(request, flow) {
+    const p = await paramsOf(request);
+    if (p.grant_type && p.grant_type !== 'authorization_code')
+        return tokenError(request, 'unsupported_grant_type', 'The grant type is not supported by the twin.', 'unsupported-grant-type');
+    if (!p.client_id)
+        return tokenError(request, 'incorrect_client_credentials', 'The client_id and/or client_secret passed are incorrect.', 'incorrect-client-credentials');
+    const at = flow.now();
+    const { value: outcome } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const row = resources.find((r) => r.type === 'oauth_code' && r.code === p.code);
+        const bad = { kind: 'skip', value: { error: ['bad_verification_code', 'The code passed is incorrect or expired.', 'bad-verification-code'] } };
+        if (!p.code || !row || row.used || row.client_id !== p.client_id || Date.parse(at) - Date.parse(row.created_at) > CODE_TTL_MS)
+            return bad;
+        if (p.redirect_uri && p.redirect_uri !== row.redirect_uri)
+            return { kind: 'skip', value: { error: ['redirect_uri_mismatch', 'The redirect_uri MUST match the registered callback URL for this application.', 'redirect-uri-mismatch'] } };
+        if (row.code_challenge) {
+            const verifier = p.code_verifier ?? '';
+            const derived = row.code_challenge_method === 'S256' ? createHash('sha256').update(verifier).digest('base64url') : verifier;
+            if (!verifier || derived !== row.code_challenge)
+                return bad;
+        }
+        return { kind: 'write', value: { code: row }, write: { operation: 'oauth_code.redeem', subjectType: 'oauth_code', subjectId: `oauthcode:${row.code}`, fields: { ...row, used: true }, occurredAt: at, actor: { kind: 'agent' } } };
+    }, flow.root);
+    if ('error' in outcome)
+        return tokenError(request, ...outcome.error);
+    const { code } = outcome;
+    const token = `gho_${hex(`oauth:${code.client_id}:${code.code}`).slice(0, 36)}`;
+    await applyTwinWrite(SERVICE, { operation: 'oauth_grant.create', subjectType: 'oauth_grant', subjectId: `oauthgrant:${token}`, fields: { token, client_id: code.client_id, scopes: code.scopes, login: code.login, created_at: at }, occurredAt: at, actor: { kind: 'agent' } }, flow.root);
+    return tokenAnswer(request, { access_token: token, token_type: 'bearer', scope: code.scopes.join(',') });
+}
+/** github.com's OAuth paths, or undefined for any other request. */
+export function githubOAuthFlow(flow) {
+    return async (request) => {
+        const path = new URL(request.url).pathname.replace(/\/+$/, '');
+        if (path === '/login/oauth/authorize')
+            return authorizePage(request, flow);
+        if (path === '/login/oauth/access_token' && request.method === 'POST')
+            return exchange(request, flow);
+        return undefined;
+    };
+}
+/** The authorize page: the consent it shows (GET) and the person's answer (POST). */
+async function authorizePage(request, flow) {
+    if (request.method === 'GET')
+        return consent(request, flow);
+    if (request.method === 'POST')
+        return answer(request, flow);
+    return undefined;
+}

package/dist/src/screens/session.d.ts

@@ -0,0 +1,8 @@
+import type { Flow } from './oauth.js';
+/** The person the request's session cookie names, or undefined when nobody is signed in. */
+export declare function signedIn(request: Request, root: string | undefined): string | undefined;
+/** Where a page asked for by nobody signed in sends its visitor: the sign-in, returning here after (or to the page a
+ *  door stands in for, `page`), with an account the application suggests prefilled. */
+export declare function toSignIn(request: Request, suggested?: string, page?: string): Response;
+/** github.com's sign-in paths, or undefined for any other request. */
+export declare function githubSessionFlow(flow: Flow): (request: Request) => Promise<Response | undefined>;