@supersuit/suggest-a-change 0.1.12 → 0.2.0

package/dist/github/relay.js

@@ -0,0 +1,734 @@
+// RUN YOUR OWN SUGGESTION RELAY. One handler on a server the repo's owner runs, holding the private key of a GitHub App
+// the owner created (contents: write, issues: write) and installed on the repos suggestions go to. It does four things,
+// chosen by the last segment of the path it is mounted on (.../file, .../follow-up, .../status, .../attach):
+//
+// - file: for someone with NO access to the repo, not even read. The relay runs the privacy catch itself, saves the
+//   files to the suggestion-attachments branch, then opens the issue AS THE APP with the filer's name (never their
+//   account), and remembers which identity filed which issue.
+// - follow-up and status: only for the identity that filed that report.
+// - attach: for a filer who opened the issue themselves but cannot push; the relay proves they could file there by
+//   reading the issue and requiring it to carry the report.
+//
+// Web-standard only: Request, Response, fetch, crypto.subtle.
+import { CEILINGS, isRepoName, isReportId, validContact, validateReport } from '../contract.mjs';
+import { cappedText, json } from '../server/http.js';
+import { ACCEPTED_TYPES, canonicalType, sameType, sniffType } from '../server/sniff.js';
+import { withPlace } from '../server/geo.js';
+import { addFollowUp, fileIssue, github, GitHubError, issueStates, issueStatus } from './api.js';
+import { BODY_LIMIT, composeIssue, endsWithFiledBy } from './compose.js';
+import { ATTACHMENTS_BRANCH, attachmentUrl, branchHost } from './hosts.js';
+import { privacyCatch, redact } from './privacy.js';
+/** A voice recording's ceiling; the same number as the server half's VOICE_FILE_BYTES (a test holds them together). */
+export const RELAY_VOICE_BYTES = 25 * 2 ** 20;
+export const RELAY_LIMITS = {
+    perPersonPerDay: CEILINGS.perPersonPerDay,
+    bytesPerPersonPerDay: 300 * 2 ** 20,
+    images: CEILINGS.images, imageBytes: CEILINGS.imageBytes,
+    videos: CEILINGS.videos, videoBytes: CEILINGS.videoBytes,
+    voice: 60, voiceBytes: RELAY_VOICE_BYTES,
+    closedGraceMs: 7 * 24 * 3600_000,
+    inlineBytes: 3 * 2 ** 20,
+};
+/** In memory, so ONE SERVER INSTANCE ONLY: a platform that runs several instances (most serverless hosts) needs a store
+ *  backed by its database, or the caps, the idempotency and who-filed-what are per instance and lost on restart. Each
+ *  method below changes what it checks before it yields, which is what makes it atomic in one process. */
+export function memoryUsage({ now = () => Date.now() } = {}) {
+    const stagedSizes = new Map();
+    const days = new Map();
+    const bytes = new Map();
+    const held = new Map();
+    const owners = new Map();
+    const filings = new Map();
+    const issues = new Map();
+    let n = 0;
+    return {
+        async reserve(a, d, r, b, lim) {
+            const k = `${a}\u0000${d}`;
+            const set = days.get(k) ?? new Set();
+            const counted = !set.has(r);
+            if (counted && set.size >= lim.reports)
+                return { ok: false, over: 'reports' };
+            if ((bytes.get(k) ?? 0) + b > lim.bytes)
+                return { ok: false, over: 'bytes' };
+            if (counted) {
+                set.add(r);
+                days.set(k, set);
+            }
+            bytes.set(k, (bytes.get(k) ?? 0) + b);
+            const token = `t${++n}`;
+            held.set(token, { k, reportId: r, counted, bytes: b });
+            return { ok: true, token };
+        },
+        async commit(t) { held.delete(t); },
+        async release(t) {
+            const h = held.get(t);
+            if (!h)
+                return;
+            held.delete(t);
+            if (h.counted)
+                days.get(h.k)?.delete(h.reportId);
+            bytes.set(h.k, Math.max(0, (bytes.get(h.k) ?? 0) - h.bytes));
+        },
+        async bind(repo, r, a) { const k = `${repo}#${r}`; const had = owners.get(k); if (had === undefined) {
+            owners.set(k, a);
+            return 'ok';
+        } return had === a ? 'ok' : 'taken'; },
+        async begin(repo, r, _a, leaseMs) {
+            const k = `${repo}#${r}`;
+            const had = filings.get(k);
+            if (had?.state === 'filed')
+                return had;
+            if (had?.state === 'busy' && had.until > now())
+                return { state: 'busy' };
+            filings.set(k, { state: 'busy', until: now() + leaseMs });
+            return { state: 'go' };
+        },
+        async stage(k, b) { stagedSizes.set(k, b); },
+        async staged(k) { return stagedSizes.get(k) ?? null; },
+        async unstage(k) { stagedSizes.delete(k); },
+        async finish(repo, rec) { filings.set(`${repo}#${rec.reportId}`, { state: 'filed', ...rec }); issues.set(`${repo}#${rec.number}`, rec); },
+        async abandon(repo, r) { const k = `${repo}#${r}`; if (filings.get(k)?.state === 'busy')
+            filings.delete(k); },
+        async filer(repo, num) { return issues.get(`${repo}#${num}`) ?? null; },
+    };
+}
+/** How long a filing holds its report before another try may take it over (its process is presumed dead). */
+export const FILING_LEASE_MS = 5 * 60_000;
+const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const B64 = /^[A-Za-z0-9+/]+={0,2}$/;
+const ACTIONS = ['file', 'follow-up', 'status', 'attach', 'upload-url'];
+const enc = new TextEncoder();
+const b64url = (bytes) => {
+    let s = '';
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+};
+function fromBase64(s) {
+    if (!s || s.length % 4 !== 0 || !B64.test(s))
+        return null;
+    try {
+        const bin = atob(s);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    catch {
+        return null;
+    }
+}
+/** DER length bytes. */
+const derLen = (n) => (n < 0x80 ? [n] : (() => { const b = []; while (n > 0) {
+    b.unshift(n & 0xff);
+    n >>= 8;
+} return [0x80 | b.length, ...b]; })());
+/** Wraps a PKCS#1 RSA key (what GitHub hands out) in the PKCS#8 envelope crypto.subtle imports. */
+function pkcs1To8(pkcs1) {
+    const algo = [0x30, 0x0d, 0x06, 0x09, 0x2a, 0x86, 0x48, 0x86, 0xf7, 0x0d, 0x01, 0x01, 0x01, 0x05, 0x00];
+    const octet = [0x04, ...derLen(pkcs1.length)];
+    const inner = [0x02, 0x01, 0x00, ...algo, ...octet];
+    const total = inner.length + pkcs1.length;
+    const out = new Uint8Array(1 + derLen(total).length + total);
+    out.set([0x30, ...derLen(total), ...inner]);
+    out.set(pkcs1, out.length - pkcs1.length);
+    return out;
+}
+async function importKey(pem) {
+    const body = pem.replace(/-----(BEGIN|END) [A-Z ]+-----/g, '').replace(/\s+/g, '');
+    const der = fromBase64(body);
+    if (!der)
+        throw new Error('the App private key is not a PEM key');
+    const pkcs8 = /BEGIN RSA PRIVATE KEY/.test(pem) ? pkcs1To8(der) : der;
+    return crypto.subtle.importKey('pkcs8', pkcs8, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, ['sign']);
+}
+/** The App's own JWT (RS256), good for nine minutes, issued a minute early for clock drift, as GitHub asks. */
+async function appJwt(key, id, nowMs) {
+    const t = Math.floor(nowMs / 1000);
+    const head = b64url(enc.encode(JSON.stringify({ alg: 'RS256', typ: 'JWT' })));
+    const body = b64url(enc.encode(JSON.stringify({ iat: t - 60, exp: t + 540, iss: id })));
+    const sig = new Uint8Array(await crypto.subtle.sign('RSASSA-PKCS1-v1_5', key, enc.encode(`${head}.${body}`)));
+    return `${head}.${body}.${b64url(sig)}`;
+}
+/** What kind of attachment a name in the folder is, by its extension (the names the module's sheet writes). */
+const kindByName = (name) => {
+    const ext = name.split('.').pop()?.toLowerCase() ?? '';
+    if (['png', 'jpg', 'jpeg', 'webp', 'heic', 'heif', 'gif'].includes(ext))
+        return 'image';
+    if (['mp4', 'm4v', 'mov', 'webm'].includes(ext) && !name.startsWith('voice-') && !name.startsWith('added-'))
+        return 'video';
+    if (['m4a', 'aac', 'mp3', 'wav', 'ogg', 'opus', 'webm', 'mp4', 'bin'].includes(ext))
+        return 'voice';
+    return null;
+};
+const kindOf = (type) => (type.startsWith('image/') ? 'image' : type.startsWith('video/') ? 'video' : 'voice');
+const stageKey = (account, reportId, name) => `staging/${encodeURIComponent(account)}/${reportId}/${name}`;
+/** Everything a staged object holds, refusing past `max` as it is read. */
+async function bytesOf(got, max) {
+    if (got instanceof Uint8Array)
+        return got.length > max ? null : got;
+    if (got instanceof ArrayBuffer)
+        return got.byteLength > max ? null : new Uint8Array(got);
+    const parts = [];
+    let n = 0;
+    const reader = got.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        n += value.length;
+        if (n > max) {
+            await reader.cancel();
+            return null;
+        }
+        parts.push(value);
+    }
+    const out = new Uint8Array(n);
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+export function createSuggestionRelay(opts, only) {
+    const limits = { ...RELAY_LIMITS };
+    for (const [k, v] of Object.entries(opts.limits ?? {})) {
+        if (typeof v !== 'number' || !(k in RELAY_LIMITS))
+            continue;
+        if (v > RELAY_LIMITS[k])
+            throw new Error(`limits.${k} may lower the relay's ${RELAY_LIMITS[k]}, never raise it`);
+        limits[k] = v;
+    }
+    const id = String(opts.app.id);
+    const cfgBase = { fetch: opts.fetch, api: opts.api };
+    const usage = opts.usage ?? memoryUsage();
+    const now = opts.now ?? (() => Date.now());
+    const day = () => new Date(now()).toISOString().slice(0, 10);
+    let key = null;
+    // The largest body each action can need, base64 and the rest of the JSON included, and never more than one day's
+    // byte budget allows: a body past it is refused by its declared length, or as soon as the count passes it.
+    const b64 = (n) => Math.ceil(n / 3) * 4;
+    const room = 64 * 1024;
+    const budget = b64(limits.bytesPerPersonPerDay) + room;
+    const oneCap = Math.min(b64(Math.min(limits.inlineBytes, Math.max(limits.imageBytes, limits.videoBytes, limits.voiceBytes))) + room, budget);
+    const reportCap = Math.min(b64(Math.min(limits.inlineBytes, limits.imageBytes) * limits.images + Math.min(limits.inlineBytes, limits.videoBytes) * limits.videos + Math.min(limits.inlineBytes, limits.voiceBytes) * 10) + 4 * room, budget);
+    const caps = { file: reportCap, 'follow-up': oneCap, status: room, attach: oneCap, 'upload-url': room };
+    const bad = (error) => json(400, { error });
+    const gone = (e) => json(502, { error: 'GitHub could not be reached or refused the relay; try again', ...(e instanceof GitHubError ? { status: e.status } : {}) });
+    /** A token for one repo, as the App's installation on it; a Response when the App is not installed there. */
+    async function repoToken(repo) {
+        key ??= importKey(opts.app.privateKey);
+        const jwt = await appJwt(await key, id, now());
+        let installation;
+        try {
+            installation = (await github({ ...cfgBase, token: jwt }, 'GET', `/repos/${repo}/installation`)).body.id;
+        }
+        catch (e) {
+            if (e instanceof GitHubError && e.status === 404)
+                return json(403, { error: `the app is not installed on ${repo}` });
+            throw e;
+        }
+        return (await github({ ...cfgBase, token: jwt }, 'POST', `/app/installations/${installation}/access_tokens`, { repositories: [repo.split('/')[1]] })).body.token;
+    }
+    const kindCap = (kind) => (kind === 'image' ? limits.imageBytes : kind === 'video' ? limits.videoBytes : limits.voiceBytes);
+    const kindOfType = (t) => (t.startsWith('audio/') ? 'voice' : kindOf(t));
+    /** One file, inline (base64 `bytes`, up to `inlineBytes`) or `staged` (put to an upload-url link first): a plain name,
+     *  an accepted type by its bytes that agrees with what was declared, within its kind's cap. */
+    async function checkFile(f, declared, account, reportId) {
+        const x = f;
+        if (!x || typeof x !== 'object' || typeof x.name !== 'string' || !FILE.test(x.name))
+            return bad('a file name is not a plain file name');
+        if (typeof x.type !== 'string')
+            return bad(`${x.name} has no type`);
+        const kind = kindOfType(x.type);
+        let bytes;
+        let stagedKey;
+        if (x.staged !== undefined) {
+            if (!opts.staging)
+                return bad(`${x.name} is staged, and this relay has no staging`);
+            if (x.staged !== true && x.staged !== x.name)
+                return bad(`${x.name} is staged under another name`);
+            stagedKey = stageKey(account, reportId, x.name);
+            const heldFor = await usage.staged(stagedKey);
+            if (heldFor === null)
+                return bad(`${x.name} was never uploaded; ask upload-url for a link and put it there first`);
+            const got = await opts.staging.read(stagedKey);
+            if (!got)
+                return bad(`${x.name} was never uploaded; ask upload-url for a link and put it there first`);
+            // Read with a counter, stopping past what upload-url held for it (and the kind's own cap).
+            const limit = Math.min(heldFor, kindCap(kind));
+            bytes = await bytesOf(got, limit);
+            if (!bytes)
+                return json(413, { error: `${x.name} is larger than the ${limit} bytes it was given a link for` });
+        }
+        else {
+            bytes = typeof x.bytes === 'string' ? fromBase64(x.bytes) : null;
+            if (!bytes || !bytes.length)
+                return bad(`${x.name} is not base64`);
+            if (bytes.length > limits.inlineBytes && bytes.length <= kindCap(kind)) {
+                return json(413, { error: opts.staging ? `${x.name} is larger than this relay takes in one request; send it staged (upload-url)` : `${x.name} is larger than this relay takes in one request, and it has no staging for larger files` });
+            }
+        }
+        if (!bytes.length)
+            return bad(`${x.name} is empty`);
+        const real = sniffType(bytes.subarray(0, 64));
+        if (!real || !ACCEPTED_TYPES.includes(real))
+            return json(422, { error: 'the file is not a picture, video or recording this module accepts' });
+        if (!sameType(x.type, real) || (declared && !sameType(declared, real)))
+            return json(422, { error: 'the file is not the type it was declared as' });
+        const max = kindCap(kind);
+        if (bytes.length > max)
+            return json(413, { error: `that file is larger than the ${max} bytes allowed` });
+        return { name: x.name, type: real, kind, bytes, ...(stagedKey ? { stagedKey } : {}) };
+    }
+    /** The bytes a request still has to hold today: inline files only, since upload-url held a staged file's up front. */
+    const inlineBytesOf = (files) => files.reduce((n, f) => n + (f.stagedKey ? 0 : f.bytes.length), 0);
+    const discardStaged = async (files) => {
+        for (const f of files)
+            if (f.stagedKey) {
+                try {
+                    await opts.staging?.discard(f.stagedKey);
+                    await usage.unstage(f.stagedKey);
+                }
+                catch { /* the bucket's own expiry catches it */ }
+            }
+    };
+    /** One request's files: each name once, and no more of each kind than a report may carry. */
+    const checkMany = async (list, declared, account, reportId) => {
+        const seen = new Set();
+        const out = [];
+        for (const f of list) {
+            const name = f?.name;
+            if (typeof name === 'string' && seen.has(name))
+                return bad(`${name} is listed twice`);
+            if (typeof name === 'string')
+                seen.add(name);
+            const want = declared(name);
+            if (want === false)
+                return bad(`${String(name)} is not a file the report declares`);
+            const c = await checkFile(f, want === 'audio/*' ? undefined : want, account, reportId);
+            if (c instanceof Response)
+                return c;
+            if (want === 'audio/*' && c.kind !== 'voice')
+                return json(422, { error: `${c.name} is a voice note and is not audio` });
+            out.push(c);
+        }
+        const count = (k) => out.filter((c) => c.kind === k).length;
+        if (count('image') > limits.images || count('video') > limits.videos || count('voice') > limits.voice)
+            return bad(`a request carries at most ${limits.images} pictures, ${limits.videos} video and ${limits.voice} recordings`);
+        return out;
+    };
+    /** The catch, on the relay, over every string that would reach the issue. A credential refuses by its kind (never its
+     *  text). Anything else holds, unless the filer says they redacted: then the relay redacts what it found itself and
+     *  answers the clean copy, so raw text is never filed on the filer's word. */
+    function catchIt(readable, account, redacted) {
+        const { hits } = privacyCatch(readable, { people: opts.privacy?.people ?? [], secrets: [...(opts.privacy?.secrets ?? []), account] });
+        const creds = hits.filter((h) => h.kind === 'credential');
+        if (creds.length)
+            return { res: json(422, { error: `a credential was found in ${[...new Set(creds.map((h) => h.field))].join(', ')}; it is never filed`, kinds: ['credential'] }) };
+        if (hits.length && !redacted)
+            return { res: json(409, { held: true, hits: hits.map((h) => ({ kind: h.kind, field: h.field })) }) };
+        return { clean: hits.length ? redact(readable, hits) : readable };
+    }
+    async function readJson(req, cap) {
+        const text = await cappedText(req, cap);
+        if (typeof text !== 'string')
+            return text;
+        try {
+            const v = JSON.parse(text);
+            return v && typeof v === 'object' && !Array.isArray(v) ? v : bad('the body is not a JSON object');
+        }
+        catch {
+            return bad('the body is not JSON');
+        }
+    }
+    async function allowed(account, repo) {
+        const list = opts.repos ? await opts.repos(account) : null;
+        return list && !list.includes(repo) ? json(403, { error: `this account may not file on ${repo}` }) : null;
+    }
+    /** Today's allowance, held atomically for this request: the token to commit or release, or the refusal. */
+    async function reserve(account, reportId, bytes) {
+        const r = await usage.reserve(account, day(), reportId, bytes, { reports: limits.perPersonPerDay, bytes: limits.bytesPerPersonPerDay });
+        if (r.ok)
+            return { token: r.token };
+        return json(429, { error: r.over === 'reports' ? 'you have reached today\'s limit of suggestions' : 'you have reached today\'s limit of attachments' });
+    }
+    /** The contact to share: the host's, and only when the request asked (the person left it ticked). */
+    const contactFor = (me, asked) => (asked !== undefined && me.contact && !validContact(me.contact).length ? me.contact : undefined);
+    async function file(me, body, req) {
+        const account = me.account;
+        const repo = body.repo;
+        if (!isRepoName(repo))
+            return bad('repo is not owner/name');
+        const refused = await allowed(account, repo);
+        if (refused)
+            return refused;
+        const report = body.report;
+        if (!report || typeof report !== 'object')
+            return bad('report is needed');
+        const problems = validateReport(report);
+        if (problems.length)
+            return json(400, { error: 'the report is not valid', problems });
+        const reportId = String(report.id);
+        const declared = [...(report.media ?? []).map((m) => [m.file, m.type]), ...(report.voice ?? []).map((v) => [v.file, 'audio/*'])];
+        const checked = await checkMany(Array.isArray(body.files) ? body.files : [], (n) => declared.find(([d]) => d === n)?.[1] ?? false, account, reportId);
+        if (checked instanceof Response)
+            return checked;
+        const files = checked;
+        // The app is the host's: a request names one by its id in the host's table, or none.
+        const appId = body.app;
+        if (appId !== undefined && opts.apps && (typeof appId !== 'string' || !Object.prototype.hasOwnProperty.call(opts.apps, appId)))
+            return bad('unknown app');
+        const app = opts.apps && typeof appId === 'string' ? opts.apps[appId] : undefined;
+        // Who it is from comes from the host, never the request: the name, the role and the contact.
+        const contact = contactFor(me, report.who?.contact);
+        const appVersion = typeof report.diagnostics?.appVersion === 'string' ? report.diagnostics.appVersion : undefined;
+        const readable = {
+            words: report.words, followUps: report.followUps, where: report.where, diagnostics: report.diagnostics,
+            context: report.context, transcript: typeof body.transcript === 'string' ? body.transcript : undefined,
+            filerName: me.name, appName: app?.name, who: { contact },
+            files: files.map((f) => ({ name: f.name })),
+        };
+        // A hit in a file name cannot be redacted (the file is named by it): it holds the report whatever the filer said.
+        const nameHits = privacyCatch({ files: readable.files }, { people: opts.privacy?.people ?? [], secrets: [...(opts.privacy?.secrets ?? []), account] }).hits;
+        if (nameHits.some((h) => h.kind === 'credential'))
+            return json(422, { error: 'a credential was found in a file name; it is never filed', kinds: ['credential'] });
+        if (nameHits.length)
+            return json(409, { held: true, hits: nameHits.map((h) => ({ kind: h.kind, field: h.field })) });
+        const caught = catchIt(readable, account, body.redacted === true);
+        if ('res' in caught)
+            return caught.res;
+        const clean = caught.clean;
+        const context = clean.context !== undefined || opts.geo ? await withPlace(clean.context, req, opts.geo) : undefined;
+        if ((await usage.bind(repo, reportId, account)) === 'taken')
+            return json(409, { error: 'that report id is taken; start the suggestion again' });
+        // Once per report: a repeat answers the issue it already became.
+        const began = await usage.begin(repo, reportId, account, FILING_LEASE_MS);
+        if (began.state === 'filed')
+            return began.account === account ? json(200, { number: began.number, url: began.url }) : json(409, { error: 'that report id is taken; start the suggestion again' });
+        if (began.state === 'busy')
+            return json(409, { error: 'that report is being filed right now; try again in a moment' });
+        const held = await reserve(account, reportId, inlineBytesOf(files));
+        if (held instanceof Response) {
+            await usage.abandon(repo, reportId);
+            return held;
+        }
+        try {
+            const token = await repoToken(repo);
+            if (token instanceof Response) {
+                await usage.abandon(repo, reportId);
+                await usage.release(held.token);
+                return token;
+            }
+            // The files first, so the issue opens complete; a file already there from an interrupted try is its link.
+            const host = branchHost({ repo, token, fetch: opts.fetch });
+            const attachmentUrls = {};
+            for (const f of files)
+                attachmentUrls[f.name] = (await host.put({ repo, issue: 0, reportId }, { name: f.name, type: f.type, bytes: f.bytes })).url;
+            const role = me.role ?? 'member';
+            // The report's own app and filer names, if a request put any there, never reach the issue: only the host's do.
+            const { appName: _a, filerName: _f, ...plain } = report;
+            void _a;
+            void _f;
+            const issue = composeIssue({ ...plain, words: clean.words, where: clean.where, diagnostics: clean.diagnostics, ...(context !== undefined ? { context } : {}), who: { role, ...(clean.who.contact ? { contact: clean.who.contact } : {}) } }, {
+                appName: typeof clean.appName === 'string' ? clean.appName.slice(0, 100) : undefined,
+                appLabel: app ? app.label : null,
+                appVersion: appVersion?.slice(0, 50),
+                filerName: typeof clean.filerName === 'string' && clean.filerName.trim() ? clean.filerName.trim().slice(0, 100) : 'Someone',
+                filerRole: role,
+                transcript: clean.transcript,
+                attachmentUrls,
+            });
+            const made = await fileIssue({ repo, token, fetch: opts.fetch, api: opts.api }, issue);
+            // The issue exists now. Record it (the store is asked again if it blinks); a filing that made an issue is never
+            // abandoned, so a retry answers this issue, or waits out the lease, and never opens a second one.
+            const record = { account, reportId, number: made.number, url: made.url };
+            for (let attempt = 0;; attempt++) {
+                try {
+                    await usage.finish(repo, record);
+                    break;
+                }
+                catch (e) {
+                    if (attempt >= 2) {
+                        void e;
+                        break;
+                    }
+                }
+            }
+            try {
+                await usage.commit(held.token);
+            }
+            catch { /* the day's count is best effort once the issue exists */ }
+            await discardStaged(files);
+            return json(200, { number: made.number, url: made.url });
+        }
+        catch (e) {
+            await usage.abandon(repo, reportId);
+            await usage.release(held.token);
+            return gone(e);
+        }
+    }
+    async function followUp(me, body) {
+        const account = me.account;
+        const { repo, number, reportId } = body;
+        if (!isRepoName(repo))
+            return bad('repo is not owner/name');
+        if (!Number.isInteger(number) || number < 1)
+            return bad('number is not an issue number');
+        if (typeof reportId !== 'string' || !isReportId(reportId))
+            return bad('reportId is not a report id');
+        const refused = await allowed(account, repo);
+        if (refused)
+            return refused;
+        const rec = await usage.filer(repo, number);
+        if (!rec || rec.account !== account || rec.reportId !== reportId)
+            return json(403, { error: 'only the person who filed it may add to it' });
+        const checked = await checkMany(Array.isArray(body.files) ? body.files : [], () => undefined, account, reportId);
+        if (checked instanceof Response)
+            return checked;
+        const files = checked;
+        const readable = { words: typeof body.words === 'string' ? body.words.slice(0, 20_000) : '', transcript: typeof body.transcript === 'string' ? body.transcript : undefined, files: files.map((f) => ({ name: f.name })) };
+        const caught = catchIt(readable, account, body.redacted === true);
+        if ('res' in caught)
+            return caught.res;
+        const { words, transcript } = caught.clean;
+        if (!words.trim() && !transcript && !files.length)
+            return bad('a follow-up needs words or a file');
+        // The comment is composed, and measured, BEFORE anything is written: a file's link is known from its path.
+        const folder = `attachments/${reportId}`;
+        const links = files.map((f) => { const url = attachmentUrl(repo, ATTACHMENTS_BRANCH, `${folder}/${f.name}`); return f.kind === 'image' ? `![${f.name}](${url})` : `[${f.name}](${url})`; });
+        // A follow-up is the person's own words, so it sits in a fence like the words of the report.
+        const fenced = (s) => { const run = Math.max(0, ...[...s.matchAll(/`+/g)].map((m) => m[0].length)); const f = '`'.repeat(Math.max(3, run + 1)); return `${f}\n${s}\n${f}`; };
+        const text = ['## Added later', words.trim() ? fenced(words.trim()) : '', transcript ? `\n### Voice note\n${fenced(transcript.trim())}` : '', links.length ? `\n${links.join('\n')}` : ''].filter(Boolean).join('\n');
+        if (text.length > BODY_LIMIT)
+            return json(413, { error: `that follow-up is longer than GitHub takes in a comment (${BODY_LIMIT} characters)` });
+        const held = await reserve(account, reportId, inlineBytesOf(files));
+        if (held instanceof Response)
+            return held;
+        try {
+            const token = await repoToken(repo);
+            if (token instanceof Response) {
+                await usage.release(held.token);
+                return token;
+            }
+            // The report's own caps hold across follow-ups, as they do for attach.
+            if (files.length) {
+                let names = [];
+                try {
+                    names = (await github({ ...cfgBase, token }, 'GET', `/repos/${repo}/contents/${folder}?ref=${ATTACHMENTS_BRANCH}`)).body.map((x) => x.name);
+                }
+                catch (e) {
+                    if (!(e instanceof GitHubError) || e.status !== 404)
+                        throw e;
+                }
+                for (const f of files)
+                    if (names.includes(f.name)) {
+                        await usage.release(held.token);
+                        return json(409, { error: `${folder}/${f.name} is already written` });
+                    }
+                for (const k of ['image', 'video', 'voice']) {
+                    const room = k === 'image' ? limits.images : k === 'video' ? limits.videos : limits.voice;
+                    if (names.filter((n) => kindByName(n) === k).length + files.filter((f) => f.kind === k).length > room) {
+                        await usage.release(held.token);
+                        return json(422, { error: `this report has all the ${k === 'voice' ? 'recordings' : `${k}s`} it can carry` });
+                    }
+                }
+            }
+            const host = branchHost({ repo, token, fetch: opts.fetch });
+            for (const f of files)
+                await host.put({ repo, issue: number, reportId }, { name: f.name, type: f.type, bytes: f.bytes });
+            const got = await addFollowUp({ repo, token, fetch: opts.fetch, api: opts.api }, number, text);
+            await usage.commit(held.token);
+            await discardStaged(files);
+            return json(200, got);
+        }
+        catch (e) {
+            await usage.release(held.token);
+            return gone(e);
+        }
+    }
+    async function status(me, body) {
+        const items = Array.isArray(body.items) ? body.items : null;
+        if (!items || !items.length || items.length > 100)
+            return bad('items is a list of 1 to 100 { repo, number }');
+        const list = [];
+        for (const it of items) {
+            const x = it;
+            if (!isRepoName(x?.repo) || !Number.isInteger(x.number) || x.number < 1)
+                return bad('an item is not { repo, number }');
+            const rec = await usage.filer(x.repo, x.number);
+            if (!rec || rec.account !== me.account)
+                return json(403, { error: 'only the person who filed an issue may ask its state' });
+            list.push({ repo: x.repo, number: x.number });
+        }
+        try {
+            const out = [];
+            for (const repo of [...new Set(list.map((i) => i.repo))]) {
+                const token = await repoToken(repo);
+                if (token instanceof Response)
+                    return token;
+                for (const s of await issueStates({ token, fetch: opts.fetch, api: opts.api }, list.filter((i) => i.repo === repo))) {
+                    out.push({ repo: s.repo, number: s.number, status: s.missing ? 'missing' : issueStatus(s), ...(s.reason ? { reason: s.reason } : {}) });
+                }
+            }
+            return json(200, { items: out });
+        }
+        catch (e) {
+            return gone(e);
+        }
+    }
+    async function attach(me, body) {
+        const account = me.account;
+        const { repo, issue, reportId } = body;
+        if (!isRepoName(repo))
+            return bad('repo is not owner/name');
+        if (!Number.isInteger(issue) || issue < 1)
+            return bad('issue is not an issue number');
+        if (typeof reportId !== 'string' || !isReportId(reportId))
+            return bad('reportId is not a report id');
+        const refused = await allowed(account, repo);
+        if (refused)
+            return refused;
+        const c = await checkFile(body, undefined, account, reportId);
+        if (c instanceof Response)
+            return c;
+        // An issue the relay filed belongs to whoever filed it through the relay.
+        const mine = await usage.filer(repo, issue);
+        if (mine && (mine.account !== account || mine.reportId !== reportId))
+            return json(403, { error: 'this report belongs to someone else' });
+        const held = await reserve(account, reportId, inlineBytesOf([c]));
+        if (held instanceof Response)
+            return held;
+        const fail = async (res) => { await usage.release(held.token); return res; };
+        try {
+            const token = await repoToken(repo);
+            if (token instanceof Response)
+                return fail(token);
+            const cfg = { ...cfgBase, token };
+            // Proof the caller could file here: the issue exists, is an issue, is open or recently closed, and ends with this report's line.
+            let found;
+            try {
+                found = (await github(cfg, 'GET', `/repos/${repo}/issues/${issue}`)).body;
+            }
+            catch (e) {
+                if (e instanceof GitHubError && e.status === 404)
+                    return fail(json(404, { error: `there is no issue #${issue} on ${repo}` }));
+                throw e;
+            }
+            if (found.pull_request)
+                return fail(json(403, { error: `#${issue} is a pull request, not an issue` }));
+            if (!endsWithFiledBy(String(found.body ?? ''), reportId))
+                return fail(json(403, { error: `issue #${issue} does not carry Report ${reportId}` }));
+            if (found.state === 'closed' && found.closed_at && now() - Date.parse(found.closed_at) > limits.closedGraceMs)
+                return fail(json(403, { error: `issue #${issue} closed too long ago to add to` }));
+            // An issue someone opened themselves takes files only from them: the login that opened it must be one this
+            // identity vouches for. Nothing is claimed until that proof holds, so a stranger's failed try blocks nobody.
+            if (!mine) {
+                const opener = String(found.user?.login ?? '').toLowerCase();
+                if (!opener || !me.githubLogin || me.githubLogin.toLowerCase() !== opener)
+                    return fail(json(403, { error: `only the person who opened issue #${issue} may attach to it` }));
+            }
+            if ((await usage.bind(repo, reportId, account)) === 'taken')
+                return fail(json(403, { error: 'this report belongs to someone else' }));
+            // What the report already holds: never the same path twice, never past its caps.
+            const folder = `attachments/${reportId}`;
+            let names = [];
+            try {
+                names = (await github(cfg, 'GET', `/repos/${repo}/contents/${folder}?ref=${ATTACHMENTS_BRANCH}`)).body.map((x) => x.name);
+            }
+            catch (e) {
+                if (!(e instanceof GitHubError) || e.status !== 404)
+                    throw e;
+            }
+            if (names.includes(c.name))
+                return fail(json(409, { error: `${folder}/${c.name} is already written` }));
+            const have = names.filter((n) => kindByName(n) === c.kind).length;
+            const room = c.kind === 'image' ? limits.images : c.kind === 'video' ? limits.videos : limits.voice;
+            if (have >= room)
+                return fail(json(422, { error: `this report has all the ${c.kind === 'voice' ? 'recordings' : `${c.kind}s`} it can carry` }));
+            try {
+                await branchHost({ repo, token, fetch: opts.fetch, refuseExisting: true }).put({ repo, issue: issue, reportId }, { name: c.name, type: c.type, bytes: c.bytes });
+            }
+            catch (e) {
+                if (e instanceof GitHubError && e.status === 409)
+                    return fail(json(409, { error: `${folder}/${c.name} is already written` }));
+                throw e;
+            }
+            await usage.commit(held.token);
+            await discardStaged([c]);
+            return json(200, { url: attachmentUrl(repo, ATTACHMENTS_BRANCH, `${folder}/${c.name}`) });
+        }
+        catch (e) {
+            await usage.release(held.token);
+            return gone(e);
+        }
+    }
+    /** A one-time signed PUT for one file of a report, for a file too large to send inside a request. Bound to this
+     *  identity and report like a filing, with the day's bytes held now (the later file or attach does not hold them again). */
+    async function uploadUrl(me, body) {
+        const account = me.account;
+        const { repo, reportId, name, type, bytes } = body;
+        if (!isRepoName(repo))
+            return bad('repo is not owner/name');
+        if (typeof reportId !== 'string' || !isReportId(reportId))
+            return bad('reportId is not a report id');
+        if (typeof name !== 'string' || !FILE.test(name))
+            return bad('name is not a plain file name');
+        if (typeof type !== 'string' || !ACCEPTED_TYPES.includes(canonicalType(type)))
+            return json(422, { error: 'that is not a picture, video or recording this module accepts' });
+        if (!Number.isInteger(bytes) || bytes < 1)
+            return bad("bytes is the file's size");
+        const kind = kindOfType(canonicalType(type));
+        if (bytes > kindCap(kind))
+            return json(413, { error: `${name} is larger than the ${kindCap(kind)} bytes allowed` });
+        const refused = await allowed(account, repo);
+        if (refused)
+            return refused;
+        if ((await usage.bind(repo, reportId, account)) === 'taken')
+            return json(403, { error: 'this report belongs to someone else' });
+        const held = await reserve(account, reportId, bytes);
+        if (held instanceof Response)
+            return held;
+        try {
+            const key = stageKey(account, reportId, name);
+            const link = await opts.staging.uploadUrl(key, { type: canonicalType(type), bytes: bytes });
+            await usage.stage(key, bytes);
+            await usage.commit(held.token);
+            return json(200, { url: link.url, headers: link.headers ?? {}, staged: name });
+        }
+        catch (e) {
+            await usage.release(held.token);
+            return gone(e);
+        }
+    }
+    const run = { file, 'follow-up': followUp, status, attach, 'upload-url': uploadUrl };
+    /** What this relay can take, so a filer knows before it sends (no sign-in needed: it says nothing about anyone). */
+    const capabilities = () => json(200, {
+        actions: ACTIONS.filter((a) => (only ? a === only : a !== 'upload-url' || Boolean(opts.staging))),
+        staging: Boolean(opts.staging),
+        inlineBytes: limits.inlineBytes,
+        maxBytes: { image: limits.imageBytes, video: limits.videoBytes, voice: limits.voiceBytes },
+    });
+    return async function relay(req) {
+        // The action is the last segment of the path the handler is mounted on: .../file, .../follow-up, .../status, .../attach.
+        const last = new URL(req.url).pathname.replace(/\/+$/, '').split('/').pop() ?? '';
+        if (req.method === 'GET' && last === 'capabilities')
+            return capabilities();
+        const found = ACTIONS.find((a) => a === last && (a !== 'upload-url' || opts.staging));
+        const action = only ?? found;
+        if (!action)
+            return json(404, { error: `no such action; use one of ${ACTIONS.join(', ')}` });
+        if (req.method !== 'POST')
+            return json(405, { error: 'method not allowed' });
+        const me = await opts.identity(req);
+        if (!me || typeof me.account !== 'string' || !me.account)
+            return json(401, { error: 'sign in first' });
+        const body = await readJson(req, caps[action]);
+        if (body instanceof Response)
+            return body;
+        return run[action](me, body, req);
+    };
+}
+/** A relay that only attaches (the 0.2.0 shape): every request is `attach`, whatever its path. */
+export const createAttachRelay = (opts) => createSuggestionRelay(opts, 'attach');