@volter/twin-github 0.1.2 → 2.0.0

package/dist/src/screens/session.js

@@ -0,0 +1,159 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// GITHUB'S SIGN-IN — the door before every github.com page (docs/contributing/architecture.md, "Who is on a screen"):
+// github.com/login shows the form, which posts to /session; the right password for the account signs its person in, and
+// GitHub's session cookies (`user_session`, `logged_in`, `dotcom_user`) name them to every page after. A page asked for by nobody signed in sends its visitor to /login with `return_to`, and the sign-in
+// returns them there. Built from @volter/world-ui's sign-in piece under GitHub's skin; nothing of GitHub's page is copied.
+//
+// A person with two-factor authentication (POST /_twin/users/:login/two-factor, standing in for GitHub's settings page)
+// signs in in two steps, as GitHub's docs say (docs.github.com/authentication/securing-your-account-with-two-factor-
+// authentication-2fa/accessing-github-using-two-factor-authentication: "you'll need to provide an authentication code"
+// after the password): the right password sets no session but sends them to GitHub's two-factor page
+// (/sessions/two-factor/app), whose form posts the code their TOTP app shows (`app_otp`) to /sessions/two-factor; the
+// right code sets the session and returns them to return_to, a wrong one shows the page again with GitHub's message.
+// Which person is between the two steps rides GitHub's own session cookie (`_gh_sess`). Mandatory 2FA
+// (docs.github.com/authentication/securing-your-account-with-two-factor-authentication-2fa/about-mandatory-two-factor-
+// authentication) is the person's to turn on in the World; the twin does not enrol anyone.
+//
+// Where GitHub's documentation stops and the twin decides: a person's password is what the World gave them
+// (`POST /_twin/users/:login/password`; GitHub's sign-up and password pages are not modelled), an account is named by
+// its login (not its email), a refused sign-in shows the form again with GitHub's message (answered 200), a code is
+// taken for the current 30-second step or the one before (RFC 6238's one step of drift) and never twice, a pending
+// two-factor sign-in does not expire, and a session does not end: no person of a World signs out yet, and signing out is built when one does.
+import { createHash } from 'node:crypto';
+import { applyTwinWriteAtomic, twinResources } from '@volter/world-core';
+import { cookieOf, flowPage, SignIn, SignInCode, SIGN_IN_CSS } from '@volter/world-ui';
+import { passwordHash, totpCode, totpStep } from "../github-twin.js";
+const SERVICE = 'github';
+const hex = (s) => createHash('sha256').update(s).digest('hex');
+// GitHub's skin over the sign-in: Primer's colours and its green primary button.
+const SKIN = `
+body { background: #f6f8fa; color: #1f2328; }
+.sign-in-mark { background: #1f2328; }
+.sign-in-error { background: #ffebe9; border-color: rgba(255,129,130,0.4); color: #1f2328; }
+.sign-in-box { background: #ffffff; border-color: #d1d9e0; }
+.sign-in-box input[type=text], .sign-in-box input[type=password] { border-color: #d1d9e0; }
+.sign-in-hint { color: #59636e; }
+.sign-in-submit { background: #1f883d; border-color: rgba(31,35,40,0.15); color: #ffffff; }
+`;
+/** The person the request's session cookie names, or undefined when nobody is signed in. */
+export function signedIn(request, root) {
+    const token = cookieOf(request, 'user_session');
+    if (!token)
+        return undefined;
+    const session = twinResources(SERVICE, root).find((r) => r.type === 'user_session' && r.token === token && r.deleted !== true);
+    return session ? String(session.login) : 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 function toSignIn(request, suggested, page) {
+    const url = new URL(request.url);
+    return new Response(null, { status: 302, headers: { location: `/login?return_to=${encodeURIComponent(page ?? url.pathname + url.search)}${suggested ? `&login=${encodeURIComponent(suggested)}` : ''}` } });
+}
+/** A return_to GitHub follows: a path on github.com, never another site. */
+const returnTo = (raw) => (raw && raw.startsWith('/') && !raw.startsWith('//') ? raw : '/');
+function page(fields, error) {
+    return flowPage({
+        title: 'Sign in to GitHub · GitHub',
+        css: [SIGN_IN_CSS, SKIN],
+        body: (_jsx(SignIn, { heading: "Sign in to GitHub", action: "/session", fields: { return_to: fields.return_to }, account: { name: 'login', label: 'Username or email address', ...(fields.login ? { value: fields.login } : {}) }, password: { name: 'password', label: 'Password' }, submit: "Sign in", ...(error ? { error } : {}) })),
+    });
+}
+async function formOf(request) {
+    return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+async function signIn(request, flow) {
+    const f = await formOf(request);
+    const login = (f.login ?? '').trim();
+    const back = returnTo(f.return_to);
+    const credential = twinResources(SERVICE, flow.root).find((r) => r.type === 'user_credential' && String(r.login).toLowerCase() === login.toLowerCase() && r.deleted !== true);
+    // GitHub names neither which half was wrong
+    if (!login || !credential || credential.hash !== passwordHash(String(credential.login), f.password ?? ''))
+        return page({ return_to: back, login }, 'Incorrect username or password.');
+    const person = String(credential.login);
+    return twoFactorOf(person, flow.root) ? askSecondFactor(person, back, flow) : signInWithPasswordOnly(person, back, flow);
+}
+/** The password was right; GitHub asks a person with two-factor authentication for the second factor on a page of its own. */
+async function askSecondFactor(person, back, flow) {
+    const at = flow.now();
+    const { value: pending } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const n = resources.filter((r) => r.type === 'pending_sign_in').length + 1;
+        const pending = hex(`pending:${person}:${at}:${n}`).slice(0, 48);
+        return { kind: 'write', value: pending, write: { operation: 'pending_sign_in.create', subjectType: 'pending_sign_in', subjectId: `pending:${pending}`, fields: { token: pending, login: person, return_to: back, created_at: at }, occurredAt: at, actor: { kind: 'human', id: person } } };
+    }, flow.root);
+    const headers = new Headers({ location: '/sessions/two-factor/app' });
+    headers.append('set-cookie', `_gh_sess=${pending}; path=/; HttpOnly; Secure; SameSite=Lax`);
+    return new Response(null, { status: 302, headers });
+}
+/** A person without two-factor authentication: the right password signs them in. */
+function signInWithPasswordOnly(person, back, flow) {
+    return startSession(person, back, flow);
+}
+/** The person's two-factor secret, or undefined when they sign in with a password alone. */
+function twoFactorOf(login, root) {
+    const f = twinResources(SERVICE, root).find((r) => r.type === 'user_two_factor' && String(r.login).toLowerCase() === login.toLowerCase() && r.deleted !== true);
+    return f ? { secret: String(f.secret), ...(typeof f.last_step === 'number' ? { last_step: f.last_step } : {}) } : undefined;
+}
+/** The sign-in waiting on its second factor that the request's `_gh_sess` cookie names. */
+function pendingOf(request, root) {
+    const token = cookieOf(request, '_gh_sess');
+    if (!token)
+        return undefined;
+    const p = twinResources(SERVICE, root).find((r) => r.type === 'pending_sign_in' && r.token === token && r.deleted !== true && r.used !== true);
+    return p ? { token, login: String(p.login), return_to: returnTo(String(p.return_to)) } : undefined;
+}
+function codePage(error) {
+    return flowPage({
+        title: 'Two-factor authentication · GitHub',
+        css: [SIGN_IN_CSS, SKIN],
+        body: (_jsx(SignInCode, { heading: "Two-factor authentication", hint: "Open your two-factor authenticator (TOTP) app or browser extension to view your authentication code.", action: "/sessions/two-factor", fields: {}, code: { name: 'app_otp', label: 'Authentication code' }, submit: "Verify", ...(error ? { error } : {}) })),
+    });
+}
+async function verifyCode(request, flow) {
+    const pending = pendingOf(request, flow.root);
+    // nobody half signed in: GitHub starts them at the sign-in again
+    if (!pending)
+        return new Response(null, { status: 302, headers: { location: '/login' } });
+    const f = await formOf(request);
+    const factor = twoFactorOf(pending.login, flow.root);
+    const code = (f.app_otp ?? '').replace(/\s+/g, '');
+    const now = totpStep(flow.now());
+    const step = factor ? [now, now - 1].find((s) => (factor.last_step === undefined || s > factor.last_step) && totpCode(factor.secret, s) === code) : undefined;
+    if (step === undefined)
+        return codePage('Two-factor authentication failed.');
+    const at = flow.now();
+    await applyTwinWriteAtomic(SERVICE, () => ({ kind: 'write', value: undefined, write: { operation: 'user_two_factor.use', subjectType: 'user_two_factor', subjectId: `twofactor:${pending.login.toLowerCase()}`, fields: { last_step: step }, occurredAt: at, actor: { kind: 'human', id: pending.login } } }), flow.root);
+    await applyTwinWriteAtomic(SERVICE, () => ({ kind: 'write', value: undefined, write: { operation: 'pending_sign_in.complete', subjectType: 'pending_sign_in', subjectId: `pending:${pending.token}`, fields: { used: true }, occurredAt: at, actor: { kind: 'human', id: pending.login } } }), flow.root);
+    const answer = await startSession(pending.login, pending.return_to, flow);
+    answer.headers.append('set-cookie', '_gh_sess=; path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax');
+    return answer;
+}
+/** The person is signed in: GitHub's session cookies, and back to where they were going. */
+async function startSession(person, back, flow) {
+    const at = flow.now();
+    const { value: token } = await applyTwinWriteAtomic(SERVICE, (resources) => {
+        const n = resources.filter((r) => r.type === 'user_session').length + 1;
+        const token = hex(`session:${person}:${at}:${n}`).slice(0, 48);
+        return { kind: 'write', value: token, write: { operation: 'user_session.create', subjectType: 'user_session', subjectId: `session:${token}`, fields: { token, login: person, created_at: at }, occurredAt: at, actor: { kind: 'human', id: person } } };
+    }, flow.root);
+    const headers = new Headers({ location: back });
+    headers.append('set-cookie', `user_session=${token}; path=/; HttpOnly; Secure; SameSite=Lax`);
+    headers.append('set-cookie', 'logged_in=yes; path=/; Secure; SameSite=Lax');
+    headers.append('set-cookie', `dotcom_user=${person}; path=/; Secure; SameSite=Lax`);
+    return new Response(null, { status: 302, headers });
+}
+/** github.com's sign-in paths, or undefined for any other request. */
+export function githubSessionFlow(flow) {
+    return async (request) => {
+        const url = new URL(request.url);
+        const path = url.pathname.replace(/\/+$/, '');
+        if (path === '/login' && request.method === 'GET')
+            return page({ return_to: returnTo(url.searchParams.get('return_to') ?? undefined), ...(url.searchParams.get('login') ? { login: url.searchParams.get('login') } : {}) });
+        if (path === '/session' && request.method === 'POST')
+            return signIn(request, flow);
+        if (path === '/sessions/two-factor/app' && request.method === 'GET')
+            return pendingOf(request, flow.root) ? codePage() : new Response(null, { status: 302, headers: { location: '/login' } });
+        if (path === '/sessions/two-factor' && request.method === 'POST')
+            return verifyCode(request, flow);
+        return undefined;
+    };
+}

package/dist/src/semantics/actions.d.ts

@@ -0,0 +1,2 @@
+import type { Semantics } from '@volter/world-core';
+export declare function actionsSemantics(): Record<string, Semantics>;

package/dist/src/semantics/actions.js

@@ -0,0 +1,413 @@
+// GitHub's Actions family: workflows, their runs and jobs (dispatch, rerun, cancel, the reviews of
+// gated environments), repository and organization secrets and variables, caches and artifacts. No
+// runner executes anything (real CI is the Actions non-goal): a dispatched run is queued and moves
+// only by these operations and the twin's runner door. List answers wrap their items in a named
+// array beside total_count, as GitHub's do.
+import { createHash } from 'node:crypto';
+import { GITHUB_WORLD_USER, githubNotFound, hasBareRepo, paginate, resolvePlaneRef, toGithubActionsArtifact, toGithubActionsCache, toGithubActionsSecret, toGithubActionsVariable, toGithubEnvironment, toGithubJob, toGithubWorkflow, toGithubWorkflowRun, toSimpleUser, } from "../github-twin.js";
+import { actionsCheckRun, canWrite, queueJobs, queueRun } from "./push-reactions.js";
+import { gh, put, send } from "./shared.js";
+const params = (query) => new URLSearchParams((query ?? '').replace(/^\?/, ''));
+/** A workflow named by its numeric id or its file path (or the path's last segment). */
+/** Runs as GitHub lists them: the most recently created first. */
+const newestFirst = (runs) => runs.map((r, i) => [r, i]).sort((a, b) => String(b[0].created_at ?? '').localeCompare(String(a[0].created_at ?? '')) || b[1] - a[1]).map(([r]) => r);
+function workflowOf(st, repo, key) {
+    return st.workflows.filter((w) => w.repository === repo).find((w) => String(w.id) === key || w.path === key || w.path.endsWith(`/${key}`));
+}
+const runOf = (ctx) => {
+    const { repo, seg, state } = gh(ctx);
+    const id = Number(decodeURIComponent(seg[5]));
+    const st = state();
+    return { id, st, run: st.workflowRuns.find((r) => r.repository === repo && r.id === id) };
+};
+const missing = (ctx, resource, fields) => ctx.reply({ message: 'Validation Failed', errors: fields.map((field) => ({ resource, field, code: 'missing_field' })) }, 422);
+function envScope(ctx) {
+    const { repo, seg } = gh(ctx);
+    return { scope: 'env', container: `${repo}:${decodeURIComponent(seg[4])}`, ...(seg[6] ? { name: decodeURIComponent(seg[6]) } : {}) };
+}
+function repoScope(ctx) {
+    const { repo, seg } = gh(ctx);
+    return { scope: 'repo', container: repo, ...(seg[5] ? { name: decodeURIComponent(seg[5]) } : {}) };
+}
+/** The org scope as the legacy reads named it (decoded) … */
+function orgReadScope(ctx) {
+    const { seg } = gh(ctx);
+    return { scope: 'org', container: decodeURIComponent(seg[1]), ...(seg[4] ? { name: decodeURIComponent(seg[4]) } : {}) };
+}
+/** … and as its writes did (the org segment as sent). */
+function orgWriteScope(ctx) {
+    const { seg } = gh(ctx);
+    return { scope: 'org', container: String(seg[1]), ...(seg[4] ? { name: decodeURIComponent(seg[4]) } : {}) };
+}
+const listSecrets = (scopeOf) => async (ctx) => {
+    const { scope, container } = scopeOf(ctx);
+    const { query, state } = gh(ctx);
+    const inScope = state().actionsSecrets.filter((s) => s.scope === scope && s.container === container);
+    return ctx.reply({ total_count: inScope.length, secrets: paginate(inScope, query).map(toGithubActionsSecret) });
+};
+const getSecret = (scopeOf) => async (ctx) => {
+    const { scope, container, name } = scopeOf(ctx);
+    const s = gh(ctx).state().actionsSecrets.find((x) => x.scope === scope && x.container === container && x.name === name);
+    return send(ctx, s ? { status: 200, body: toGithubActionsSecret(s) } : githubNotFound());
+};
+// Create or update a secret (201 new, 204 existing). The encrypted value is accepted but never
+// stored: the twin keeps nothing secret.
+const putSecret = (scopeOf) => async (ctx) => {
+    const { scope, container, name } = scopeOf(ctx);
+    const { occurredAt, state } = gh(ctx);
+    const prior = state().actionsSecrets.find((s) => s.scope === scope && s.container === container && s.name === name);
+    const existed = !!prior;
+    // Rewriting a secret moves updated_at; it was created when first written.
+    await put(ctx, { operation: 'actions_secret.upsert', subjectType: 'actions_secret', subjectId: `secret:${scope}:${container}#${name}`, fields: { scope, container, name, created_at: prior?.created_at ?? occurredAt, updated_at: occurredAt, ...(scope === 'org' ? { visibility: String(gh(ctx).body.visibility ?? prior?.visibility ?? 'private') } : {}) } });
+    return send(ctx, { status: existed ? 204 : 201, body: undefined });
+};
+const deleteSecret = (scopeOf) => async (ctx) => {
+    const { scope, container, name } = scopeOf(ctx);
+    if (!gh(ctx).state().actionsSecrets.find((s) => s.scope === scope && s.container === container && s.name === name))
+        return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'actions_secret.delete', subjectType: 'actions_secret', subjectId: `secret:${scope}:${container}#${name}`, fields: { deleted: true, scope, container, name } });
+    return send(ctx, { status: 204, body: undefined });
+};
+const listVariables = (scopeOf) => async (ctx) => {
+    const { scope, container } = scopeOf(ctx);
+    const { query, state } = gh(ctx);
+    const inScope = state().actionsVariables.filter((v) => v.scope === scope && v.container === container);
+    return ctx.reply({ total_count: inScope.length, variables: paginate(inScope, query).map(toGithubActionsVariable) });
+};
+const getVariable = (scopeOf) => async (ctx) => {
+    const { scope, container, name } = scopeOf(ctx);
+    const v = gh(ctx).state().actionsVariables.find((x) => x.scope === scope && x.container === container && x.name === name);
+    return send(ctx, v ? { status: 200, body: toGithubActionsVariable(v) } : githubNotFound());
+};
+// create (201); a name the scope already holds is a conflict
+const createVariable = (scopeOf) => async (ctx) => {
+    const { scope, container } = scopeOf(ctx);
+    const { body, occurredAt, state } = gh(ctx);
+    const absent = ['name', 'value'].filter((k) => body[k] === undefined);
+    if (absent.length)
+        return missing(ctx, 'Variable', absent);
+    const name = String(body.name);
+    if (state().actionsVariables.some((v) => v.scope === scope && v.container === container && v.name === name))
+        return ctx.reply({ message: 'Variable already exists' }, 409);
+    await put(ctx, { operation: 'actions_variable.create', subjectType: 'actions_variable', subjectId: `variable:${scope}:${container}#${name}`, fields: { scope, container, name, value: String(body.value), created_at: occurredAt, updated_at: occurredAt, ...(scope === 'org' ? { visibility: String(body.visibility ?? 'private') } : {}) } });
+    return send(ctx, { status: 201, body: undefined });
+};
+const deleteVariable = (scopeOf) => async (ctx) => {
+    const { scope, container, name } = scopeOf(ctx);
+    if (!gh(ctx).state().actionsVariables.find((v) => v.scope === scope && v.container === container && v.name === name))
+        return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'actions_variable.delete', subjectType: 'actions_variable', subjectId: `variable:${scope}:${container}#${name}`, fields: { deleted: true, scope, container, name } });
+    return send(ctx, { status: 204, body: undefined });
+};
+/** Disabling and enabling a workflow are its moves (manifest.ts); asking for the state it is already in answers
+ *  as done, and moves nothing. */
+const toggleWorkflow = (to, operation) => async (ctx) => {
+    const { repo, seg, state, occurredAt } = gh(ctx);
+    const wf = workflowOf(state(), repo, decodeURIComponent(seg[5]));
+    if (!wf)
+        return send(ctx, githubNotFound());
+    const refused = ctx.legal('workflow', 'state', operation, wf.state, to, String(wf.id));
+    if (refused)
+        return ctx.refuse(refused);
+    await put(ctx, { operation: `workflow.${to === 'active' ? 'enable' : 'disable'}`, subjectType: 'workflow', subjectId: `workflow:${wf.id}`, fields: { repository: wf.repository, name: wf.name, path: wf.path, state: to, created_at: wf.created_at, updated_at: occurredAt } });
+    return send(ctx, { status: 204, body: undefined });
+};
+export function actionsSemantics() {
+    const actionsListRepoWorkflows = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const inRepo = state().workflows.filter((w) => w.repository === repo);
+        return ctx.reply({ total_count: inRepo.length, workflows: paginate(inRepo, query).map(toGithubWorkflow) });
+    };
+    const actionsGetWorkflow = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const wf = workflowOf(state(), repo, decodeURIComponent(seg[5]));
+        return send(ctx, wf ? { status: 200, body: toGithubWorkflow(wf) } : githubNotFound());
+    };
+    const actionsGetWorkflowRun = async (ctx) => {
+        const { run } = runOf(ctx);
+        return send(ctx, run ? { status: 200, body: toGithubWorkflowRun(run, runOf(ctx).st) } : githubNotFound());
+    };
+    const actionsListJobsForWorkflowRun = async (ctx) => {
+        const { id, st, run } = runOf(ctx);
+        if (!run)
+            return send(ctx, githubNotFound());
+        const { repo, query } = gh(ctx);
+        const inRun = st.jobs.filter((j) => j.repository === repo && j.run_id === id);
+        return ctx.reply({ total_count: inRun.length, jobs: paginate(inRun, query).map(toGithubJob) });
+    };
+    const actionsGetReviewsForRun = async (ctx) => {
+        const { st, run } = runOf(ctx);
+        if (!run)
+            return send(ctx, githubNotFound());
+        const { repo } = gh(ctx);
+        return ctx.reply((run.approvals ?? []).map((a) => {
+            const env = st.environments.find((e) => e.repository === repo && e.name === a.environment);
+            return { environments: env ? [{ id: toGithubEnvironment(env).id, name: env.name, url: toGithubEnvironment(env).url, html_url: toGithubEnvironment(env).html_url }] : [], state: a.state, comment: a.comment, user: toSimpleUser(a.user_login, 'User') };
+        }));
+    };
+    const actionsDownloadWorkflowRunLogs = async (ctx) => {
+        const { id, run } = runOf(ctx);
+        if (!run)
+            return send(ctx, githubNotFound());
+        return ctx.reply({ location: `https://pipelines.actions.githubusercontent.com/${gh(ctx).repo}/runs/${id}/logs` }, 302);
+    };
+    const actionsGetJobForWorkflowRun = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const id = Number(decodeURIComponent(seg[5]));
+        const job = state().jobs.find((j) => j.repository === repo && j.id === id);
+        return send(ctx, job ? { status: 200, body: toGithubJob(job) } : githubNotFound());
+    };
+    const actionsCreateWorkflowDispatch = async (ctx) => {
+        const { repo, seg, body, caller, root, state } = gh(ctx);
+        const st = state();
+        const wf = workflowOf(st, repo, decodeURIComponent(seg[5]));
+        if (!wf)
+            return send(ctx, githubNotFound());
+        if (!body.ref)
+            return missing(ctx, 'WorkflowDispatch', ['ref']);
+        const ref = String(body.ref);
+        // head_sha: the commit the ref names, resolved through the git plane (an annotated tag peels to its commit) when the
+        // repository has history there, where GitHub refuses a ref it cannot find; a repository known only through the API
+        // keeps a deterministic stand-in derived from repo+ref+run.
+        const plane = hasBareRepo(repo, root);
+        const planeSha = plane ? await resolvePlaneRef(repo, ref, st.repos.find((r) => r.full_name === repo)?.default_branch ?? 'main', root) : null;
+        if (plane && !planeSha)
+            return ctx.reply({ message: `No ref found for: ${ref}`, documentation_url: 'https://docs.github.com/rest/actions/workflows#create-a-workflow-dispatch-event' }, 422);
+        const runs = st.workflowRuns.filter((r) => r.repository === repo && r.workflow_id === wf.id).length;
+        const headSha = planeSha ?? createHash('sha256').update(`${repo}:${ref}:${runs + 1}`).digest('hex').slice(0, 40);
+        await queueRun(ctx, st, repo, wf, ref, headSha, 'workflow_dispatch', caller);
+        return send(ctx, { status: 204, body: undefined });
+    };
+    const actionsReviewPendingDeploymentsForRun = async (ctx) => {
+        const { id, st, run } = runOf(ctx);
+        if (!run)
+            return send(ctx, githubNotFound());
+        const { repo, body, occurredAt, caller } = gh(ctx);
+        const verdict = String(body.state ?? '');
+        if (verdict !== 'approved' && verdict !== 'rejected')
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PendingDeployment', field: 'state', code: 'invalid' }] }, 422);
+        const ids = Array.isArray(body.environment_ids) ? body.environment_ids.map(Number) : [];
+        const envs = st.environments.filter((e) => e.repository === repo && ids.includes(Number(toGithubEnvironment(e).id)));
+        if (!ids.length || envs.length !== ids.length)
+            return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PendingDeployment', field: 'environment_ids', code: 'invalid' }] }, 422);
+        if (!caller || envs.some((e) => !(e.reviewers ?? []).includes(caller)))
+            return ctx.reply({ message: 'You are not a required reviewer of every environment named', documentation_url: 'https://docs.github.com/rest/actions/workflow-runs#review-pending-deployments-for-a-workflow-run' }, 403);
+        const approvals = [...(run.approvals ?? []), ...envs.map((e) => ({ environment: e.name, state: verdict, comment: String(body.comment ?? ''), user_login: caller, at: occurredAt }))];
+        await put(ctx, { operation: 'workflow_run.review', subjectType: 'workflow_run', subjectId: `run:${id}`, fields: { ...run, approvals, updated_at: occurredAt } });
+        return ctx.reply([]);
+    };
+    const actionsReRunWorkflow = async (ctx) => {
+        const { id, run } = runOf(ctx);
+        if (!run)
+            return send(ctx, githubNotFound());
+        const { repo, occurredAt, state } = gh(ctx);
+        const runFields = { repository: repo, workflow_id: run.workflow_id, name: run.name, run_number: run.run_number, event: run.event, status: 'queued', conclusion: null, head_sha: run.head_sha, head_branch: run.head_branch, created_at: run.created_at, updated_at: occurredAt };
+        await put(ctx, { operation: 'workflow_run.rerun', subjectType: 'workflow_run', subjectId: `run:${id}`, fields: runFields });
+        for (const job of state().jobs.filter((j) => j.repository === repo && j.run_id === id)) {
+            const jobFields = { run_id: id, repository: repo, name: job.name, status: 'queued', conclusion: null, head_sha: job.head_sha, steps: job.steps.map((s) => ({ ...s, status: 'queued', conclusion: null })) };
+            await put(ctx, { operation: 'workflow_job.rerun', subjectType: 'workflow_job', subjectId: `job:${job.id}`, fields: jobFields });
+            await put(ctx, actionsCheckRun(job, 'queued', null, occurredAt));
+        }
+        return ctx.reply({}, 201);
+    };
+    const actionsCancelWorkflowRun = async (ctx) => {
+        const { id, run } = runOf(ctx);
+        if (!run)
+            return send(ctx, githubNotFound());
+        const { repo, occurredAt, state } = gh(ctx);
+        const runFields = { repository: repo, workflow_id: run.workflow_id, name: run.name, run_number: run.run_number, event: run.event, status: 'completed', conclusion: 'cancelled', head_sha: run.head_sha, head_branch: run.head_branch, created_at: run.created_at, updated_at: occurredAt };
+        await put(ctx, { operation: 'workflow_run.cancel', subjectType: 'workflow_run', subjectId: `run:${id}`, fields: runFields });
+        for (const job of state().jobs.filter((j) => j.repository === repo && j.run_id === id)) {
+            const jobFields = { run_id: id, repository: repo, name: job.name, status: 'completed', conclusion: 'cancelled', head_sha: job.head_sha, started_at: job.started_at, completed_at: occurredAt, steps: job.steps.map((s) => ({ ...s, status: 'completed', conclusion: 'cancelled' })) };
+            await put(ctx, { operation: 'workflow_job.cancel', subjectType: 'workflow_job', subjectId: `job:${job.id}`, fields: jobFields });
+            await put(ctx, actionsCheckRun(job, 'completed', 'cancelled', occurredAt));
+        }
+        return ctx.reply({}, 202);
+    };
+    const actionsUpdateRepoVariable = async (ctx) => {
+        const { container: repo, name } = repoScope(ctx);
+        const { body, occurredAt, state } = gh(ctx);
+        const existing = state().actionsVariables.find((v) => v.scope === 'repo' && v.container === repo && v.name === name);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        const newName = body.name !== undefined ? String(body.name) : name;
+        await put(ctx, { operation: 'actions_variable.update', subjectType: 'actions_variable', subjectId: `variable:repo:${repo}#${newName}`, fields: { scope: 'repo', container: repo, name: newName, value: body.value !== undefined ? String(body.value) : existing.value, created_at: existing.created_at, updated_at: occurredAt } });
+        if (newName !== name)
+            await put(ctx, { operation: 'actions_variable.delete', subjectType: 'actions_variable', subjectId: `variable:repo:${repo}#${name}`, fields: { deleted: true, scope: 'repo', container: repo, name } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    const actionsUpdateOrgVariable = async (ctx) => {
+        const { container: org, name } = orgWriteScope(ctx);
+        const { body, occurredAt, state } = gh(ctx);
+        const existing = state().actionsVariables.find((v) => v.scope === 'org' && v.container === org && v.name === name);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'actions_variable.update', subjectType: 'actions_variable', subjectId: `variable:org:${org}#${name}`, fields: { scope: 'org', container: org, name, value: body.value !== undefined ? String(body.value) : existing.value, created_at: existing.created_at, updated_at: occurredAt } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    const actionsGetActionsCacheList = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const inRepo = state().actionsCaches.filter((c) => c.repository === repo);
+        return ctx.reply({ total_count: inRepo.length, actions_caches: paginate(inRepo, query).map(toGithubActionsCache) });
+    };
+    const actionsListArtifactsForRepo = async (ctx) => {
+        const { repo, query, state } = gh(ctx);
+        const inRepo = state().actionsArtifacts.filter((a) => a.repository === repo);
+        return ctx.reply({ total_count: inRepo.length, artifacts: paginate(inRepo, query).map(toGithubActionsArtifact) });
+    };
+    const actionsGetArtifact = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const a = state().actionsArtifacts.find((x) => x.repository === repo && x.id === Number(decodeURIComponent(seg[5])));
+        return send(ctx, a ? { status: 200, body: toGithubActionsArtifact(a) } : githubNotFound());
+    };
+    const actionsDeleteArtifact = async (ctx) => {
+        const { repo, seg, state } = gh(ctx);
+        const id = Number(decodeURIComponent(seg[5]));
+        const existing = state().actionsArtifacts.find((a) => a.repository === repo && a.id === id);
+        if (!existing)
+            return send(ctx, githubNotFound());
+        await put(ctx, { operation: 'actions_artifact.delete', subjectType: 'actions_artifact', subjectId: `artifact:${id}`, fields: { deleted: true, repository: repo, name: existing.name } });
+        return send(ctx, { status: 204, body: undefined });
+    };
+    return {
+        'actions/disable-workflow': toggleWorkflow('disabled_manually', 'actions/disable-workflow'),
+        'actions/enable-workflow': toggleWorkflow('active', 'actions/enable-workflow'),
+        'actions/list-repo-workflows': actionsListRepoWorkflows,
+        // the id may be the numeric id OR the workflow file path
+        'actions/get-workflow': actionsGetWorkflow,
+        // runs scoped to one workflow (status/branch filters apply)
+        'actions/list-workflow-runs': async (ctx) => {
+            const { repo, seg, query, state } = gh(ctx);
+            const st = state();
+            const wf = workflowOf(st, repo, decodeURIComponent(seg[5]));
+            if (!wf)
+                return send(ctx, githubNotFound());
+            let runs = st.workflowRuns.filter((r) => r.repository === repo && r.workflow_id === wf.id);
+            const status = params(query).get('status');
+            if (status)
+                runs = runs.filter((r) => r.status === status || r.conclusion === status);
+            const branch = params(query).get('branch');
+            if (branch)
+                runs = runs.filter((r) => r.head_branch === branch);
+            return ctx.reply({ total_count: runs.length, workflow_runs: paginate(newestFirst(runs), query).map((r) => toGithubWorkflowRun(r, st)) });
+        },
+        // with GitHub's status/branch/event filters
+        'actions/list-workflow-runs-for-repo': async (ctx) => {
+            const { repo, query, state } = gh(ctx);
+            let inRepo = state().workflowRuns.filter((r) => r.repository === repo);
+            const p = params(query);
+            const status = p.get('status');
+            if (status)
+                inRepo = inRepo.filter((r) => r.status === status || r.conclusion === status);
+            const branch = p.get('branch');
+            if (branch)
+                inRepo = inRepo.filter((r) => r.head_branch === branch);
+            const event = p.get('event');
+            if (event)
+                inRepo = inRepo.filter((r) => r.event === event);
+            return ctx.reply({ total_count: inRepo.length, workflow_runs: paginate(newestFirst(inRepo), query).map((r) => toGithubWorkflowRun(r, gh(ctx).state())) });
+        },
+        'actions/get-workflow-run': actionsGetWorkflowRun,
+        'actions/list-jobs-for-workflow-run': actionsListJobsForWorkflowRun,
+        // the reviews of the run's gated environments, oldest first
+        'actions/get-reviews-for-run': actionsGetReviewsForRun,
+        // GitHub 302-redirects to a signed download URL; the twin answers the 302 with the location in
+        // its body (serving the bytes is not modeled)
+        'actions/download-workflow-run-logs': actionsDownloadWorkflowRunLogs,
+        'actions/get-job-for-workflow-run': actionsGetJobForWorkflowRun,
+        // workflow_dispatch: a queued run and its build job. `ref` selects the branch or sha; in a
+        // repository with history the ref must resolve there, as GitHub requires. 204.
+        'actions/create-workflow-dispatch': actionsCreateWorkflowDispatch,
+        // A required reviewer approves or rejects the run's gated environments. The caller (a personal
+        // token's user) must be one of each environment's reviewers; the review is recorded on the run.
+        'actions/review-pending-deployments-for-run': actionsReviewPendingDeploymentsForRun,
+        // A maintainer with write access approves a first-time contributor's run from a fork, which waits in
+        // action_required until then; the run is queued with its jobs (201)
+        // (docs.github.com/rest/actions/workflow-runs#approve-a-workflow-run-for-a-fork-pull-request,
+        // docs.github.com/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks).
+        // Where the documentation stops and the twin decides: it gives the refusal only as 403 Forbidden, and the twin
+        // words it for the two causes it has, a caller without write access and a run that is not waiting for approval.
+        'actions/approve-workflow-run': async (ctx) => {
+            const { id, st, run } = runOf(ctx);
+            if (!run)
+                return send(ctx, githubNotFound());
+            const { repo, occurredAt, caller } = gh(ctx);
+            const docs = 'https://docs.github.com/rest/actions/workflow-runs#approve-a-workflow-run-for-a-fork-pull-request';
+            if (!canWrite(st, repo, caller ?? GITHUB_WORLD_USER))
+                return ctx.reply({ message: 'Must have write access to the repository to approve workflow runs.', documentation_url: docs }, 403);
+            if (run.conclusion !== 'action_required')
+                return ctx.reply({ message: 'This workflow run is not waiting for approval.', documentation_url: docs }, 403);
+            const wf = st.workflows.find((w) => w.id === run.workflow_id);
+            if (!wf)
+                return send(ctx, githubNotFound());
+            await put(ctx, { operation: 'workflow_run.approve', subjectType: 'workflow_run', subjectId: `run:${id}`, fields: { repository: repo, workflow_id: run.workflow_id, name: run.name, run_number: run.run_number, event: run.event, status: 'queued', conclusion: null, head_sha: run.head_sha, head_branch: run.head_branch, created_at: run.created_at, updated_at: occurredAt } });
+            await queueJobs(ctx, st, repo, wf, id, run.run_number, run.head_branch ?? '', run.head_sha);
+            return ctx.reply({}, 201);
+        },
+        // a new attempt: the run and its jobs back to queued (201)
+        'actions/re-run-workflow': actionsReRunWorkflow,
+        // the run and its jobs to completed/cancelled (202)
+        'actions/cancel-workflow-run': actionsCancelWorkflowRun,
+        // repository secrets and variables (the secret's value is never returned; a variable's is)
+        'actions/list-repo-secrets': listSecrets(repoScope),
+        'actions/get-repo-secret': getSecret(repoScope),
+        'actions/create-or-update-repo-secret': putSecret(repoScope),
+        'actions/delete-repo-secret': deleteSecret(repoScope),
+        // environment secrets
+        'actions/list-environment-secrets': listSecrets(envScope),
+        'actions/get-environment-secret': getSecret(envScope),
+        'actions/create-or-update-environment-secret': putSecret(envScope),
+        'actions/delete-environment-secret': deleteSecret(envScope),
+        'actions/list-repo-variables': listVariables(repoScope),
+        'actions/get-repo-variable': getVariable(repoScope),
+        'actions/create-repo-variable': createVariable(repoScope),
+        // an edit may rename the variable: the new name is written and the old one deleted
+        'actions/update-repo-variable': actionsUpdateRepoVariable,
+        'actions/delete-repo-variable': deleteVariable(repoScope),
+        // organization secrets and variables
+        'actions/list-org-secrets': listSecrets(orgReadScope),
+        'actions/get-org-secret': getSecret(orgReadScope),
+        'actions/create-or-update-org-secret': putSecret(orgWriteScope),
+        'actions/delete-org-secret': deleteSecret(orgWriteScope),
+        'actions/list-org-variables': listVariables(orgReadScope),
+        'actions/get-org-variable': getVariable(orgReadScope),
+        'actions/create-org-variable': createVariable(orgWriteScope),
+        'actions/update-org-variable': actionsUpdateOrgVariable,
+        'actions/delete-org-variable': deleteVariable(orgWriteScope),
+        // caches: list, delete by id (404 when absent) or by ?key= (every cache of the repo without one)
+        'actions/get-actions-cache-list': actionsGetActionsCacheList,
+        'actions/delete-actions-cache-by-id': async (ctx) => deleteCaches(ctx),
+        'actions/delete-actions-cache-by-key': async (ctx) => deleteCaches(ctx),
+        // the artifacts one run's steps uploaded (docs.github.com/rest/actions/artifacts#list-workflow-run-artifacts), by name
+        // when `name` is given
+        'actions/list-workflow-run-artifacts': async (ctx) => {
+            const { id, st, run } = runOf(ctx);
+            if (!run)
+                return send(ctx, githubNotFound());
+            const { repo, query } = gh(ctx);
+            const name = params(query).get('name');
+            const inRun = st.actionsArtifacts.filter((a) => a.repository === repo && a.run_id === id && (!name || a.name === name));
+            return ctx.reply({ total_count: inRun.length, artifacts: paginate(inRun, query).map(toGithubActionsArtifact) });
+        },
+        'actions/list-artifacts-for-repo': actionsListArtifactsForRepo,
+        'actions/get-artifact': actionsGetArtifact,
+        'actions/delete-artifact': actionsDeleteArtifact,
+    };
+}
+/** Delete caches: the one an id names (204, no body), or those a `key` names (200 with the deleted list). */
+async function deleteCaches(ctx) {
+    const { repo, seg, query, state } = gh(ctx);
+    const key = params(query).get('key');
+    let targets = state().actionsCaches.filter((c) => c.repository === repo);
+    if (seg[5])
+        targets = targets.filter((c) => c.id === Number(decodeURIComponent(seg[5])));
+    else if (key)
+        targets = targets.filter((c) => c.key === key);
+    if (!targets.length)
+        return seg[5] ? send(ctx, githubNotFound()) : ctx.reply({ total_count: 0, actions_caches: [] });
+    for (const c of targets)
+        await put(ctx, { operation: 'actions_cache.delete', subjectType: 'actions_cache', subjectId: `cache:${c.id}`, fields: { deleted: true, repository: repo, key: c.key } });
+    if (seg[5])
+        return send(ctx, { status: 204, body: undefined });
+    return ctx.reply({ total_count: targets.length, actions_caches: targets.map(toGithubActionsCache) });
+}

package/dist/src/semantics/activity.d.ts

@@ -0,0 +1,4 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+/** Who the credential names: its user, or the World's own for its shared token. */
+export declare const me: (ctx: SemanticsContext) => string;
+export declare function activitySemantics(): Record<string, Semantics>;