@volter/twin-github 0.1.2 → 2.0.1

package/src/semantics/security.ts

@@ -0,0 +1,153 @@
+// GitHub's security alert families: code scanning alerts and analyses, Dependabot alerts, and secret
+// scanning alerts with their locations. GitHub raises them itself: secret scanning and Dependabot when code is
+// pushed (./push-reactions.ts), code scanning from an uploaded SARIF analysis (./code-scanning-upload.ts); here
+// they are read and moved through their states: dismissing needs a reason, resolving a resolution.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { GITHUB_WORLD_USER, githubNotFound, resolvePlaneRef, paginate, toGithubCodeScanningAlert, toGithubCodeScanningAnalysis, toGithubDependabotAlert, toGithubSecretScanningAlert } from '../github-twin.ts';
+import { asView, gh, put, send } from './shared.ts';
+import { dependabotOn, dependabotReads, manifestsAt } from './push-reactions.ts';
+
+const wantState = (query: string | undefined): string | null => new URLSearchParams((query ?? '').replace(/^\?/, '')).get('state');
+const alertNumber = (ctx: SemanticsContext): number => Number(decodeURIComponent(gh(ctx).seg[5]!));
+const invalid = (ctx: SemanticsContext, resource: string, field: string): Response => ctx.reply({ message: 'Validation Failed', errors: [{ resource, field, code: 'invalid' }] }, 422);
+
+/** PATCH an alert: to `dismissed` with one of the vendor's reasons, or back (clearing the reason). */
+async function dismissable(ctx: SemanticsContext, kind: 'code_scanning' | 'dependabot'): Promise<Response> {
+  const { repo, body, occurredAt, state, caller } = gh(ctx);
+  const number = alertNumber(ctx);
+  const alerts = kind === 'code_scanning' ? state().codeScanningAlerts : state().dependabotAlerts;
+  const existing = alerts.find((a) => a.repository === repo && a.number === number);
+  if (!existing) return send(ctx, githubNotFound());
+  const newState = body.state !== undefined ? String(body.state) : existing.state;
+  // Dismissing requires a reason (real GitHub 422s without it).
+  if (newState === 'dismissed' && !body.dismissed_reason) return ctx.reply({ message: 'dismissed_reason is required when dismissing an alert' }, 422);
+  const validReasons = kind === 'code_scanning' ? ['false positive', "won't fix", 'used in tests'] : ['fix_started', 'inaccurate', 'no_bandwidth', 'not_used', 'tolerable_risk'];
+  if (newState === 'dismissed' && !validReasons.includes(String(body.dismissed_reason))) return invalid(ctx, kind === 'code_scanning' ? 'CodeScanningAlert' : 'DependabotAlert', 'dismissed_reason');
+  const fields: Record<string, unknown> = { number, repository: repo, state: newState, updated_at: occurredAt };
+  if (newState === 'dismissed') { fields.dismissed_reason = String(body.dismissed_reason); fields.dismissed_comment = body.dismissed_comment !== undefined ? String(body.dismissed_comment) : null; fields.dismissed_at = occurredAt; fields.dismissed_by_login = caller ?? GITHUB_WORLD_USER; }
+  else { fields.dismissed_reason = null; fields.dismissed_comment = null; fields.dismissed_at = null; fields.dismissed_by_login = null; }
+  if (kind === 'code_scanning') {
+    await put(ctx, { operation: 'code_scanning_alert.update', subjectType: 'code_scanning_alert', subjectId: `csalert:${repo}#${number}`, fields });
+    return ctx.reply(toGithubCodeScanningAlert(state().codeScanningAlerts.find((x) => x.repository === repo && x.number === number)!));
+  }
+  await put(ctx, { operation: 'dependabot_alert.update', subjectType: 'dependabot_alert', subjectId: `dependabot:${repo}#${number}`, fields });
+  return ctx.reply(toGithubDependabotAlert(state().dependabotAlerts.find((x) => x.repository === repo && x.number === number)!));
+}
+
+async function vulnerabilityAlerts(ctx: SemanticsContext, on: boolean): Promise<Response> {
+  const { repo, root, caller, state } = gh(ctx);
+  const st = state();
+  const r = st.repos.find((x) => x.full_name === repo);
+  if (!r) return send(ctx, githubNotFound());
+  const me = caller ?? GITHUB_WORLD_USER;
+  const admin = r.owner === me || st.orgMembers.some((m) => m.org === r.owner && m.login === me && m.role === 'admin' && m.state === 'active') || st.collaborators.some((c) => c.repository === repo && c.login === me && c.permission === 'admin');
+  if (!admin) return send(ctx, githubNotFound());
+  await put(ctx, { operation: on ? 'vulnerability_alerts.enable' : 'vulnerability_alerts.disable', subjectType: 'vulnerability_alerts', subjectId: `vulnalerts:${repo}`, fields: { repository: repo, enabled: on } });
+  const tip = on ? await resolvePlaneRef(repo, r.default_branch ?? 'main', r.default_branch ?? 'main', root) : null;
+  if (tip) await dependabotReads(ctx, repo, tip, await manifestsAt(repo, tip, root));
+  return send(ctx, { status: 204, body: undefined });
+}
+
+export function securitySemantics(): Record<string, Semantics> {
+  const codeScanningListRecentAnalyses: Semantics = async (ctx) => {
+    const { repo, query, state } = gh(ctx);
+    const q = new URLSearchParams((query ?? '').replace(/^\?/, ''));
+    const items = state().codeScanningAnalyses.filter((a) => a.repository === repo && (!q.get('sarif_id') || a.sarif_id === q.get('sarif_id')) && (!q.get('ref') || a.ref === q.get('ref')));
+    // most recent first, as GitHub lists them
+    return ctx.reply(paginate([...items].sort((x, y) => String(y.created_at ?? '').localeCompare(String(x.created_at ?? '')) || y.id - x.id), query).map(toGithubCodeScanningAnalysis));
+  };
+  const codeScanningGetAnalysis: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    const id = alertNumber(ctx);
+    const a = state().codeScanningAnalyses.find((x) => x.repository === repo && x.id === id);
+    return send(ctx, a ? { status: 200, body: toGithubCodeScanningAnalysis(a) } : githubNotFound());
+  };
+  const codeScanningDeleteAnalysis: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    const id = alertNumber(ctx);
+    if (!state().codeScanningAnalyses.find((a) => a.repository === repo && a.id === id)) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'code_scanning_analysis.delete', subjectType: 'code_scanning_analysis', subjectId: `csanalysis:${id}`, fields: { deleted: true, repository: repo } });
+    return ctx.reply({ next_analysis_url: null, confirm_delete_url: null });
+  };
+  const secretScanningListAlertsForRepo: Semantics = async (ctx) => {
+    const { repo, query, state } = gh(ctx);
+    const want = wantState(query);
+    let items = state().secretScanningAlerts.filter((a) => a.repository === repo);
+    if (want) items = items.filter((a) => a.state === want);
+    return ctx.reply(paginate(items, query).map(toGithubSecretScanningAlert));
+  };
+  const secretScanningGetAlert: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    const n = alertNumber(ctx);
+    const a = state().secretScanningAlerts.find((x) => x.repository === repo && x.number === n);
+    return send(ctx, a ? { status: 200, body: toGithubSecretScanningAlert(a) } : githubNotFound());
+  };
+  const secretScanningListLocationsForAlert: Semantics = async (ctx) => {
+    const { repo, state } = gh(ctx);
+    const n = alertNumber(ctx);
+    const alert = state().secretScanningAlerts.find((x) => x.repository === repo && x.number === n);
+    if (!alert) return send(ctx, githubNotFound());
+    return ctx.reply((alert.locations ?? []).map((l) => ({ type: 'commit', details: { ...l, blob_url: `https://api.github.com/repos/${repo}/git/blobs/${l.blob_sha}`, commit_url: `https://api.github.com/repos/${repo}/git/commits/${l.commit_sha}` } })));
+  };
+  const secretScanningUpdateAlert: Semantics = async (ctx) => {
+    const { repo, body, occurredAt, state } = gh(ctx);
+    const number = alertNumber(ctx);
+    const existing = state().secretScanningAlerts.find((a) => a.repository === repo && a.number === number);
+    if (!existing) return send(ctx, githubNotFound());
+    const newState = body.state !== undefined ? String(body.state) : existing.state;
+    if (newState === 'resolved' && !body.resolution) return ctx.reply({ message: 'resolution is required when resolving an alert' }, 422);
+    if (newState === 'resolved' && !['false_positive', 'wont_fix', 'revoked', 'used_in_tests'].includes(String(body.resolution))) return invalid(ctx, 'SecretScanningAlert', 'resolution');
+    const fields: Record<string, unknown> = { number, repository: repo, state: newState, updated_at: occurredAt };
+    if (newState === 'resolved') { fields.resolution = String(body.resolution); fields.resolution_comment = body.resolution_comment !== undefined ? String(body.resolution_comment) : null; fields.resolved_at = occurredAt; }
+    else { fields.resolution = null; fields.resolution_comment = null; fields.resolved_at = null; }
+    await put(ctx, { operation: 'secret_scanning_alert.update', subjectType: 'secret_scanning_alert', subjectId: `secretscan:${repo}#${number}`, fields });
+    return ctx.reply(toGithubSecretScanningAlert(state().secretScanningAlerts.find((x) => x.repository === repo && x.number === number)!));
+  };
+  return {
+    'code-scanning/list-alerts-for-repo': async (ctx) => {
+      const { repo, query, state } = gh(ctx);
+      const want = wantState(query);
+      let items = state().codeScanningAlerts.filter((a) => a.repository === repo);
+      if (want) items = items.filter((a) => a.state === want);
+      return ctx.reply(paginate(items, query).map((a) => asView('code-scanning-alert-items', toGithubCodeScanningAlert(a))));
+    },
+    'code-scanning/get-alert': async (ctx) => {
+      const { repo, state } = gh(ctx);
+      const n = alertNumber(ctx);
+      const a = state().codeScanningAlerts.find((x) => x.repository === repo && x.number === n);
+      return send(ctx, a ? { status: 200, body: toGithubCodeScanningAlert(a) } : githubNotFound());
+    },
+    'code-scanning/update-alert': async (ctx) => dismissable(ctx, 'code_scanning'),
+    'code-scanning/list-recent-analyses': codeScanningListRecentAnalyses,
+    'code-scanning/get-analysis': codeScanningGetAnalysis,
+    'code-scanning/delete-analysis': codeScanningDeleteAnalysis,
+    // Dependabot alerts on or off for a repository: GET answers 204 when on and 404 when off; turning them on reads the
+    // default branch's manifests at once (docs.github.com/rest/repos/repos#check-if-vulnerability-alerts-are-enabled-for-a-repository,
+    // #enable-vulnerability-alerts, #disable-vulnerability-alerts). Only an admin of the repository turns them on or off.
+    'repos/check-vulnerability-alerts': async (ctx) => send(ctx, dependabotOn(ctx, gh(ctx).repo) ? { status: 204, body: undefined } : githubNotFound()),
+    'repos/enable-vulnerability-alerts': async (ctx) => vulnerabilityAlerts(ctx, true),
+    'repos/disable-vulnerability-alerts': async (ctx) => vulnerabilityAlerts(ctx, false),
+    // with alerts off there are none to list: GitHub answers 403
+    'dependabot/list-alerts-for-repo': async (ctx) => {
+      const { repo, query, state } = gh(ctx);
+      if (!dependabotOn(ctx, repo)) return ctx.reply({ message: 'Dependabot alerts are disabled for this repository.', documentation_url: 'https://docs.github.com/rest/dependabot/alerts#list-dependabot-alerts-for-a-repository' }, 403);
+      const want = wantState(query);
+      let items = state().dependabotAlerts.filter((a) => a.repository === repo);
+      if (want) items = items.filter((a) => a.state === want);
+      return ctx.reply(paginate(items, query).map(toGithubDependabotAlert));
+    },
+    'dependabot/get-alert': async (ctx) => {
+      const { repo, state } = gh(ctx);
+      const n = alertNumber(ctx);
+      const a = state().dependabotAlerts.find((x) => x.repository === repo && x.number === n);
+      return send(ctx, a ? { status: 200, body: toGithubDependabotAlert(a) } : githubNotFound());
+    },
+    'dependabot/update-alert': async (ctx) => dismissable(ctx, 'dependabot'),
+    'secret-scanning/list-alerts-for-repo': secretScanningListAlertsForRepo,
+    'secret-scanning/get-alert': secretScanningGetAlert,
+    // where the secret was found: each commit and file secret scanning read it in
+    'secret-scanning/list-locations-for-alert': secretScanningListLocationsForAlert,
+    // resolving needs one of the vendor's resolutions; reopening clears it
+    'secret-scanning/update-alert': secretScanningUpdateAlert,
+  };
+}

package/src/semantics/shared.ts

@@ -0,0 +1,181 @@
+// What every GitHub handler (and GraphQL resolver) shares: the request as GitHub's helpers read it (the
+// path's segments, the query, the JSON body), the tree read through the pack's projection over the
+// context's whole-tree read, GitHub's answers, and the webhooks a write announces.
+//
+// Reads: GitHub's projection (`githubState`) folds every stored type in one pass, in tree order
+// (`ctx.tree()`), and replays open/closed history from the log, which it still reads from the kernel:
+// `ctx.history` is per subject and carries no actor, so it cannot tell a local create from an
+// observation. Writes go through the context (`put`, `ctx.atomically`).
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { SemanticsContext } from '@volter/world-core';
+import { callerLogin, githubState, resolveGithubNumber, twinUserId, type GithubAtomic, type GithubResponse, type GithubState, type GithubWrite, type GithubWriteEvent } from '../github-twin.ts';
+import { emitGithubEvent, emitGithubInstallationEvents } from '../github-events.ts';
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { spanning } from '../manifest.ts';
+
+const VIEWS = new Map((surface.resources as Array<{ name: string; fields: Array<{ name: string }> }>).map((r) => [r.name, new Set(r.fields.map((f) => f.name))]));
+/** An object as one of GitHub's views of it answers: a list's user is a simple-user, a list's pull request
+ *  pull-request-simple, a search hit an issue-search-result-item. The view keeps the fields the spec gives
+ *  it, from the full object it is a view of. */
+export function asView(view: string, full: Record<string, unknown>): Record<string, unknown> {
+  const keep = VIEWS.get(view);
+  if (!keep) throw new Error(`github: the spec has no view named ${view}`);
+  return Object.fromEntries(Object.entries(full).filter(([k]) => keep.has(k)));
+}
+
+export type Gh = {
+  ctx: SemanticsContext;
+  /** the path's segments as sent (percent-encoded), one per segment of the operation's path: a parameter
+   *  that spans slashes is one segment holding its encoded value; an issue or pull number resolved
+   *  through the alias map */
+  seg: string[];
+  /** the path, trailing slashes dropped */
+  path: string;
+  /** the query string with its `?`, when there is one */
+  query: string | undefined;
+  /** `owner/name` for a path under /repos */
+  repo: string;
+  root: string | undefined;
+  occurredAt: string;
+  /** the credential, as the twin's user door minted it */
+  token: string | undefined;
+  /** the caller's login, when the credential names one */
+  caller: string | undefined;
+  /** the JSON body as sent */
+  body: Record<string, any>;
+  state(): GithubState;
+};
+
+export function gh(ctx: SemanticsContext): Gh {
+  const url = new URL(ctx.call.request.url);
+  const path = url.pathname.replace(/\/+$/, '');
+  const sent = path.replace(/^\/+/, '').split('/');
+  const template = ctx.call.operation.path.replace(/^\/+/, '').split('/');
+  const extra = sent.length - template.length;
+  const at = extra > 0 ? template.findIndex((t) => t.startsWith('{') && spanning.includes(t.slice(1, -1))) : -1;
+  const seg = at === -1 ? sent : [...sent.slice(0, at), sent.slice(at, at + extra + 1).join('%2F'), ...sent.slice(at + extra + 1)];
+  if (seg[0] === 'repos' && (seg[3] === 'issues' || seg[3] === 'pulls') && seg[4] && /^\d+$/.test(seg[4])) seg[4] = resolveGithubNumber(seg[1]!, seg[2]!, seg[4], ctx.root);
+  const token = (ctx.call.request.headers.get('authorization') ?? '').replace(/^(?:bearer|token)\s+/i, '').trim() || undefined;
+  return {
+    ctx,
+    seg,
+    path,
+    query: url.search || undefined,
+    repo: `${seg[1]}/${seg[2]}`,
+    root: ctx.root,
+    occurredAt: ctx.occurredAt,
+    token,
+    caller: callerLogin(token, ctx.root),
+    body: (ctx.body ?? {}) as Record<string, any>,
+    state: () => githubStateOf(ctx),
+  };
+}
+
+/** GitHub's projection over this request's tree. */
+export const githubStateOf = (ctx: SemanticsContext): GithubState => githubState(ctx.root);
+
+/** GitHub's answer: JSON, or nothing for a 204 or an answer with no body. */
+export function send(ctx: SemanticsContext, r: GithubResponse): Response {
+  if (r.status === 204 || r.body === undefined) return ctx.raw(null, { status: r.status });
+  return ctx.reply(r.body, r.status);
+}
+
+/** A stored write, as the kernel records it: the subject's type, id, fields and operation name. */
+export function put(ctx: SemanticsContext, w: { operation: string; subjectType: string; subjectId: string; fields: Record<string, unknown> }): Promise<Record<string, unknown>> {
+  return ctx.write(w.subjectType, w.subjectId, w.fields, w.operation);
+}
+
+/** The events announced while an in-process call runs, for the caller that asked (applyGithubWrite
+ *  answers them beside the response, as the hand-written writes did). */
+const announcements = new AsyncLocalStorage<GithubWriteEvent[]>();
+export async function collectAnnouncements<T>(run: () => Promise<T>): Promise<{ value: T; events: GithubWriteEvent[] }> {
+  const events: GithubWriteEvent[] = [];
+  const value = await announcements.run(events, run);
+  // an in-process call made inside another (a GraphQL mutation writing through REST) announces to both
+  announcements.getStore()?.push(...events);
+  return { value, events };
+}
+export function noteAnnounced(events: GithubWriteEvent[]): void {
+  announcements.getStore()?.push(...events);
+}
+
+/** Deliver the webhooks a write announces. Fire-and-forget, like GitHub: a delivery failure never
+ *  fails the write. */
+export async function announce(ctx: SemanticsContext, events: Array<GithubWriteEvent | undefined>): Promise<void> {
+  for (const event of events) {
+    if (!event) continue;
+    // a branch that moved is read by GitHub's own processes (workflows, secret scanning, Dependabot)
+    if (event.event === 'push' && event.ref && event.after) {
+      const { reactToPush } = await import('./push-reactions.ts');
+      await reactToPush(ctx, event.repository, String(event.ref), String(event.before ?? '0'.repeat(40)), String(event.after));
+    }
+    // and so is a pull request opened or pushed to: its workflows run (semantics/push-reactions.ts)
+    if (event.event === 'pull_request' && event.number) {
+      const { reactToPullRequest } = await import('./push-reactions.ts');
+      await reactToPullRequest(ctx, event.repository, Number(event.number), String(event.action ?? ''));
+    }
+    // and someone else's act on an issue or pull request may notify the World's user
+    if (event.event === 'issues' || event.event === 'issue_comment' || event.event === 'pull_request' || event.event === 'pull_request_review') {
+      const { notify } = await import('./notifications.ts');
+      await notify(ctx, event);
+    }
+    noteAnnounced([event]);
+    try {
+      await emitGithubEvent(event, { occurredAt: ctx.occurredAt, root: ctx.root });
+    } catch {
+      /* fire-and-forget */
+    }
+    // and the GitHub Apps installed on the repository hear of it on their own webhooks
+    try {
+      await emitGithubInstallationEvents(event, { occurredAt: ctx.occurredAt, root: ctx.root });
+    } catch {
+      /* fire-and-forget */
+    }
+  }
+}
+
+/** The stored types whose subject ids carry each sequence prefix (`sshkey:3`). */
+const SEQ_TYPES: Record<string, string[]> = {
+  artifact: ['actions_artifact'], asset: ['release_asset'], autolink: ['autolink'], cache: ['actions_cache'], check: ['check_run'],
+  comment: ['issue_comment', 'pull_request_review_comment'], commitcomment: ['commit_comment'], csanalysis: ['code_scanning_analysis'],
+  deploykey: ['deploy_key'], deployment: ['deployment'], depstatus: ['deployment_status'], discomment: ['discussion_comment'],
+  gpgkey: ['user_gpg_key'], installation: ['app_installation'], issuetype: ['issue_type'], label: ['label'], orghook: ['org_webhook'],
+  package: ['package'], packageversion: ['package_version'], pagesbuild: ['pages_build'], project: ['project'], projectfield: ['project_field'],
+  projectitem: ['project_item'], projectview: ['project_view'], reaction: ['reaction'], release: ['release'], repo: ['repository'], repoinvite: ['repo_invitation'],
+  review: ['pull_request_review'], rulesuite: ['rule_suite'], ruleset: ['ruleset'], sshkey: ['user_ssh_key'], status: ['commit_status'],
+  team: ['team'], teamdisc: ['team_discussion'], teamdisccomment: ['team_discussion_comment'], thread: ['review_thread'], webhook: ['webhook'],
+};
+
+/** One past the highest `<prefix>:<n>` subject id stored, tombstones included. */
+export function nextSeq(ctx: SemanticsContext, prefix: string): number {
+  const pattern = new RegExp(`^${prefix}:(\\d+)$`);
+  let max = 0;
+  for (const type of SEQ_TYPES[prefix] ?? []) {
+    for (const r of ctx.rowsRaw(type, { withDeleted: true })) {
+      const m = pattern.exec(String(r.id));
+      if (m) max = Math.max(max, Number(m[1]));
+    }
+  }
+  return max + 1;
+}
+
+/** The pack helpers' atomic decision (GithubAtomic), made through this request's context. */
+export function atomic(ctx: SemanticsContext): GithubAtomic {
+  return <T>(decide: () => { value: T; write?: { operation: string; subjectType: string; subjectId: string; fields: Record<string, unknown> } }) =>
+    ctx.atomically<T>(() => {
+      const d = decide();
+      return d.write ? { value: d.value, write: { resource: d.write.subjectType, id: d.write.subjectId, fields: d.write.fields, operation: d.write.operation } } : { value: d.value };
+    });
+}
+
+/** The pack helpers' writer (GithubWrite), through this request's context. */
+export const writer = (ctx: SemanticsContext): GithubWrite => (w) => put(ctx, w);
+
+/** Who a commit or tag made through the API is by when the request names no one: the signed-in person, as
+ *  GitHub defaults author and committer to the authenticated user (docs.github.com/rest/repos/contents), with
+ *  the noreply address GitHub gives an account that keeps its email private. */
+export function identityOf(g: Gh): { name: string; email: string } {
+  const login = g.caller ?? 'octocat';
+  const profile = login === 'octocat' ? g.state().userProfile : undefined;
+  return { name: String(profile?.name ?? login), email: `${twinUserId(login)}+${login}@users.noreply.github.com` };
+}

package/src/semantics/users.ts

@@ -0,0 +1,252 @@
+// GitHub's users family: a user by login or account id, the authenticated user and their profile,
+// the follow graph, emails, SSH and GPG keys, blocks, and the activity streams scoped to a user.
+// The twin models one follow actor, the authenticated `octocat`.
+import { me } from './activity.ts';
+import { createHash } from 'node:crypto';
+import type { Semantics } from '@volter/world-core';
+import {
+  githubActivityEvents, githubNotFound, paginate, seedUser, toGithubOrg, toGithubRepo, toGithubUser, toGithubUserEmail, toGithubUserGpgKey, toGithubUserSshKey, toSimpleUser, twinUserId,
+} from '../github-twin.ts';
+import { asView, gh, nextSeq, put, send } from './shared.ts';
+
+/** GET /users/:login/events[/public] and /users/:login/received_events[/public]: events = activity the
+ *  user PERFORMED (actor); received_events = activity in repos the user OWNS. Both filter the SAME
+ *  modeled stream. */
+const userEvents = (received: boolean, only: 'public' | undefined): Semantics => async (ctx) => {
+  const { seg, query, state } = gh(ctx);
+  const login = decodeURIComponent(seg[1]!);
+  const all = githubActivityEvents(state());
+  let items = !received
+    ? all.filter((e) => (e.actor as { login?: string }).login === login)
+    : all.filter((e) => String((e.repo as { name?: string }).name ?? '').split('/')[0] === login);
+  if (only === 'public') items = items.filter((e) => e.public === true);
+  return ctx.reply(paginate(items, query));
+};
+
+export function usersSemantics(): Record<string, Semantics> {
+  const usersGetByUsername: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const login = decodeURIComponent(seg[1]!);
+    return ctx.reply(toGithubUser(login === 'octocat' ? { ...seedUser('octocat'), ...state().userProfile, login } : seedUser(login)));
+  };
+  const reposListForAuthenticatedUser: Semantics = async (ctx) => {
+    const { caller, query, state } = gh(ctx);
+    const me = caller ?? 'octocat';
+    const params = new URLSearchParams(query ?? '');
+    const affiliation = new Set((params.get('affiliation') ?? 'owner,collaborator,organization_member').split(',').map((a) => a.trim()));
+    const visibility = params.get('visibility') ?? 'all';
+    const st = state();
+    const memberOf = new Set(st.orgMembers.filter((m) => m.login === me && (m.state ?? 'active') === 'active').map((m) => m.org));
+    const collaborating = new Set(st.collaborators.filter((c) => c.login === me).map((c) => c.repository));
+    const mine = st.repos.filter((r) =>
+      ((affiliation.has('owner') && r.owner === me) || (affiliation.has('collaborator') && collaborating.has(r.full_name)) || (affiliation.has('organization_member') && memberOf.has(r.owner)))
+      && (visibility === 'all' || (visibility === 'private') === (r.private === true)));
+    return ctx.reply(paginate([...mine].sort((a, b) => a.full_name.localeCompare(b.full_name)), query).map((r) => asView('repository', toGithubRepo(r))));
+  };
+  const orgsListForAuthenticatedUser: Semantics = async (ctx) => {
+    const { caller, query, state } = gh(ctx);
+    const me = caller ?? 'octocat';
+    const st = state();
+    const logins = new Set(st.orgMembers.filter((m) => m.login === me && (m.state ?? 'active') === 'active').map((m) => m.org));
+    const SIMPLE = ['login', 'id', 'node_id', 'url', 'repos_url', 'events_url', 'hooks_url', 'issues_url', 'members_url', 'public_members_url', 'avatar_url', 'description'];
+    const simple = (o: Record<string, unknown>) => Object.fromEntries(SIMPLE.filter((k) => k in o).map((k) => [k, o[k]]));
+    return ctx.reply(paginate(st.orgs.filter((o) => logins.has(o.login)), query).map((o) => simple(toGithubOrg(o))));
+  };
+  const reposListForUser: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const login = decodeURIComponent(seg[1]!);
+    return ctx.reply(paginate(state().repos.filter((r) => r.owner === login), query).map(toGithubRepo));
+  };
+  const usersListFollowersForUser: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const login = decodeURIComponent(seg[1]!);
+    return ctx.reply(paginate(state().followEdges.filter((e) => e.to === login).map((e) => asView('simple-user', toGithubUser(seedUser(e.from)))), query));
+  };
+  const usersListFollowingForUser: Semantics = async (ctx) => {
+    const { seg, query, state } = gh(ctx);
+    const login = decodeURIComponent(seg[1]!);
+    return ctx.reply(paginate(state().followEdges.filter((e) => e.from === login).map((e) => asView('simple-user', toGithubUser(seedUser(e.to)))), query));
+  };
+  const usersCheckFollowingForUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const [login, other] = [decodeURIComponent(seg[1]!), decodeURIComponent(seg[3]!)];
+    return send(ctx, state().followEdges.some((e) => e.from === login && e.to === other) ? { status: 204, body: undefined } : githubNotFound());
+  };
+  const usersGetById: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    if (!/^\d+$/.test(seg[1]!)) return send(ctx, githubNotFound());
+    const st = state();
+    const known = new Set<string>(['octocat', ...st.orgMembers.map((m) => m.login), ...st.oauthGrants.map((g) => g.login), ...st.prs.map((p) => p.user_login ?? '')].filter((l): l is string => !!l));
+    const login = [...known].find((l) => twinUserId(l) === Number(seg[1]));
+    return send(ctx, login ? { status: 200, body: { ...toSimpleUser(login), id: twinUserId(login) } } : githubNotFound());
+  };
+  const usersListFollowedByAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    return ctx.reply(paginate(state().followEdges.filter((e) => e.from === me(ctx)).map((e) => asView('simple-user', toGithubUser(seedUser(e.to)))), query));
+  };
+  const usersCheckPersonIsFollowedByAuthenticated: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    return send(ctx, state().followEdges.some((e) => e.from === me(ctx) && e.to === decodeURIComponent(seg[2]!)) ? { status: 204, body: undefined } : githubNotFound());
+  };
+  const usersListFollowersForAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    return ctx.reply(paginate(state().followEdges.filter((e) => e.to === me(ctx)).map((e) => asView('simple-user', toGithubUser(seedUser(e.from)))), query));
+  };
+  const usersListEmailsForAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    return ctx.reply(paginate(state().userEmails, query).map(toGithubUserEmail));
+  };
+  const usersListPublicEmailsForAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    return ctx.reply(paginate(state().userEmails.filter((e) => e.visibility === 'public'), query).map(toGithubUserEmail));
+  };
+  const usersListPublicSshKeysForAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    return ctx.reply(paginate(state().userSshKeys, query).map(toGithubUserSshKey));
+  };
+  const usersGetPublicSshKeyForAuthenticatedUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const k = state().userSshKeys.find((x) => x.id === Number(decodeURIComponent(seg[2]!)));
+    return send(ctx, k ? { status: 200, body: toGithubUserSshKey(k) } : githubNotFound());
+  };
+  const usersListGpgKeysForAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    return ctx.reply(paginate(state().userGpgKeys, query).map(toGithubUserGpgKey));
+  };
+  const usersGetGpgKeyForAuthenticatedUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const k = state().userGpgKeys.find((x) => x.id === Number(decodeURIComponent(seg[2]!)));
+    return send(ctx, k ? { status: 200, body: toGithubUserGpgKey(k) } : githubNotFound());
+  };
+  const usersListBlockedByAuthenticatedUser: Semantics = async (ctx) => {
+    const { query, state } = gh(ctx);
+    return ctx.reply(paginate([...state().blockedUsers].sort().map((l) => asView('simple-user', toGithubUser(seedUser(l)))), query));
+  };
+  const usersCheckBlocked: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    return send(ctx, state().blockedUsers.has(decodeURIComponent(seg[2]!)) ? { status: 204, body: undefined } : githubNotFound());
+  };
+  const usersGetAuthenticated: Semantics = async (ctx) => {
+    const { caller, state } = gh(ctx);
+    if (caller) return ctx.reply(toGithubUser(seedUser(caller)));
+    return ctx.reply(toGithubUser({ ...seedUser('octocat'), ...state().userProfile, login: 'octocat' }));
+  };
+  const usersUpdateAuthenticated: Semantics = async (ctx) => {
+    const { body, state } = gh(ctx);
+    const fields: Record<string, unknown> = {};
+    for (const k of ['name', 'bio', 'company', 'blog', 'location', 'email'] as const) if (body[k] !== undefined) fields[k] = body[k];
+    await put(ctx, { operation: 'user_profile.update', subjectType: 'user_profile', subjectId: 'user_profile:octocat', fields });
+    return ctx.reply(toGithubUser({ ...seedUser('octocat'), ...state().userProfile, login: 'octocat' }));
+  };
+  const usersCreatePublicSshKeyForAuthenticatedUser: Semantics = async (ctx) => {
+    const { body, occurredAt, state } = gh(ctx);
+    if (!body.key) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'PublicKey', field: 'key', code: 'missing_field' }] }, 422);
+    const id = nextSeq(ctx, 'sshkey');
+    await put(ctx, { operation: 'user_ssh_key.create', subjectType: 'user_ssh_key', subjectId: `sshkey:${id}`, fields: { key: String(body.key), title: String(body.title ?? ''), created_at: occurredAt } });
+    return ctx.reply(toGithubUserSshKey(state().userSshKeys.find((x) => x.id === id)!), 201);
+  };
+  const usersDeletePublicSshKeyForAuthenticatedUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const id = Number(decodeURIComponent(seg[2]!));
+    if (!state().userSshKeys.find((k) => k.id === id)) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'user_ssh_key.delete', subjectType: 'user_ssh_key', subjectId: `sshkey:${id}`, fields: { deleted: true } });
+    return send(ctx, { status: 204, body: undefined });
+  };
+  const usersCreateGpgKeyForAuthenticatedUser: Semantics = async (ctx) => {
+    const { body, occurredAt, state } = gh(ctx);
+    if (!body.armored_public_key) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'GpgKey', field: 'armored_public_key', code: 'missing_field' }] }, 422);
+    const id = nextSeq(ctx, 'gpgkey');
+    const raw = String(body.armored_public_key);
+    const keyId = createHash('sha256').update(raw).digest('hex').slice(0, 16).toUpperCase();
+    await put(ctx, { operation: 'user_gpg_key.create', subjectType: 'user_gpg_key', subjectId: `gpgkey:${id}`, fields: { key_id: keyId, raw_key: raw, created_at: occurredAt } });
+    return ctx.reply(toGithubUserGpgKey(state().userGpgKeys.find((x) => x.id === id)!), 201);
+  };
+  const usersDeleteGpgKeyForAuthenticatedUser: Semantics = async (ctx) => {
+    const { seg, state } = gh(ctx);
+    const id = Number(decodeURIComponent(seg[2]!));
+    if (!state().userGpgKeys.find((k) => k.id === id)) return send(ctx, githubNotFound());
+    await put(ctx, { operation: 'user_gpg_key.delete', subjectType: 'user_gpg_key', subjectId: `gpgkey:${id}`, fields: { deleted: true } });
+    return send(ctx, { status: 204, body: undefined });
+  };
+  return {
+    // the twin's own account (octocat) answers with the profile its owner edited (PATCH /user)
+    'users/get-by-username': usersGetByUsername,
+    // the signed-in person's repositories, by GitHub's affiliation (owner, collaborator, organization_member;
+    // all three by default) and visibility (all, public, private), sorted by full_name
+    'repos/list-for-authenticated-user': reposListForAuthenticatedUser,
+    // the organizations the signed-in person is an active member of, in GitHub's simple organization shape
+    'orgs/list-for-authenticated-user': orgsListForAuthenticatedUser,
+    'repos/list-for-user': reposListForUser,
+    // who follows :login, and whom :login follows
+    'users/list-followers-for-user': usersListFollowersForUser,
+    'users/list-following-for-user': usersListFollowingForUser,
+    // 204 if :login follows :other, else 404
+    'users/check-following-for-user': usersCheckFollowingForUser,
+    'activity/list-events-for-authenticated-user': userEvents(false, undefined),
+    'activity/list-public-events-for-user': userEvents(false, 'public'),
+    'activity/list-received-events-for-user': userEvents(true, undefined),
+    'activity/list-received-public-events-for-user': userEvents(true, 'public'),
+    // an account by its id, among the accounts the twin knows (its own octocat, members, token holders, authors)
+    'users/get-by-id': usersGetById,
+    'users/list-followed-by-authenticated-user': usersListFollowedByAuthenticatedUser,
+    'users/check-person-is-followed-by-authenticated': usersCheckPersonIsFollowedByAuthenticated,
+    // the authenticated user's own followers
+    'users/list-followers-for-authenticated-user': usersListFollowersForAuthenticatedUser,
+    'users/list-emails-for-authenticated-user': usersListEmailsForAuthenticatedUser,
+    'users/list-public-emails-for-authenticated-user': usersListPublicEmailsForAuthenticatedUser,
+    'users/list-public-ssh-keys-for-authenticated-user': usersListPublicSshKeysForAuthenticatedUser,
+    'users/get-public-ssh-key-for-authenticated-user': usersGetPublicSshKeyForAuthenticatedUser,
+    'users/list-gpg-keys-for-authenticated-user': usersListGpgKeysForAuthenticatedUser,
+    'users/get-gpg-key-for-authenticated-user': usersGetGpgKeyForAuthenticatedUser,
+    'users/list-blocked-by-authenticated-user': usersListBlockedByAuthenticatedUser,
+    // "Check if a user is blocked by the authenticated user" → 204 blocked / 404 not.
+    'users/check-blocked': usersCheckBlocked,
+    // the token's own user when the twin's user door minted it; else the deterministic octocat
+    'users/get-authenticated': usersGetAuthenticated,
+    'users/update-authenticated': usersUpdateAuthenticated,
+    'users/add-email-for-authenticated-user': async (ctx) => emails(ctx, false),
+    'users/delete-email-for-authenticated-user': async (ctx) => emails(ctx, true),
+    'users/create-public-ssh-key-for-authenticated-user': usersCreatePublicSshKeyForAuthenticatedUser,
+    'users/delete-public-ssh-key-for-authenticated-user': usersDeletePublicSshKeyForAuthenticatedUser,
+    'users/create-gpg-key-for-authenticated-user': usersCreateGpgKeyForAuthenticatedUser,
+    'users/delete-gpg-key-for-authenticated-user': usersDeleteGpgKeyForAuthenticatedUser,
+    // block / unblock answer 204
+    'users/block': async (ctx) => block(ctx, true),
+    'users/unblock': async (ctx) => block(ctx, false),
+    // follow / unfollow answer 204
+    'users/follow': async (ctx) => follow(ctx, true),
+    'users/unfollow': async (ctx) => follow(ctx, false),
+  };
+}
+
+/** POST /user/emails adds, DELETE removes; both take `{emails}` or a bare array. The first address a
+ *  user adds is primary and public. */
+async function emails(ctx: Parameters<Semantics>[0], remove: boolean): Promise<Response> {
+  const { body, state } = gh(ctx);
+  const list: string[] = Array.isArray(body.emails) ? body.emails.map(String) : Array.isArray(body) ? (body as string[]).map(String) : [];
+  if (!list.length) return ctx.reply({ message: 'Validation Failed', errors: [{ resource: 'Email', field: 'emails', code: 'missing_field' }] }, 422);
+  const st = state();
+  for (const email of list) {
+    const subjectId = `useremail:${email}`;
+    if (remove) {
+      await put(ctx, { operation: 'user_email.delete', subjectType: 'user_email', subjectId, fields: { deleted: true, email } });
+    } else {
+      const isFirst = st.userEmails.length === 0 && email === list[0];
+      await put(ctx, { operation: 'user_email.upsert', subjectType: 'user_email', subjectId, fields: { email, primary: isFirst, verified: true, visibility: isFirst ? 'public' : 'private' } });
+    }
+  }
+  if (remove) return send(ctx, { status: 204, body: undefined });
+  return ctx.reply(state().userEmails.map(toGithubUserEmail), 201);
+}
+
+async function block(ctx: Parameters<Semantics>[0], blocking: boolean): Promise<Response> {
+  const login = decodeURIComponent(gh(ctx).seg[2]!);
+  await put(ctx, { operation: blocking ? 'user_block.create' : 'user_block.delete', subjectType: 'user_block', subjectId: `block:${login}`, fields: blocking ? { login } : { login, deleted: true } });
+  return send(ctx, { status: 204, body: undefined });
+}
+
+async function follow(ctx: Parameters<Semantics>[0], following: boolean): Promise<Response> {
+  const login = decodeURIComponent(gh(ctx).seg[2]!);
+  await put(ctx, { operation: following ? 'user_following.add' : 'user_following.remove', subjectType: 'user_following', subjectId: `following:${me(ctx)}:${login}`, fields: { login, following } });
+  return send(ctx, { status: 204, body: undefined });
+}