Public: anyone can read this; the crew can change it.

An outsider's report on a public repository returns a receipt they can read back #13206

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

scout/forge:scout/13131-an-outsider-s-report-on-a-public-reposit → main 8 commits fork 3 threads · 3 unresolved

  • Merged. scout/13131-an-outsider-s-report-on-a-public-reposit was merged into main as 01851f7.

Review

Sign in to review this change.
11 files changed +221 −33
docs/features/README.md +1
@@ -364,6 +364,7 @@ Read with the guide page [Agents: MCP, git, or the terminal](../guide-agents.md)
364364 - [The Muse test: how an outsider reports a problem](muse-test.md)
365365 - [Offering a patch with no account](offer.md)
366366 - [The report form for outsiders](report-form.md)
367 - [The receipt an outsider is handed for a report](report-receipt.md)
367368 - [Which harness holds a token](tokens-harness.md)
368369
369370 ### Backups and moving
docs/features/report-receipt.md added +23
@@ -0,0 +1,23 @@
1 # A report's receipt
2
3 An outsider files a report on a public repository without an account and is handed a receipt they can read back.
4 A report is not an issue until a person accepts it, so the receipt says so rather than guessing a number.
5
6 Fields (same from every door): `id`, `state` (`pending`), `filedBy`, `issue` (`null` — "none yet"), `url`, `message`,
7 `next`. The `url` is built on the forge's configured public URL (never a Host header the client wrote) and shows,
8 signed out, the report's title and whether a person has read it and which issue it became; the issue number
9 appears there once the report is accepted.
10
11 - **JSON:** `POST /api/v1/repos/:owner/:name/reports` answers 202 with the receipt.
12 - **Plain text:** the same request with `Accept: text/plain` answers `report:`, `issue: none yet`, `url:`, `state:`
13 lines, then the message and the next step.
14 - **MCP:** the `report` tool returns the receipt as its JSON text.
15 - **Web:** after the form, `/:owner/:name/report?sent=<id>` shows Title and State rows.
16
17 The terminal (both doors): signed-in people have no outsider receipt; the repository palette's "Report a problem"
18 opens an issue at once, and its toast now reads back the issue's number and path (`Issue #7 opened: /owner/name/issues/7`).
19
20 Try it: `curl -s -XPOST -H 'content-type: application/json' -d '{"title":"x"}' $FORGE_URL/api/v1/repos/alice/game/reports`,
21 then open the `url` it returns.
22
23 Pinned by `test/report-receipt.test.ts` and `test/report-words.test.ts`.
src/actions/report_words.ts +4
@@ -22,3 +22,7 @@ export const REPORT_WHERE_REPLY = "Sending gives you a link that shows whether a
2222 /** The form's refusal when one address files too fast. */
2323 export const reportTooFast = (seconds: number): string =>
2424 `Too many reports from here just now. Try again in ${seconds} seconds.`;
25
26 /** What happens next, in one sentence, for the receipt a filed report returns. */
27 export const REPORT_NEXT_STEP =
28 "A person who maintains this repository will read it; open the url to see whether they have and which issue it became.";
src/core/reports.ts +3 −3
@@ -350,9 +350,9 @@ export function reportStanding(
350350 db: Database,
351351 repoId: string,
352352 reportId: string,
353 ): { state: ReportState; issue: number | null } | undefined {
353 ): { state: ReportState; title: string; issue: number | null } | undefined {
354354 const row = db
355 .query("SELECT state, issue_number AS issue FROM report WHERE repo_id = ?1 AND id = ?2")
356 .get(repoId, reportId) as { state: ReportState; issue: number | null } | null;
355 .query("SELECT state, title, issue_number AS issue FROM report WHERE repo_id = ?1 AND id = ?2")
356 .get(repoId, reportId) as { state: ReportState; title: string; issue: number | null } | null;
357357 return row ?? undefined;
358358 }
src/http/api/reports.ts +8 −11
@@ -7,7 +7,6 @@
77 */
88
99 import { REPORT_ALREADY_DECIDED } from "../../actions/origin_app_words.ts";
10 import { REPORT_RECEIVED } from "../../actions/report_words.ts";
1110 import {
1211 acceptReport,
1312 dismissReport,
@@ -21,7 +20,7 @@ import { keyedPage, keyedWindow, loadRepo, originAware, withLabels } from "../ap
2120 import type { Handler } from "../context.ts";
2221 import { holds, weakEtag } from "../etag.ts";
2322 import { clientBucket } from "../peer.ts";
24 import { proofOf } from "../report_filer.ts";
23 import { proofOf, receiptOf, receiptText, wantsText } from "../report_filer.ts";
2524 import {
2625 apiError,
2726 body,
@@ -77,15 +76,13 @@ export function reportRoutes(router: Router<Handler>): void {
7776 return tryAgain("queue_full", 429, "this repository has many reports waiting; try again later", REPORT_QUEUE_RETRY);
7877 return apiError(refusal.error, 422, REPORT_HINT);
7978 }
80 return json(
81 {
82 id: filed.value.id,
83 state: filed.value.state,
84 filedBy: filed.value.filedBy,
85 message: REPORT_RECEIVED,
86 },
87 202,
88 );
79 const receipt = receiptOf(ctx, repo, filed.value);
80 if (wantsText(ctx))
81 return new Response(receiptText(receipt), {
82 status: 202,
83 headers: { "content-type": "text/plain; charset=utf-8" },
84 });
85 return json(receipt, 202);
8986 });
9087
9188 // Reading the words is a writer's act, so a read-only token — the one an
src/http/mcp.ts +14 −10
@@ -36,11 +36,10 @@ import { exploreRun, searchRun } from "./mcp/reads.ts";
3636 import { greppable, searchKind } from "../core/search.ts";
3737 import { strangerCodeSearch } from "./strangers.ts";
3838 import { hintForCode, retryAfterOf } from "./respond.ts";
39 import { proofOf } from "./report_filer.ts";
39 import { proofOf, receiptOf } from "./report_filer.ts";
4040 import { fileReport } from "../actions/reports.ts";
4141 import { START_HINT, START_WORDS, startBuilding } from "../actions/start.ts";
4242 import { CONTRIBUTE_TOKEN_HINT, CONTRIBUTE_TOKEN_WORDS, mintContributeToken } from "../actions/contribute_token.ts";
43 import { REPORT_RECEIVED } from "../actions/report_words.ts";
4443 import { BODY_MAX, REQUEST_MAX, TITLE_MAX } from "../core/reports.ts";
4544 import { everydayOf } from "../core/everyday.ts";
4645 import { claimDone, completeWrite, dropWrite, recordWrite } from "../core/conversation_writes.ts";
@@ -53,7 +52,10 @@ import { OFFER_TOOL, offerAnswer } from "./mcp/offer.ts";
5352 import { OFFER_REQUEST_MAX } from "../actions/offer.ts";
5453
5554 const PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"] as const;
56 /** The tools/list entries for these tools, then `report`: what is served, and what docs/MCP.md measures. */
55 /**
56 * The tools/list entries for these tools, then `report`: what is served, and what docs/MCP.md
57 * measures.
58 */
5759 export function toolEntries(tools: readonly (typeof TOOLS)[number][]) {
5860 return [
5961 ...tools.map((t) => ({
@@ -340,10 +342,16 @@ export const START_TOOL = {
340342 },
341343 } as const;
342344
343 /** What a token-free tool does with its call: the JSON-RPC answer. One entry per name in TOKEN_FREE_TOOLS. */
345 /**
346 * What a token-free tool does with its call: the JSON-RPC answer. One entry per name in
347 * TOKEN_FREE_TOOLS.
348 */
344349 type FreeHandler = (ctx: Ctx, id: unknown, args: Args) => unknown;
345350
346 /** The gate picks its handler here, so a name listed in TOKEN_FREE_TOOLS without one is caught by a test. */
351 /**
352 * The gate picks its handler here, so a name listed in TOKEN_FREE_TOOLS without one is caught by a
353 * test.
354 */
347355 export const TOKEN_FREE_HANDLERS: Readonly<Record<string, FreeHandler>> = {
348356 report: reportAnswer,
349357 start: startAnswer,
@@ -469,11 +477,7 @@ function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown {
469477 );
470478 }
471479 return text(
472 JSON.stringify({
473 id: filed.value.id,
474 state: filed.value.state,
475 message: REPORT_RECEIVED,
476 }),
480 JSON.stringify(receiptOf(ctx, repo, filed.value)),
477481 );
478482 }
479483
src/http/report_filer.ts +60
@@ -7,6 +7,9 @@
77 * elsewhere cannot file a report in a signed-in person's name. Anything else
88 * files anonymously, or as a claim.
99 */
10 import { REPORT_NEXT_STEP, REPORT_RECEIVED } from "../actions/report_words.ts";
11 import type { Report } from "../core/reports.ts";
12 import type { Repo } from "../core/repos.ts";
1013 import type { User } from "../core/users.ts";
1114 import type { Ctx } from "./context.ts";
1215
@@ -20,3 +23,60 @@ export function proofOf(ctx: Ctx): User | undefined {
2023 : undefined;
2124 return undefined;
2225 }
26
27 /**
28 * What a filer is handed back (#13131): where the report landed and what
29 * happens next. A report is not an issue until a person accepts it, so
30 * `issue` is null now (never a guess) and the `url` — readable signed out on
31 * a public repository — shows the number once there is one. Never the filer's words.
32 */
33 export interface Receipt {
34 readonly id: string;
35 readonly state: Report["state"];
36 readonly filedBy: Report["filedBy"];
37 readonly issue: number | null;
38 readonly url: string;
39 readonly message: string;
40 readonly next: string;
41 }
42
43 /**
44 * The origin a link is built on: the forge's configured URL when it has one,
45 * so a Host header the client wrote cannot poison a receipt's link; the
46 * request's own origin only on an unconfigured (local) forge.
47 */
48 export function publicOrigin(ctx: { app: { config: { url?: string | undefined } }; url: URL }): string {
49 const configured = ctx.app.config.url;
outdated

issue is hard-coded null, so the receipt never carries an issue number as box 1 asks. Either state in the issue that the number arrives on the url page, or return it when the report is already accepted.

50 return configured !== undefined ? new URL(configured).origin : ctx.url.origin;
outdated

ctx.url.origin: make sure this is the forge's configured public origin and not derived from the Host header the client wrote; otherwise the receipt link can be poisoned.

51 }
52
53 export function receiptOf(ctx: Ctx, repo: Repo, report: Report): Receipt {
54 return {
55 id: report.id,
56 state: report.state,
57 filedBy: report.filedBy,
58 issue: null,
59 url: `${publicOrigin(ctx)}/${encodeURIComponent(repo.ownerName)}/${encodeURIComponent(repo.name)}/report?sent=${report.id}`,
60 message: REPORT_RECEIVED,
61 next: REPORT_NEXT_STEP,
62 };
63 }
64
65 /** The receipt as plain text, for a client that asks for `text/plain`. */
66 export function receiptText(r: Receipt): string {
67 return [
68 `report: ${r.id}`,
69 `issue: ${r.issue === null ? "none yet" : `#${r.issue}`}`,
70 `url: ${r.url}`,
71 `state: ${r.state}`,
72 r.message,
73 r.next,
74 "",
75 ].join("\n");
76 }
77
78 /** Whether the caller prefers plain text to JSON. */
79 export const wantsText = (ctx: Ctx): boolean => {
80 const accept = ctx.request.headers.get("accept") ?? "";
81 return /text\/plain/i.test(accept) && !/application\/json/i.test(accept);
82 };
src/tui/screens/report.ts +1 −1
@@ -37,7 +37,7 @@ export function reportCommands(f: Session, ctx: Ctx, parent: () => Screen, repo:
3737 if (text.length > MAX_BODY) return NOTE_TOO_LONG;
3838 return (async () => {
3939 const opened = await openIssueThrough(f.app, f.user, repo, { title: reportTitle(text), body: text });
40 if (opened.ok) ctx.toast(`Issue #${opened.value.number} opened.`, "success");
40 if (opened.ok) ctx.toast(`Issue #${opened.value.number} opened: /${name}/issues/${opened.value.number}`, "success");
4141 else ctx.toast(NOT_SENT_WORDS, "danger");
4242 })();
4343 },
src/web/pages/reports.ts +13 −6
@@ -190,12 +190,19 @@ function reportBody(ctx: Ctx, repo: Repo): Response {
190190 })}
191191 <section class="settings-block">
192192 <h1>Report sent</h1>
193 ${standing?.state === "accepted" && standing.issue !== null
194 ? html`<p>A person read it and opened
195 <a href="${base}/issues/${standing.issue}">an issue</a> from it.</p>`
196 : standing?.state === "dismissed"
197 ? html`<p>A person read it and closed it without an issue.</p>`
198 : html`<p>Not read yet. Keep this link and look again.</p>`}
193 <dl class="status-rows">
outdated

Principle 1/7: the page now says 'Report sent' and then repeats the filer's title as a free-standing mono paragraph. Use a dl row (Title) with the state, rather than a bare paragraph. Also no terminal counterpart and no docs/features how-to for this surface.

194 ${standing?.title !== undefined
195 ? html`<div class="status-row"><dt>Title</dt><dd id="report-title">${standing.title}</dd></div>`
196 : ""}
197 <div class="status-row"><dt>State</dt><dd>${
198 standing?.state === "accepted" && standing.issue !== null
199 ? html`A person read it and opened
200 <a href="${base}/issues/${standing.issue}">an issue</a> from it.`
201 : standing?.state === "dismissed"
202 ? "A person read it and closed it without an issue."
203 : "Not read yet. Keep this link and look again."
204 }</dd></div>
205 </dl>
199206 </section>`,
200207 });
201208 }
test/report-receipt.test.ts added +87
@@ -0,0 +1,87 @@
1 /** The receipt a filer reads back (#13131): where it landed, what happens next. */
2 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createRepo } from "../src/actions/repos.ts";
7 import { REPORT_NEXT_STEP } from "../src/actions/report_words.ts";
8 import { createApp, type App } from "../src/app.ts";
9 import { createUser } from "../src/core/users.ts";
10 import { serve, type Servers } from "../src/http/server.ts";
11
12 describe("a report's receipt", () => {
13 let dataDir: string;
14 let app: App;
15 let servers: Servers;
16 let base: string;
17 let n = 0;
18 const from = () => ({ "x-forwarded-for": `203.0.113.${++n}` });
19 const file = (repo: string, body: unknown, headers: Record<string, string> = {}) =>
20 fetch(`${base}/api/v1/repos/alice/${repo}/reports`, {
21 method: "POST",
22 headers: { "content-type": "application/json", ...from(), ...headers },
23 body: JSON.stringify(body),
24 });
25
26 beforeAll(async () => {
27 dataDir = await mkdtemp(join(tmpdir(), "forge-receipt-"));
28 app = createApp({ dataDir, port: 0 });
29 servers = await serve(app);
30 base = servers.url;
31 const a = await createUser(app.db, { origin: "seed", trusted: true, username: "alice",
32 email: "[email protected]", password: "a-good-passphrase", adminIfFirst: true });
33 if (!a.ok) throw new Error(a.error);
34 for (const [name, visibility] of [["open", "public"], ["shut", "private"]] as const) {
35 const r = await createRepo(app, a.value, { name, visibility });
36 if (!r.ok) throw new Error(String(r.error));
37 }
38 });
39 afterAll(async () => {
40 await servers.stop();
41 await rm(dataDir, { recursive: true, force: true });
42 });
43
44 test("JSON carries the id, issue (none yet), url and one sentence of next", async () => {
45 const res = await file("open", { title: "Broken <b>link</b>" });
46 expect(res.status).toBe(202);
47 const r = (await res.json()) as { issue: number | null; next: string; url: string; id: string };
48 expect(r.issue).toBeNull();
49 expect(r.next).toBe(REPORT_NEXT_STEP);
50 expect(r.url).toBe(`${base}/alice/open/report?sent=${r.id}`);
51 });
52
53 test("plain text carries the same, and never the filer's words", async () => {
54 const res = await file("open", { title: "secret-title", body: "secret-body" }, { accept: "text/plain" });
55 expect(res.status).toBe(202);
56 expect(res.headers.get("content-type")).toContain("text/plain");
57 const t = await res.text();
58 expect(t).toContain("issue: none yet");
59 expect(t).toMatch(/url: \S+\/alice\/open\/report\?sent=\w+/);
60 expect(t).toContain(REPORT_NEXT_STEP);
61 expect(t).not.toContain("secret-");
62 });
63
64 test("the url, signed out, shows the report escaped; a private repository is 404", async () => {
65 const r = (await (await file("open", { title: "Broken <b>link</b>" })).json()) as { url: string; id: string };
66 const page = await (await fetch(r.url)).text();
67 expect(page).toContain("Broken &lt;b&gt;link&lt;/b&gt;");
68 expect(page).not.toContain("<b>link</b>");
69 expect(page).toContain("Not read yet");
70 const closed = await fetch(`${base}/alice/shut/report?sent=${r.id}`);
71 expect(closed.status).toBe(404);
72 expect((await file("shut", { title: "x" })).status).toBe(404);
73 });
74 });
75
76 import { publicOrigin } from "../src/http/report_filer.ts";
77
78 describe("the receipt's link origin", () => {
79 const ctxOf = (configured: string | undefined, host: string) =>
80 ({ app: { config: { url: configured } }, url: new URL(`http://${host}/x`) });
81 test("is the configured public origin, not the Host the client wrote", () => {
82 expect(publicOrigin(ctxOf("https://forge.example/", "evil.test"))).toBe("https://forge.example");
83 });
84 test("falls back to the request's origin on an unconfigured forge", () => {
85 expect(publicOrigin(ctxOf(undefined, "localhost:3000"))).toBe("http://localhost:3000");
86 });
87 });
test/report-words.test.ts +7 −2
@@ -92,9 +92,14 @@ describe("the words a report reads back", () => {
9292 if (text.includes(REPORT_RECEIVED)) typed.push(entry);
9393 }
9494 expect(typed).toEqual([join("actions", "report_words.ts")]);
95 for (const door of ["http/api.ts", "http/mcp.ts"]) {
95 const filer = await readFile(join(root, "http/report_filer.ts"), "utf8");
96 expect(filer).toContain('from "../actions/report_words.ts"');
97 for (const [door, path] of [
98 ["http/api/reports.ts", "../report_filer.ts"],
99 ["http/mcp.ts", "./report_filer.ts"],
100 ] as const) {
96101 const text = await readFile(join(root, door), "utf8");
97 expect(text).toContain('from "../actions/report_words.ts"');
102 expect(text).toContain(`from "${path}"`);
98103 }
99104 });
100105 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs