@volter/twin-github 0.1.2 → 2.0.0

package/dist/src/semantics/security.js

@@ -0,0 +1,177 @@
+import { GITHUB_WORLD_USER, githubNotFound, resolvePlaneRef, paginate, toGithubCodeScanningAlert, toGithubCodeScanningAnalysis, toGithubDependabotAlert, toGithubSecretScanningAlert } from "../github-twin.js";
+import { asView, gh, put, send } from "./shared.js";
+import { dependabotOn, dependabotReads, manifestsAt } from "./push-reactions.js";
+const wantState = (query) => new URLSearchParams((query ?? '').replace(/^\?/, '')).get('state');
+const alertNumber = (ctx) => Number(decodeURIComponent(gh(ctx).seg[5]));
+const invalid = (ctx, resource, field) => 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, kind) {
+    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 = { 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, on) {
+    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() {
+    const codeScanningListRecentAnalyses = 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 = 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 = 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 = 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 = 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 = 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 = 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 = { 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/dist/src/semantics/shared.d.ts

@@ -0,0 +1,61 @@
+import type { SemanticsContext } from '@volter/world-core';
+import { type GithubAtomic, type GithubResponse, type GithubState, type GithubWrite, type GithubWriteEvent } from '../github-twin.js';
+/** 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 declare function asView(view: string, full: Record<string, unknown>): Record<string, unknown>;
+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 declare function gh(ctx: SemanticsContext): Gh;
+/** GitHub's projection over this request's tree. */
+export declare const githubStateOf: (ctx: SemanticsContext) => GithubState;
+/** GitHub's answer: JSON, or nothing for a 204 or an answer with no body. */
+export declare function send(ctx: SemanticsContext, r: GithubResponse): Response;
+/** A stored write, as the kernel records it: the subject's type, id, fields and operation name. */
+export declare function put(ctx: SemanticsContext, w: {
+    operation: string;
+    subjectType: string;
+    subjectId: string;
+    fields: Record<string, unknown>;
+}): Promise<Record<string, unknown>>;
+export declare function collectAnnouncements<T>(run: () => Promise<T>): Promise<{
+    value: T;
+    events: GithubWriteEvent[];
+}>;
+export declare function noteAnnounced(events: GithubWriteEvent[]): void;
+/** Deliver the webhooks a write announces. Fire-and-forget, like GitHub: a delivery failure never
+ *  fails the write. */
+export declare function announce(ctx: SemanticsContext, events: Array<GithubWriteEvent | undefined>): Promise<void>;
+/** One past the highest `<prefix>:<n>` subject id stored, tombstones included. */
+export declare function nextSeq(ctx: SemanticsContext, prefix: string): number;
+/** The pack helpers' atomic decision (GithubAtomic), made through this request's context. */
+export declare function atomic(ctx: SemanticsContext): GithubAtomic;
+/** The pack helpers' writer (GithubWrite), through this request's context. */
+export declare const writer: (ctx: SemanticsContext) => GithubWrite;
+/** 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 declare function identityOf(g: Gh): {
+    name: string;
+    email: string;
+};

package/dist/src/semantics/shared.js

@@ -0,0 +1,151 @@
+// 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 { callerLogin, githubState, resolveGithubNumber, twinUserId } from "../github-twin.js";
+import { emitGithubEvent, emitGithubInstallationEvents } from "../github-events.js";
+import surface from '../generated/surface.gen.json' with { type: 'json' };
+import { spanning } from "../manifest.js";
+const VIEWS = new Map(surface.resources.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, full) {
+    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 function gh(ctx) {
+    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 ?? {}),
+        state: () => githubStateOf(ctx),
+    };
+}
+/** GitHub's projection over this request's tree. */
+export const githubStateOf = (ctx) => githubState(ctx.root);
+/** GitHub's answer: JSON, or nothing for a 204 or an answer with no body. */
+export function send(ctx, r) {
+    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, w) {
+    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();
+export async function collectAnnouncements(run) {
+    const events = [];
+    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) {
+    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, events) {
+    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.js");
+            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.js");
+            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.js");
+            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 = {
+    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, prefix) {
+    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) {
+    return (decide) => ctx.atomically(() => {
+        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) => (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) {
+    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/dist/src/semantics/users.d.ts

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