@supersuit/suggest-a-change 0.1.13 → 0.2.1

package/dist/github/filer.d.ts

@@ -0,0 +1,72 @@
+import { type Fetch } from './api.ts';
+export interface RelayFile {
+    name: string;
+    type: string;
+    bytes: Uint8Array | ArrayBuffer | string;
+}
+export interface RelayFiling {
+    repo: string;
+    /** Which of the relay's apps this came from, by its id in the relay's own table (the relay names it and labels it). */
+    app?: string;
+    /** The report, in the contract's shape. The relay never writes the account id into the issue. */
+    report: Record<string, unknown>;
+    /** The name the issue says it was filed by. */
+    filerName?: string;
+    appName?: string;
+    appVersion?: string;
+    transcript?: string;
+    files?: RelayFile[];
+    /** True once the filer chose to file without what the privacy catch flagged (they replaced it themselves). */
+    redacted?: boolean;
+}
+export interface RelayFiler {
+    /** Answers the issue; a repeat of the same report answers the same issue. A held report throws status 409 with `{ held, hits }`. */
+    file(input: RelayFiling): Promise<{
+        number: number;
+        url: string;
+    }>;
+    followUp(input: {
+        repo: string;
+        number: number;
+        reportId: string;
+        words?: string;
+        transcript?: string;
+        files?: RelayFile[];
+        redacted?: boolean;
+    }): Promise<{
+        id: number;
+        url: string;
+    }>;
+    status(items: {
+        repo: string;
+        number: number;
+    }[]): Promise<{
+        repo: string;
+        number: number;
+        status: string;
+        reason?: string;
+    }[]>;
+    /** What the relay can take (asked once, then kept). */
+    capabilities(): Promise<RelayCapabilities>;
+}
+/** Files larger than this go to the relay staged (one signed PUT each) rather than inside the request. */
+export declare const STAGE_OVER_BYTES: number;
+export interface RelayCapabilities {
+    actions: string[];
+    staging: boolean;
+    inlineBytes: number;
+    maxBytes?: Record<string, number>;
+}
+/** `url` is where the relay is mounted; each action is posted to `<url>/<action>`. */
+export declare function relayFiler({ url, headers, fetch }: {
+    url: string;
+    headers?: Record<string, string>;
+    fetch?: Fetch;
+}): RelayFiler;
+/** True when this token can see the repo, so it can open an issue there itself; false on 401, 403 or 404 (or issues off). */
+export declare function canFileDirectly({ repo, token, fetch, api }: {
+    repo: string;
+    token: string;
+    fetch?: Fetch;
+    api?: string;
+}): Promise<boolean>;

package/dist/github/filer.js

@@ -0,0 +1,89 @@
+// THE FILER'S SIDE OF A SUGGESTION RELAY. `relayFiler` talks to any relay running `createSuggestionRelay`, at whatever
+// URL it is mounted on and with whatever header it checks. `canFileDirectly` says whether a filer's own token can see
+// the repo (and so open an issue there); `fileSuggestion` uses it to choose between filing directly and the relay.
+import { github, GitHubError } from './api.js';
+import { toBase64 } from './hosts.js';
+const files64 = (files = []) => files.map((f) => ({ name: f.name, type: f.type, bytes: typeof f.bytes === 'string' ? f.bytes : toBase64(f.bytes) }));
+/** Files larger than this go to the relay staged (one signed PUT each) rather than inside the request. */
+export const STAGE_OVER_BYTES = 2 * 2 ** 20;
+const sizeOf = (b) => (typeof b === 'string' ? Math.floor((b.length * 3) / 4) : b instanceof Uint8Array ? b.length : b.byteLength);
+const raw = (b) => {
+    if (b instanceof Uint8Array)
+        return b;
+    if (b instanceof ArrayBuffer)
+        return new Uint8Array(b);
+    const bin = atob(b);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+};
+/** `url` is where the relay is mounted; each action is posted to `<url>/<action>`. */
+export function relayFiler({ url, headers = {}, fetch }) {
+    if (!/^https?:\/\//.test(url))
+        throw new Error(`${JSON.stringify(url)} is not a relay URL`);
+    const base = url.replace(/\/+$/, '');
+    const f = fetch ?? globalThis.fetch;
+    const call = async (action, body) => {
+        const res = await f(`${base}/${action}`, { method: 'POST', headers: { ...headers, 'content-type': 'application/json' }, body: JSON.stringify(body) });
+        const text = await res.text();
+        let parsed = null;
+        try {
+            parsed = text ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = text;
+        }
+        if (!res.ok)
+            throw new GitHubError(`the suggestion relay answered ${res.status} to ${action}`, res.status, parsed);
+        return parsed;
+    };
+    let caps = null;
+    const capabilities = () => (caps ??= (async () => {
+        const res = await f(`${base}/capabilities`, { method: 'GET', headers });
+        if (!res.ok)
+            throw new GitHubError(`the suggestion relay answered ${res.status} to capabilities`, res.status, null);
+        return (await res.json());
+    })().catch((e) => { caps = null; throw e; }));
+    /** Each file inline, or, past STAGE_OVER_BYTES, put to a link from upload-url first and named as staged. A file the
+     *  relay cannot take at all is refused here, in words, before anything is filed. */
+    async function prepare(repo, reportId, files = []) {
+        if (!files.some((x) => sizeOf(x.bytes) > STAGE_OVER_BYTES))
+            return files64(files);
+        const c = await capabilities();
+        const out = [];
+        for (const x of files) {
+            const size = sizeOf(x.bytes);
+            if (size <= Math.min(STAGE_OVER_BYTES, c.inlineBytes)) {
+                out.push(...files64([x]));
+                continue;
+            }
+            if (!c.staging)
+                throw new Error(`${x.name} is larger than this relay takes in one request (${Math.round(c.inlineBytes / 2 ** 20)} MB), and it has no staging for larger files`);
+            const link = (await call('upload-url', { repo, reportId, name: x.name, type: x.type, bytes: size }));
+            const put = await f(link.url, { method: 'PUT', headers: link.headers ?? {}, body: raw(x.bytes) });
+            if (!put.ok)
+                throw new GitHubError(`the staging upload of ${x.name} answered ${put.status}`, put.status, null);
+            out.push({ name: x.name, type: x.type, staged: x.name });
+        }
+        return out;
+    }
+    return {
+        capabilities,
+        async file(input) { return call('file', { ...input, files: await prepare(input.repo, String(input.report.id), input.files) }); },
+        async followUp(input) { return call('follow-up', { ...input, files: await prepare(input.repo, input.reportId, input.files) }); },
+        async status(items) { return (await call('status', { items })).items; },
+    };
+}
+/** True when this token can see the repo, so it can open an issue there itself; false on 401, 403 or 404 (or issues off). */
+export async function canFileDirectly({ repo, token, fetch, api }) {
+    try {
+        const got = await github({ token, fetch, api }, 'GET', `/repos/${repo}`);
+        return got.body?.has_issues !== false;
+    }
+    catch (e) {
+        if (e instanceof GitHubError && [401, 403, 404].includes(e.status))
+            return false;
+        throw e;
+    }
+}

package/dist/github/hosts.d.ts

@@ -0,0 +1,41 @@
+import { type Fetch } from './api.ts';
+/** Which issue a file belongs to. The relay reads that issue and requires it to carry `Report <reportId>`. */
+export interface AttachmentTarget {
+    repo: string;
+    issue: number;
+    reportId: string;
+}
+export interface AttachmentFile {
+    name: string;
+    type: string;
+    bytes: Uint8Array | ArrayBuffer;
+}
+export interface AttachmentHost {
+    put(target: AttachmentTarget, file: AttachmentFile): Promise<{
+        url: string;
+    }>;
+}
+export declare const ATTACHMENTS_BRANCH = "suggestion-attachments";
+/** Up to this size a file goes through the contents API; past it, through the git data API (blob, tree, commit). */
+export declare const CONTENTS_API_BYTES = 1000000;
+/** Base64 with no dependency and no reliance on btoa's string rules. */
+export declare function toBase64(bytes: Uint8Array | ArrayBuffer): string;
+/** The link form that renders inline in a private issue, for the people who can read the repo. */
+export declare const attachmentUrl: (repo: string, branch: string, path: string) => string;
+/** Commits each file through the contents API with a token that can push (a maintainer's Mac, an app server's own key).
+ *  The branch is made the first time, as an orphan that shares no history with the code. A path already written is its link. */
+export declare function branchHost({ repo, token, branch, fetch, refuseExisting }: {
+    repo: string;
+    token: string;
+    branch?: string;
+    fetch?: Fetch; /** Throw (409) instead of answering the link when the path is already written. */
+    refuseExisting?: boolean;
+}): AttachmentHost;
+/** For a filer who cannot push: the file goes to an attachment relay (any URL running `createAttachRelay`, with whatever
+ *  header proves who is asking), which checks the named issue carries this report, saves the file through its own
+ *  GitHub App, and answers the link. */
+export declare function relayHost({ url, headers, fetch }: {
+    url: string;
+    headers?: Record<string, string>;
+    fetch?: Fetch;
+}): AttachmentHost;

package/dist/github/hosts.js

@@ -0,0 +1,154 @@
+// WHERE A SCREENSHOT OR RECORDING GOES (design: "Attachment parity for every filer"). GitHub has no API for attaching a
+// file to an issue, so each file is committed to the repo's own `suggestion-attachments` branch and linked: it shows to
+// exactly the people who can read the repo, and to nobody else. Two hosts ship: one for a filer that can push, one
+// through the repo owner's own GitHub App, by way of a suggestion relay, for everyone who cannot.
+import { isRepoName } from '../contract.mjs';
+import { github, GitHubError } from './api.js';
+export const ATTACHMENTS_BRANCH = 'suggestion-attachments';
+/** Up to this size a file goes through the contents API; past it, through the git data API (blob, tree, commit). */
+export const CONTENTS_API_BYTES = 1_000_000;
+const REPORT_ID = /^r-\d{14}-[a-z0-9]{6}$/;
+const FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+const B64 = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+/** Base64 with no dependency and no reliance on btoa's string rules. */
+export function toBase64(bytes) {
+    const b = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    let out = '';
+    for (let i = 0; i < b.length; i += 3) {
+        const n = (b[i] << 16) | ((b[i + 1] ?? 0) << 8) | (b[i + 2] ?? 0);
+        out += B64[(n >> 18) & 63] + B64[(n >> 12) & 63] + (i + 1 < b.length ? B64[(n >> 6) & 63] : '=') + (i + 2 < b.length ? B64[n & 63] : '=');
+    }
+    return out;
+}
+/** Refuses anything that would write outside attachments/<report id>/<file>. */
+function pathFor(t, name) {
+    if (!isRepoName(t.repo))
+        throw new Error(`${JSON.stringify(t.repo)} is not owner/name`);
+    if (!REPORT_ID.test(String(t.reportId)))
+        throw new Error(`${JSON.stringify(t.reportId)} is not a report id`);
+    if (!FILE.test(name))
+        throw new Error(`${JSON.stringify(name)} is not a plain file name`);
+    return `attachments/${t.reportId}/${name}`;
+}
+/** The link form that renders inline in a private issue, for the people who can read the repo. */
+export const attachmentUrl = (repo, branch, path) => `https://github.com/${repo}/blob/${branch}/${path}?raw=true`;
+/** Commits each file through the contents API with a token that can push (a maintainer's Mac, an app server's own key).
+ *  The branch is made the first time, as an orphan that shares no history with the code. A path already written is its link. */
+export function branchHost({ repo, token, branch = ATTACHMENTS_BRANCH, fetch, refuseExisting = false }) {
+    const cfg = { token, fetch };
+    let ready = null;
+    const ensure = () => (ready ??= (async () => {
+        try {
+            await github(cfg, 'GET', `/repos/${repo}/git/ref/heads/${branch}`);
+            return;
+        }
+        catch (e) {
+            if (!(e instanceof GitHubError) || e.status !== 404)
+                throw e;
+        }
+        const tree = await github(cfg, 'POST', `/repos/${repo}/git/trees`, { tree: [{ path: 'README.md', mode: '100644', type: 'blob', content: 'Screenshots and recordings attached to suggestions filed as issues on this repo, one folder per report. Nothing here is code.\n' }] });
+        const commit = await github(cfg, 'POST', `/repos/${repo}/git/commits`, { message: 'Start the suggestion attachments branch', tree: tree.body.sha, parents: [] });
+        try {
+            await github(cfg, 'POST', `/repos/${repo}/git/refs`, { ref: `refs/heads/${branch}`, sha: commit.body.sha });
+        }
+        catch (e) {
+            if (!(e instanceof GitHubError) || e.status !== 422)
+                throw e;
+        }
+    })().catch((e) => { ready = null; throw e; }));
+    /** A file past the contents API's comfortable size, through the git data API: a blob, a tree on top of the branch's
+     *  own, a commit, and the branch moved to it (once more if another write moved it first). Up to GitHub's 100 MB. */
+    async function putLarge(path, file, reportId) {
+        try {
+            await github(cfg, 'GET', `/repos/${repo}/contents/${path}?ref=${branch}`);
+            if (refuseExisting)
+                throw new GitHubError(`${path} is already written`, 409, null);
+            return; // written once: its link stands
+        }
+        catch (e) {
+            if (!(e instanceof GitHubError) || e.status !== 404)
+                throw e;
+        }
+        const blob = (await github(cfg, 'POST', `/repos/${repo}/git/blobs`, { content: toBase64(file.bytes), encoding: 'base64' })).body.sha;
+        for (let attempt = 0;; attempt++) {
+            const head = (await github(cfg, 'GET', `/repos/${repo}/git/ref/heads/${branch}`)).body.object.sha;
+            const base = (await github(cfg, 'GET', `/repos/${repo}/git/commits/${head}`)).body.tree.sha;
+            const tree = (await github(cfg, 'POST', `/repos/${repo}/git/trees`, { base_tree: base, tree: [{ path, mode: '100644', type: 'blob', sha: blob }] })).body.sha;
+            const commit = (await github(cfg, 'POST', `/repos/${repo}/git/commits`, { message: `Attach ${file.name} to ${reportId}`, tree, parents: [head] })).body.sha;
+            try {
+                await github(cfg, 'PATCH', `/repos/${repo}/git/refs/heads/${branch}`, { sha: commit });
+                return;
+            }
+            catch (e) {
+                if (!(e instanceof GitHubError) || e.status !== 422 || attempt >= 2)
+                    throw e;
+            } // someone else moved the branch: build on theirs
+        }
+    }
+    return {
+        async put(target, file) {
+            if (target.repo !== repo)
+                throw new Error(`this host writes to ${repo}, not ${target.repo}`);
+            const path = pathFor(target, file.name);
+            await ensure();
+            const size = file.bytes instanceof Uint8Array ? file.bytes.length : file.bytes.byteLength;
+            if (size > CONTENTS_API_BYTES) {
+                await putLarge(path, file, target.reportId);
+                return { url: attachmentUrl(repo, branch, path) };
+            }
+            try {
+                await github(cfg, 'PUT', `/repos/${repo}/contents/${path}`, { message: `Attach ${file.name} to ${target.reportId}`, content: toBase64(file.bytes), branch });
+            }
+            catch (e) {
+                if (!(e instanceof GitHubError) || e.status !== 422)
+                    throw e;
+                // A 422 means "already there" only if it is there: look, and pass any other refusal on as it came.
+                let there = false;
+                try {
+                    await github(cfg, 'GET', `/repos/${repo}/contents/${path}?ref=${branch}`);
+                    there = true;
+                }
+                catch (g) {
+                    if (!(g instanceof GitHubError) || g.status !== 404)
+                        throw g;
+                }
+                if (!there)
+                    throw e;
+                if (refuseExisting)
+                    throw new GitHubError(`${path} is already written`, 409, e.body);
+            }
+            return { url: attachmentUrl(repo, branch, path) };
+        },
+    };
+}
+/** For a filer who cannot push: the file goes to an attachment relay (any URL running `createAttachRelay`, with whatever
+ *  header proves who is asking), which checks the named issue carries this report, saves the file through its own
+ *  GitHub App, and answers the link. */
+export function relayHost({ url, headers = {}, fetch }) {
+    const f = fetch ?? globalThis.fetch;
+    if (!/^https?:\/\//.test(url))
+        throw new Error(`${JSON.stringify(url)} is not a relay URL`);
+    return {
+        async put(target, file) {
+            pathFor(target, file.name);
+            const res = await f(url, {
+                method: 'POST',
+                headers: { ...headers, 'content-type': 'application/json' },
+                body: JSON.stringify({ repo: target.repo, issue: target.issue, reportId: target.reportId, name: file.name, type: file.type, bytes: toBase64(file.bytes) }),
+            });
+            const text = await res.text();
+            let body = null;
+            try {
+                body = text ? JSON.parse(text) : null;
+            }
+            catch {
+                body = text;
+            }
+            if (!res.ok)
+                throw new GitHubError(`the attachment relay answered ${res.status}`, res.status, body);
+            if (typeof body?.url !== 'string' || !body.url.startsWith(`https://github.com/${target.repo}/`))
+                throw new Error('the attachment relay did not answer a github.com link in this repo');
+            return { url: body.url };
+        },
+    };
+}

package/dist/github/index.d.ts

@@ -0,0 +1,12 @@
+export { privacyCatch, redact, mayFileAsIs, normalize } from './privacy.ts';
+export type { Hit, HitKind, Person, CatchOptions } from './privacy.ts';
+export { composeIssue, whatGoes, destinationWords, pieces, BODY_LIMIT, filedByLine, endsWithFiledBy, FILED_BY } from './compose.ts';
+export type { Piece, Destination, Draft, ComposeOptions, ComposedIssue } from './compose.ts';
+export { fileIssue, updateIssue, addFollowUp, issueStates, issueStatus, fileSuggestion, attachPending, github, GitHubError } from './api.ts';
+export type { GitHubConfig, FilingConfig, IssueState, FileSuggestionInput, FiledSuggestion, Fetch } from './api.ts';
+export { branchHost, relayHost, toBase64, attachmentUrl, ATTACHMENTS_BRANCH, CONTENTS_API_BYTES } from './hosts.ts';
+export type { AttachmentHost, AttachmentTarget, AttachmentFile } from './hosts.ts';
+export { createSuggestionRelay, createAttachRelay, memoryUsage, RELAY_LIMITS, RELAY_VOICE_BYTES, FILING_LEASE_MS } from './relay.ts';
+export type { SuggestionRelayOptions, AttachRelayOptions, RelayLimits, RelayUsage, RelayIdentity, Reservation, FiledRecord, StagingAdapter } from './relay.ts';
+export { relayFiler, canFileDirectly, STAGE_OVER_BYTES } from './filer.ts';
+export type { RelayFiler, RelayFiling, RelayFile, RelayCapabilities } from './filer.ts';

package/dist/github/index.js

@@ -0,0 +1,9 @@
+// "@supersuit/suggest-a-change/github": a suggestion becomes one ordinary GitHub issue. Zero runtime dependencies,
+// web-standard fetch (injectable). Used straight from an app's server (createReportHandlers' `github` option) or by the
+// owner's Mac with `gh`'s token.
+export { privacyCatch, redact, mayFileAsIs, normalize } from './privacy.js';
+export { composeIssue, whatGoes, destinationWords, pieces, BODY_LIMIT, filedByLine, endsWithFiledBy, FILED_BY } from './compose.js';
+export { fileIssue, updateIssue, addFollowUp, issueStates, issueStatus, fileSuggestion, attachPending, github, GitHubError } from './api.js';
+export { branchHost, relayHost, toBase64, attachmentUrl, ATTACHMENTS_BRANCH, CONTENTS_API_BYTES } from './hosts.js';
+export { createSuggestionRelay, createAttachRelay, memoryUsage, RELAY_LIMITS, RELAY_VOICE_BYTES, FILING_LEASE_MS } from './relay.js';
+export { relayFiler, canFileDirectly, STAGE_OVER_BYTES } from './filer.js';

package/dist/github/privacy.d.ts

@@ -0,0 +1,34 @@
+export type HitKind = 'credential' | 'email' | 'phone' | 'person';
+export interface Hit {
+    kind: HitKind;
+    text: string;
+    field: string;
+}
+export interface Person {
+    name: string;
+    aliases?: string[];
+}
+export interface CatchOptions {
+    /** Third parties: anyone in the workspace's people records other than the sender and the owner. */
+    people?: Person[];
+    /** Secrets the app knows, such as the sender's own account key; one under 12 characters is a name, not a secret, and is not looked for. */
+    secrets?: string[];
+}
+/** What the catch reads: report fields, plus a `transcript` the Mac wrote. */
+export interface Readable {
+    words?: unknown;
+    transcript?: unknown;
+    followUps?: unknown;
+    [k: string]: unknown;
+}
+/** Text as it will read once rendered: compatibility forms folded (NFKC, so fullwidth letters are letters) and invisible
+ *  format characters removed (zero-width spaces and joiners, soft hyphens, direction marks), so a split token still matches. */
+export declare const normalize: (s: string) => string;
+export declare function privacyCatch(report: Readable, { people, secrets }?: CatchOptions): {
+    hits: Hit[];
+};
+/** A copy of the report with every hit replaced by `[removed]` in its own field, wherever it appears there. A field with a
+ *  hit comes back normalized (the form the catch read), so a hit split by an invisible character is removed too. */
+export declare function redact<T extends Readable>(report: T, hits: Hit[]): T;
+/** No credential among the hits: the owner may file it as it is. A credential only ever files without the flagged part. */
+export declare const mayFileAsIs: (hits: Hit[]) => boolean;

package/dist/github/privacy.js

@@ -0,0 +1,142 @@
+// THE PRIVACY CATCH (suggestions-as-github-issues design, section 5). Runs over everything a person SAID before any of it
+// becomes an issue: the words, the transcript and the follow-ups. Screenshots are not read for text in this version; the
+// sheet's list is what tells the sender they are going. A hit holds the report for the owner; a credential is never
+// filed as it is, whatever the tap (`mayFileAsIs`).
+const CREDENTIALS = [
+    /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{20,}/g,
+    /\bsk-ant-[A-Za-z0-9_-]{20,}/g,
+    /\bsk-(?!ant-)[A-Za-z0-9_-]{20,}/g,
+    /\bAKIA[0-9A-Z]{16}\b/g,
+    /\bAIza[0-9A-Za-z_-]{35}/g,
+    /\bxox[abposr]-[A-Za-z0-9-]{10,}/g,
+    /-----BEGIN [A-Z ]*PRIVATE KEY-----/g,
+];
+// A long random value after a name that says it is secret. The value alone is the hit, so "token=" survives redaction.
+const ASSIGNED = /\b(?:api[_-]?key|key|token|secret|password|passwd)\s*[=:]\s*["']?([A-Za-z0-9+/_=-]{20,})/gi;
+const EMAIL = /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g;
+const PHONES = [
+    /(?<![\w.])(?:\+?1[\s.-]?)?(?:\(\d{3}\)|\d{3})[\s.-]?\d{3}[\s.-]?\d{4}(?![\w.])/g,
+    /(?<![\w.])\+\d{8,15}(?![\w.])/g,
+];
+/** Shannon entropy in bits per character: random keys score high, "aaaa..." and ordinary words low. */
+function entropy(s) {
+    const n = new Map();
+    for (const ch of s)
+        n.set(ch, (n.get(ch) ?? 0) + 1);
+    let e = 0;
+    for (const c of n.values()) {
+        const p = c / s.length;
+        e -= p * Math.log2(p);
+    }
+    return e;
+}
+const escape = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+/** Text as it will read once rendered: compatibility forms folded (NFKC, so fullwidth letters are letters) and invisible
+ *  format characters removed (zero-width spaces and joiners, soft hyphens, direction marks), so a split token still matches. */
+export const normalize = (s) => s.normalize('NFKC').replace(/\p{Cf}/gu, '');
+/** EVERY string that reaches the issue, with the path it sits at: the words, the transcript, the follow-ups, where, every
+ *  diagnostic, the names given (filerName, appName), the contact's handle, and every part of the context (each item's
+ *  label, value and why, and the routes, taps and errors). Each is normalized before it is read. */
+function fields(r) {
+    const out = [];
+    const at = (path, v) => { if (typeof v === 'string' && v)
+        out.push([path, normalize(v)]); };
+    const obj = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : null);
+    at('words', r.words);
+    at('transcript', r.transcript);
+    if (Array.isArray(r.followUps))
+        r.followUps.forEach((f, i) => at(`followUps.${i}.words`, obj(f)?.words));
+    const where = obj(r.where);
+    at('where.screen', where?.screen);
+    at('where.route', where?.route);
+    for (const [k, v] of Object.entries(obj(r.diagnostics) ?? {}))
+        at(`diagnostics.${k}`, v);
+    at('filerName', r.filerName);
+    at('appName', r.appName);
+    at('who.contact.handle', obj(obj(r.who)?.contact)?.handle);
+    // The names of the files, which the issue shows as link text.
+    if (Array.isArray(r.files))
+        r.files.forEach((f, i) => at(`files.${i}.name`, typeof f === 'string' ? f : obj(f)?.name));
+    if (Array.isArray(r.files))
+        r.files.forEach((f, i) => at(`files.${i}.name`, typeof f === 'string' ? f : obj(f)?.name));
+    const ctx = obj(r.context);
+    if (ctx) {
+        for (const [list, keys] of [['items', ['label', 'value', 'why']], ['routes', ['route', 'at']], ['taps', ['label', 'at']], ['errors', ['message', 'frame', 'at']]]) {
+            const v = ctx[list];
+            if (Array.isArray(v))
+                v.forEach((x, i) => { for (const k of keys)
+                    at(`context.${list}.${i}.${k}`, obj(x)?.[k]); });
+        }
+    }
+    return out;
+}
+const digits = (s) => s.replace(/\D/g, '');
+export function privacyCatch(report, { people = [], secrets = [] } = {}) {
+    const hits = [];
+    const seen = new Set();
+    // The sender's own way to be reached is theirs to share: it is never a hit, while anyone else's still is. An email
+    // or phone inside the contact itself (its handle) is the sender's too; anywhere else it is a hit.
+    const own = report.who?.contact;
+    const ownEmail = typeof own?.email === 'string' ? normalize(own.email).toLowerCase() : null;
+    const ownPhone = typeof own?.phone === 'string' && digits(own.phone).length >= 7 ? digits(own.phone) : null;
+    const add = (kind, text, field) => {
+        if (kind === 'email' && ownEmail && text.toLowerCase() === ownEmail)
+            return;
+        if (kind === 'phone' && ownPhone && digits(text) === ownPhone)
+            return;
+        if ((kind === 'email' || kind === 'phone') && field === 'who.contact.handle')
+            return;
+        const k = `${field}\u0000${text}`;
+        if (seen.has(k))
+            return;
+        // A value already caught as a credential is not caught again as something smaller inside it.
+        if (hits.some((h) => h.field === field && h.kind === 'credential' && h.text.includes(text)))
+            return;
+        seen.add(k);
+        hits.push({ kind, text, field });
+    };
+    const keys = secrets.filter((k) => typeof k === 'string' && k.length >= 12).map(normalize);
+    const names = people.flatMap((p) => [p.name, ...(p.aliases ?? [])]).filter((n) => typeof n === 'string' && n.trim().split(/\s+/).length >= 2).map(normalize);
+    for (const [field, text] of fields(report)) {
+        for (const re of CREDENTIALS)
+            for (const m of text.matchAll(re))
+                add('credential', m[0], field);
+        for (const m of text.matchAll(ASSIGNED))
+            if (entropy(m[1]) >= 3)
+                add('credential', m[1], field);
+        for (const k of keys)
+            if (text.includes(k))
+                add('credential', k, field);
+        for (const m of text.matchAll(EMAIL))
+            add('email', m[0], field);
+        for (const re of PHONES)
+            for (const m of text.matchAll(re))
+                add('phone', m[0].trim(), field);
+        for (const n of names) {
+            const re = new RegExp(`(?<![\\p{L}\\p{N}])${escape(n.trim()).replace(/\s+/g, '\\s+')}(?![\\p{L}\\p{N}])`, 'giu');
+            for (const m of text.matchAll(re))
+                add('person', m[0], field);
+        }
+    }
+    return { hits };
+}
+/** A copy of the report with every hit replaced by `[removed]` in its own field, wherever it appears there. A field with a
+ *  hit comes back normalized (the form the catch read), so a hit split by an invisible character is removed too. */
+export function redact(report, hits) {
+    const out = JSON.parse(JSON.stringify(report));
+    for (const field of [...new Set(hits.map((h) => h.field))]) {
+        const path = field.split('.');
+        let at = out;
+        for (const p of path.slice(0, -1))
+            at = at && typeof at === 'object' ? at[p] : undefined;
+        const last = path[path.length - 1];
+        if (!at || typeof at !== 'object' || typeof at[last] !== 'string')
+            continue;
+        const mine = hits.filter((h) => h.field === field).map((h) => h.text).sort((a, b) => b.length - a.length);
+        at[last] = mine.reduce((t, h) => t.split(h).join('[removed]'), normalize(at[last]));
+    }
+    return out;
+}
+/** No credential among the hits: the owner may file it as it is. A credential only ever files without the flagged part. */
+export const mayFileAsIs = (hits) => !hits.some((h) => h.kind === 'credential');