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
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/13131-an-outsider-s-report-on-a-public-reposit → main 8 commits fork 3 threads · 3 unresolved
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) | ||
| 364 | 364 | - [](muse-test.md) |
| 365 | 365 | - [](offer.md) |
| 366 | 366 | - [](report-form.md) |
| 367 | - [](report-receipt.md) | |
| 367 | 368 | - [](tokens-harness.md) |
| 368 | 369 | |
| 369 | 370 | ### 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 | ||
| 22 | 22 | /** The form's refusal when one address files too fast. */ |
| 23 | 23 | export const reportTooFast = (seconds: number): string => |
| 24 | 24 | `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( | ||
| 350 | 350 | db: Database, |
| 351 | 351 | repoId: string, |
| 352 | 352 | reportId: string, |
| 353 | ): { state: ReportState; issue: number | null } | undefined { | |
| 353 | ): { state: ReportState; title: string; issue: number | null } | undefined { | |
| 354 | 354 | 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; | |
| 357 | 357 | return row ?? undefined; |
| 358 | 358 | } |
src/http/api/reports.ts +8 −11
| @@ -7,7 +7,6 @@ | ||
| 7 | 7 | */ |
| 8 | 8 | |
| 9 | 9 | import { REPORT_ALREADY_DECIDED } from "../../actions/origin_app_words.ts"; |
| 10 | import { REPORT_RECEIVED } from "../../actions/report_words.ts"; | |
| 11 | 10 | import { |
| 12 | 11 | acceptReport, |
| 13 | 12 | dismissReport, |
| @@ -21,7 +20,7 @@ import { keyedPage, keyedWindow, loadRepo, originAware, withLabels } from "../ap | ||
| 21 | 20 | import type { Handler } from "../context.ts"; |
| 22 | 21 | import { holds, weakEtag } from "../etag.ts"; |
| 23 | 22 | import { clientBucket } from "../peer.ts"; |
| 24 | import { proofOf } from "../report_filer.ts"; | |
| 23 | import { proofOf, receiptOf, receiptText, wantsText } from "../report_filer.ts"; | |
| 25 | 24 | import { |
| 26 | 25 | apiError, |
| 27 | 26 | body, |
| @@ -77,15 +76,13 @@ export function reportRoutes(router: Router<Handler>): void { | ||
| 77 | 76 | return tryAgain("queue_full", 429, "this repository has many reports waiting; try again later", REPORT_QUEUE_RETRY); |
| 78 | 77 | return apiError(refusal.error, 422, REPORT_HINT); |
| 79 | 78 | } |
| 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); | |
| 89 | 86 | }); |
| 90 | 87 | |
| 91 | 88 | // 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"; | ||
| 36 | 36 | import { greppable, searchKind } from "../core/search.ts"; |
| 37 | 37 | import { strangerCodeSearch } from "./strangers.ts"; |
| 38 | 38 | import { hintForCode, retryAfterOf } from "./respond.ts"; |
| 39 | import { proofOf } from "./report_filer.ts"; | |
| 39 | import { proofOf, receiptOf } from "./report_filer.ts"; | |
| 40 | 40 | import { fileReport } from "../actions/reports.ts"; |
| 41 | 41 | import { START_HINT, START_WORDS, startBuilding } from "../actions/start.ts"; |
| 42 | 42 | import { CONTRIBUTE_TOKEN_HINT, CONTRIBUTE_TOKEN_WORDS, mintContributeToken } from "../actions/contribute_token.ts"; |
| 43 | import { REPORT_RECEIVED } from "../actions/report_words.ts"; | |
| 44 | 43 | import { BODY_MAX, REQUEST_MAX, TITLE_MAX } from "../core/reports.ts"; |
| 45 | 44 | import { everydayOf } from "../core/everyday.ts"; |
| 46 | 45 | import { claimDone, completeWrite, dropWrite, recordWrite } from "../core/conversation_writes.ts"; |
| @@ -53,7 +52,10 @@ import { OFFER_TOOL, offerAnswer } from "./mcp/offer.ts"; | ||
| 53 | 52 | import { OFFER_REQUEST_MAX } from "../actions/offer.ts"; |
| 54 | 53 | |
| 55 | 54 | 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 | */ | |
| 57 | 59 | export function toolEntries(tools: readonly (typeof TOOLS)[number][]) { |
| 58 | 60 | return [ |
| 59 | 61 | ...tools.map((t) => ({ |
| @@ -340,10 +342,16 @@ export const START_TOOL = { | ||
| 340 | 342 | }, |
| 341 | 343 | } as const; |
| 342 | 344 | |
| 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 | */ | |
| 344 | 349 | type FreeHandler = (ctx: Ctx, id: unknown, args: Args) => unknown; |
| 345 | 350 | |
| 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 | */ | |
| 347 | 355 | export const TOKEN_FREE_HANDLERS: Readonly<Record<string, FreeHandler>> = { |
| 348 | 356 | report: reportAnswer, |
| 349 | 357 | start: startAnswer, |
| @@ -469,11 +477,7 @@ function reportAnswer(ctx: Ctx, id: unknown, args: Args): unknown { | ||
| 469 | 477 | ); |
| 470 | 478 | } |
| 471 | 479 | 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)), | |
| 477 | 481 | ); |
| 478 | 482 | } |
| 479 | 483 |
src/http/report_filer.ts +60
| @@ -7,6 +7,9 @@ | ||
| 7 | 7 | * elsewhere cannot file a report in a signed-in person's name. Anything else |
| 8 | 8 | * files anonymously, or as a claim. |
| 9 | 9 | */ |
| 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"; | |
| 10 | 13 | import type { User } from "../core/users.ts"; |
| 11 | 14 | import type { Ctx } from "./context.ts"; |
| 12 | 15 | |
| @@ -20,3 +23,60 @@ export function proofOf(ctx: Ctx): User | undefined { | ||
| 20 | 23 | : undefined; |
| 21 | 24 | return undefined; |
| 22 | 25 | } |
| 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; | |
| 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: | ||
| 37 | 37 | if (text.length > MAX_BODY) return NOTE_TOO_LONG; |
| 38 | 38 | return (async () => { |
| 39 | 39 | 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"); | |
| 41 | 41 | else ctx.toast(NOT_SENT_WORDS, "danger"); |
| 42 | 42 | })(); |
| 43 | 43 | }, |
src/web/pages/reports.ts +13 −6
| @@ -190,12 +190,19 @@ function reportBody(ctx: Ctx, repo: Repo): Response { | ||
| 190 | 190 | })} |
| 191 | 191 | <section class="settings-block"> |
| 192 | 192 | <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> | |
| 199 | 206 | </section>`, |
| 200 | 207 | }); |
| 201 | 208 | } |
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 <b>link</b>"); | |
| 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", () => { | ||
| 92 | 92 | if (text.includes(REPORT_RECEIVED)) typed.push(entry); |
| 93 | 93 | } |
| 94 | 94 | 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) { | |
| 96 | 101 | const text = await readFile(join(root, door), "utf8"); |
| 97 | expect(text).toContain('from "../actions/report_words.ts"'); | |
| 102 | expect(text).toContain(`from "${path}"`); | |
| 98 | 103 | } |
| 99 | 104 | }); |
| 100 | 105 | }); |
new above
offline
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.