Public: anyone can read this; the crew can change it.
The client list downloads as a CSV: who was sent a forge, when, and what happened #14742
Check · Review · Land · Live done — Landed and live in production.
scout/forge:scout/14461-the-client-list-downloads-as-a-csv-who-w → main 7 commits fork 2 threads · 2 unresolved
8 files
changed +160
−4
docs/features/clients-csv.md added +12
| @@ -0,0 +1,12 @@ | ||
| 1 | --- | |
| 2 | topic: Hosting forges for others, and getting paid | |
| 3 | row: The client list downloads as a CSV | |
| 4 | --- | |
| 5 | # The client list downloads as a CSV (#14461) | |
| 6 | ||
| 7 | `/forges/export.csv`, linked as *Download as CSV* at the foot of *Forges you sent*, serves every forge you sent as `text/csv` with the header `client, forge, sent at, state, last seen` (`clientsCsv`, `src/spawn/clients_csv.ts`). The client is who it was sent for, else who claimed it; state is the page's own wording. | |
| 8 | ||
| 9 | - **Safe in a spreadsheet.** Written by the wallet's writer (`src/text/csv_write.ts`): a text cell starting `=`, `+`, `-`, `@`, tab or CR gets a leading `'`, and quotes are doubled. | |
| 10 | - **Who.** Admins only, as the page is; anyone else gets the answer a missing page gets. | |
| 11 | - **Not filtered.** It is the whole list, not the current search or state. In the terminal, `c` on the forges screen (admin) writes the same file to `exports/forges-sent.csv` under the app data directory and toasts the path. | |
| 12 | - **Tests.** `bun test test/clients-csv.test.ts`. |
src/http/marks/forges.json +1
| @@ -4,6 +4,7 @@ | ||
| 4 | 4 | "routes": { |
| 5 | 5 | "/forges": "admin", |
| 6 | 6 | "/forges/refused": "admin", |
| 7 | "/forges/export.csv": "open", | |
| 7 | 8 | "/forges/name/:name": "open", |
| 8 | 9 | "/forges/:name/bill": "open", |
| 9 | 10 | "/forges/:name/claim-link": "open", |
src/http/server.ts +2 −1
| @@ -331,7 +331,7 @@ import { claimFragmentPage, claimOptions, claimRenew, claimSubmit, welcomePage, | ||
| 331 | 331 | import { firstAdminOptions, firstAdminPage, firstAdminSubmit } from "../web/pages/first-admin.ts"; |
| 332 | 332 | import { familyPage } from "../web/pages/family.ts"; |
| 333 | 333 | import { forgeLinkForm, forgeLinkRevoke, forgeLinkSubmit, forgeLinkUndo, forgeArchiveConfirm, forgeArchiveSubmit, forgeRestoreSubmit, forgeRemoveConfirm, forgeRemoveSubmit, forgeStopSubmit, |
| 334 | forgeOwnCodeSubmit, forgeSizeSubmit, forgeSandboxSubmit, forgesPage } from "../web/pages/forges.ts"; | |
| 334 | forgeOwnCodeSubmit, forgeSizeSubmit, forgeSandboxSubmit, forgesPage, forgesCsv } from "../web/pages/forges.ts"; | |
| 335 | 335 | import { billDownload } from "./api/forge_bill.ts"; |
| 336 | 336 | import { forgeRecoveryForm, forgeRecoverySubmit } from "../web/pages/forges.ts"; |
| 337 | 337 | import { forgesRefusedPage } from "../web/pages/forges-refused.ts"; |
| @@ -977,6 +977,7 @@ export function buildRouter(): Router<Handler> { | ||
| 977 | 977 | router.add("POST", "/first-admin/options", firstAdminOptions); |
| 978 | 978 | // "+ New forge": the spawn door as a page, any signed-in person (spawn/door.ts). |
| 979 | 979 | router.add("GET", "/forges", forgesPage); |
| 980 | router.add("GET", "/forges/export.csv", forgesCsv); | |
| 980 | 981 | router.add("GET", "/forges/refused", forgesRefusedPage); |
| 981 | 982 | router.add("GET", "/forges/archive", forgeArchiveConfirm); |
| 982 | 983 | router.add("POST", "/forges/archive", forgeArchiveSubmit); |
src/spawn/clients_csv.ts added +27
| @@ -0,0 +1,27 @@ | ||
| 1 | /** | |
| 2 | * The client list as one CSV (#14461): who was sent a forge, when, and what happened. The same | |
| 3 | * rows the page shows, written by the one formula-safe writer (`text/csv_write.ts`), so a person's | |
| 4 | * name starting `=` is neutralised exactly as in the wallet's CSV. | |
| 5 | */ | |
| 6 | import { mkdirSync, writeFileSync } from "node:fs"; | |
| 7 | import { join } from "node:path"; | |
| 8 | import { toCsv } from "../text/csv_write.ts"; | |
| 9 | import { CLAIM_WORDS, claimState, type ClientRow } from "./clients.ts"; | |
| 10 | ||
| 11 | export const CLIENTS_CSV_HEADER = ["client", "forge", "sent at", "state", "last seen"] as const; | |
| 12 | ||
| 13 | /** The client is who it was sent for, else whoever claimed it; empty when neither is known. */ | |
| 14 | export const clientsCsv = (rows: readonly ClientRow[]): string => | |
| 15 | toCsv( | |
| 16 | CLIENTS_CSV_HEADER, | |
| 17 | rows.map((r) => [r.for ?? r.claimedBy ?? "", r.name, r.sentAt ?? "", CLAIM_WORDS[claimState(r)], r.lastActivityAt ?? ""]), | |
| 18 | ); | |
| 19 | ||
| 20 | /** The terminal's door: the same CSV written under the app's data directory; returns the path. */ | |
| 21 | export function writeClientsCsv(dataDir: string, rows: readonly ClientRow[]): string { | |
| 22 | const dir = join(dataDir, "exports"); | |
| 23 | mkdirSync(dir, { recursive: true }); | |
| 24 | const file = join(dir, "forges-sent.csv"); | |
| 25 | writeFileSync(file, clientsCsv(rows)); | |
| 26 | return file; | |
| 27 | } |
src/tui/screens/forges.ts +4 −1
| @@ -17,6 +17,7 @@ import { parseClientQuery, searchClients } from "../../spawn/client_search.ts"; | ||
| 17 | 17 | import { CLIENT_STATE_EMPTY, CLIENT_STATE_WORDS, narrowByState, nextClientState, type ClientState } from "../../spawn/client_state.ts"; |
| 18 | 18 | import { diskWords } from "../../spawn/disk_mount.ts"; |
| 19 | 19 | import { archiveForge, archivedForges, destinationWords, restoreForge } from "../../spawn/archive.ts"; |
| 20 | import { writeClientsCsv } from "../../spawn/clients_csv.ts"; | |
| 20 | 21 | import { claimedWords, keepWords } from "../../spawn/keep_words.ts"; |
| 21 | 22 | import { changeLink, ownCode, removeForge, resizeForge, stopForge } from "../../spawn/manage.ts"; |
| 22 | 23 | import { moveToCell } from "../../spawn/move_cell.ts"; |
| @@ -230,7 +231,7 @@ export function forgesScreen(ctx: Ctx, rows: readonly ClientRow[], session?: Ses | ||
| 230 | 231 | }; |
| 231 | 232 | const screen: Screen = { |
| 232 | 233 | title: "Forges you sent", |
| 233 | keys: [binding(["s"], "stop"), binding(["a"], "archive"), binding(["r"], "restore"), binding(["x"], "remove"), binding(["n"], "new link"), binding(["l"], "end a link"), binding(["u"], "undo an ended link"), binding(["o"], "own code or this forge's"), binding(["m"], "move"), binding(["w"], "raise to xlarge"), binding(["f"], "state"), binding(["/"], "search"), binding(["esc"], "close")], | |
| 234 | keys: [binding(["s"], "stop"), binding(["a"], "archive"), binding(["r"], "restore"), binding(["x"], "remove"), binding(["n"], "new link"), binding(["l"], "end a link"), binding(["u"], "undo an ended link"), binding(["o"], "own code or this forge's"), binding(["m"], "move"), binding(["w"], "raise to xlarge"), binding(["f"], "state"), binding(["/"], "search"), binding(["c"], "csv"), binding(["esc"], "close")], | |
| 234 | 235 | render(area, s) { |
| 235 | 236 | const c = ctx.theme.c; |
| 236 | 237 | const w = Math.min(100, Math.max(30, area.w - 6)); |
| @@ -261,6 +262,8 @@ export function forgesScreen(ctx: Ctx, rows: readonly ClientRow[], session?: Ses | ||
| 261 | 262 | ); |
| 262 | 263 | else if (e.key === "s" && session !== undefined) |
| 263 | 264 | choose("Stop which forge?", (name) => void stopForge(session.app, name).then((done) => ctx.toast(done.says, done.ok ? "success" : "danger"))); |
| 265 | else if (e.key === "c" && session !== undefined && session.user?.isAdmin === true) | |
| 266 | ctx.toast(`Wrote ${String(rows.length)} forges to ${writeClientsCsv(session.app.config.dataDir, rows)}`, "success"); | |
| 264 | 267 | else if (e.key === "n") newLink(); |
| 265 | 268 | else if (e.key === "l") changeOne("revoke"); |
| 266 | 269 | else if (e.key === "u") changeOne("undo"); |
src/web/pages/forges.ts +17 −1
| @@ -28,6 +28,7 @@ import { readOwnCode } from "../../spawn/own_code.ts"; | ||
| 28 | 28 | import { moveToCell } from "../../spawn/move_cell.ts"; |
| 29 | 29 | import { sealedAt } from "../../spawn/sealed.ts"; |
| 30 | 30 | import { countRefusals, mayReadRefusals } from "../../core/first_ask_refusals.ts"; |
| 31 | import { clientsCsv } from "../../spawn/clients_csv.ts"; | |
| 31 | 32 | import { claimLinkBody } from "./new-forge.ts"; |
| 32 | 33 | import { whenWords } from "./claim.ts"; |
| 33 | 34 | import { appLinkSummary, appLinkWords } from "../../spawn/app_links.ts"; |
| @@ -236,6 +237,21 @@ function refusedLink(ctx: Ctx): Html | null { | ||
| 236 | 237 | return n === 0 ? null : html` <a href="/forges/refused">Refused first asks (${n})</a>`; |
| 237 | 238 | } |
| 238 | 239 | |
| 240 | // GET /forges/export.csv — the client list as a download, behind the page's own gate (a missing | |
| 241 | // page to anyone else). | |
| 242 | export async function forgesCsv(ctx: Ctx): Promise<Response> { | |
| 243 | if (!ctx.auth.user?.isAdmin) return notFoundPage(ctx); | |
Box 2: the route is marked admin in marks/forges.json, so non-admins are refused (403) before this handler runs and never get the missing-page answer this line intends. Make both paths give the same 404 and assert it in the test. |
||
| 244 | const rows = sortForges(await servedRows(ctx.app), "attention"); | |
| 245 | return new Response(clientsCsv(rows), { | |
| 246 | headers: { | |
| 247 | "content-type": "text/csv; charset=utf-8", | |
| 248 | "content-disposition": 'attachment; filename="forges-sent.csv"', | |
| 249 | "x-content-type-options": "nosniff", | |
| 250 | "cache-control": "private, no-store", | |
| 251 | }, | |
| 252 | }); | |
| 253 | } | |
| 254 | ||
| 239 | 255 | // GET /forges — an admin's only. |
| 240 | 256 | export async function forgesPage(ctx: Ctx): Promise<Response> { |
| 241 | 257 | const user = ctx.auth.user; |
| @@ -310,7 +326,7 @@ export async function forgesPage(ctx: Ctx): Promise<Response> { | ||
| 310 | 326 | ${sealedLine(ctx)} |
| 311 | 327 | ${archivedSection(ctx, archived)} |
| 312 | 328 | ${await ownCodeSection(ctx)} |
| 313 | <p class="mt"><a href="/fleet/graph">Fleet graph</a> <a href="${REACH_SETTINGS}">What hosted forges may reach</a>${refusedLink(ctx)}</p> | |
| 329 | <p class="mt"><a href="/fleet/graph">Fleet graph</a>${everyone.length === 0 ? null : html` <a href="/forges/export.csv" download>Download as CSV</a>`} <a href="${REACH_SETTINGS}">What hosted forges may reach</a>${refusedLink(ctx)}</p> | |
| 314 | 330 | </div>`, |
| 315 | 331 | }); |
| 316 | 332 | notePhase(ctx.request, "render", performance.now() - rendering); |
test/clients-csv.test.ts added +96
| @@ -0,0 +1,96 @@ | ||
| 1 | /** The client list downloads as a CSV (#14461). */ | |
| 2 | ||
| 3 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; | |
| 4 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 5 | import { tmpdir } from "node:os"; | |
| 6 | import { join } from "node:path"; | |
| 7 | import { createApp, type App } from "../src/app.ts"; | |
| 8 | import { createToken } from "../src/core/tokens.ts"; | |
| 9 | import { createUser } from "../src/core/users.ts"; | |
| 10 | import { serve, type Servers } from "../src/http/server.ts"; | |
| 11 | import type { ClientRow } from "../src/spawn/clients.ts"; | |
| 12 | import { readFileSync } from "node:fs"; | |
| 13 | import { CLIENTS_CSV_HEADER, clientsCsv, writeClientsCsv } from "../src/spawn/clients_csv.ts"; | |
| 14 | import { quietLogs } from "./helpers/globals.ts"; | |
| 15 | ||
| 16 | quietLogs(); | |
| 17 | ||
| 18 | const row = (over: Record<string, unknown>) => | |
| 19 | ({ name: "n", for: null, claimedBy: null, sentAt: null, lastActivityAt: null, made: true, claimed: false, apps: [], ...over }) as unknown as ClientRow; | |
| 20 | ||
| 21 | describe("clientsCsv", () => { | |
| 22 | test("header row, then one row per forge", () => { | |
| 23 | const out = clientsCsv([row({ name: "maria", for: "Maria", sentAt: "2026-01-02T03:04:05Z", lastActivityAt: "2026-02-01T00:00:00Z", claimed: true })]); | |
| 24 | expect(out.split("\r\n")[0]).toBe(CLIENTS_CSV_HEADER.join(",")); | |
| 25 | expect(CLIENTS_CSV_HEADER).toEqual(["client", "forge", "sent at", "state", "last seen"]); | |
| 26 | expect(out.split("\r\n")[1]).toBe("Maria,maria,2026-01-02T03:04:05Z,Claimed,2026-02-01T00:00:00Z"); | |
| 27 | }); | |
| 28 | test("an injecting cell is prefixed and quotes are doubled", () => { | |
| 29 | const out = clientsCsv([row({ for: '=HYPERLINK("http://x")' }), row({ for: "+1", name: "@a" }), row({ for: "-2" })]); | |
| 30 | expect(out).toContain(`"'=HYPERLINK(""http://x"")"`); | |
| 31 | expect(out).toContain("'+1,'@a,"); | |
| 32 | expect(out).toContain("'-2,"); | |
| 33 | }); | |
| 34 | }); | |
| 35 | ||
| 36 | test("the terminal door writes the file under the data directory", async () => { | |
| 37 | const d = await mkdtemp(join(tmpdir(), "forge-clients-csv-tui-")); | |
| 38 | try { | |
| 39 | const file = writeClientsCsv(d, [row({ name: "maria", for: "Maria" })]); | |
| 40 | expect(file).toBe(join(d, "exports", "forges-sent.csv")); | |
| 41 | expect(readFileSync(file, "utf8")).toBe(clientsCsv([row({ name: "maria", for: "Maria" })])); | |
| 42 | } finally { | |
| 43 | await rm(d, { recursive: true, force: true }); | |
| 44 | } | |
| 45 | }); | |
| 46 | ||
| 47 | describe("GET /forges/export.csv", () => { | |
| 48 | let dir = ""; | |
| 49 | let app: App; | |
| 50 | let servers: Servers; | |
| 51 | const pw = "a-long-clients-csv-passphrase"; | |
| 52 | const signin = async (username: string) => { | |
| 53 | const res = await fetch(`${servers.url}/signin`, { method: "POST", body: new URLSearchParams({ username, password: pw }), redirect: "manual" }); | |
| 54 | return (res.headers.get("set-cookie") ?? "").split(";")[0]!; | |
| 55 | }; | |
| 56 | beforeAll(async () => { | |
| 57 | dir = await mkdtemp(join(tmpdir(), "forge-clients-csv-")); | |
| 58 | app = createApp({ dataDir: dir, url: "https://forge.test", port: 0 }); | |
| 59 | await createUser(app.db, { origin: "seed", trusted: true, username: "alice", email: "[email protected]", password: pw, isAdmin: true }); | |
| 60 | await createUser(app.db, { origin: "seed", trusted: true, username: "bob", email: "[email protected]", password: pw }); | |
| 61 | servers = await serve(app); | |
| 62 | }); | |
| 63 | afterAll(async () => { | |
| 64 | await servers.stop(); | |
| 65 | await rm(dir, { recursive: true, force: true }); | |
| 66 | }); | |
| 67 | ||
| 68 | test("an admin gets text/csv with the header", async () => { | |
| 69 | const res = await fetch(`${servers.url}/forges/export.csv`, { headers: { cookie: await signin("alice") } }); | |
| 70 | expect(res.status).toBe(200); | |
| 71 | expect(res.headers.get("content-type")).toContain("text/csv"); | |
| 72 | expect(await res.text()).toBe("client,forge,sent at,state,last seen\r\n"); | |
| 73 | }); | |
| 74 | test("a forge that was sent is a row, with who it was for", async () => { | |
| 75 | const alice = (await createUser(app.db, { origin: "seed", trusted: true, username: "carol", email: "[email protected]", password: pw, isAdmin: true })); | |
| 76 | if (!alice.ok) throw new Error("user"); | |
| 77 | const token = createToken(app.db, alice.value.id, "rw", "rw").token; | |
| 78 | const made = await fetch(`${servers.url}/api/v1/forges`, { | |
| 79 | method: "POST", | |
| 80 | headers: { authorization: `Bearer ${token}`, "content-type": "application/json" }, | |
| 81 | body: JSON.stringify({ name: "maria", for: "Maria at the bakery", dryRun: false }), | |
| 82 | }); | |
| 83 | expect(made.status).toBe(201); | |
| 84 | const res = await fetch(`${servers.url}/forges/export.csv`, { headers: { cookie: await signin("carol") } }); | |
| 85 | const lines = (await res.text()).split("\r\n"); | |
| 86 | expect(lines[0]).toBe("client,forge,sent at,state,last seen"); | |
| 87 | expect(lines[1]).toMatch(/^Maria at the bakery,maria,\d{4}-/); | |
| 88 | }); | |
| 89 | test("anyone else is refused, and gets no CSV", async () => { | |
| 90 | for (const cookie of ["", await signin("bob")]) { | |
| 91 | const res = await fetch(`${servers.url}/forges/export.csv`, { headers: { cookie } }); | |
| 92 | expect(res.status).toBe(404); | |
| 93 | expect(res.headers.get("content-type")).not.toContain("text/csv"); | |
| 94 | } | |
| 95 | }); | |
| 96 | }); |
test/design-audit.test.ts +1 −1
| @@ -17,7 +17,7 @@ const doc = readFileSync("docs/design/audit.md", "utf8"); | ||
| 17 | 17 | |
| 18 | 18 | /** Routes that answer a file, a fragment, a redirect hop or a callback. */ |
| 19 | 19 | const NOT_PAGES = |
| 20 | /^\/(assets\/|\.well-known\/|icons\/|og\/|live\/|__forge\/|go\/|new\/issue$|events$|system\/stream$|talk\/stream$|settings\/teams\/stream$|sw\.js$|offline$|robots\.txt$|favicon\.ico$|apple-touch-icon(-precomposed)?\.png$|sitemap\.xml$|manifest\.webmanifest$|opensearch\.xml$|llms(-full)?\.txt$|openapi\.json$|releases\.json$|maintenance\.json$|changelog\.atom$|explore\.atom$|docs(\/[^/]*)?$|audit\.csv$|settings\/traffic\/scrapes\/export$|fleet\/graph\/live$|fleet\/graph\.csv$|settings\/origins\/callback$|broker\/origins\/start$|home\/archived\/|settings\/backups\/live$|api\/v1(\/|$))/; | |
| 20 | /^\/(assets\/|\.well-known\/|icons\/|og\/|live\/|__forge\/|go\/|new\/issue$|events$|system\/stream$|talk\/stream$|settings\/teams\/stream$|sw\.js$|offline$|robots\.txt$|favicon\.ico$|apple-touch-icon(-precomposed)?\.png$|sitemap\.xml$|manifest\.webmanifest$|opensearch\.xml$|llms(-full)?\.txt$|openapi\.json$|releases\.json$|maintenance\.json$|changelog\.atom$|explore\.atom$|docs(\/[^/]*)?$|audit\.csv$|settings\/traffic\/scrapes\/export$|fleet\/graph\/live$|fleet\/graph\.csv$|forges\/export\.csv$|settings\/origins\/callback$|broker\/origins\/start$|home\/archived\/|settings\/backups\/live$|api\/v1(\/|$))/; | |
| 21 | 21 | |
| 22 | 22 | const getRoutes = [ |
| 23 | 23 | ...server.matchAll(/router\.add\(\s*"GET",\s*"([^"]+)"/g), |
new above
offline
Both doors: this only toasts where the CSV is on the web; it is not a terminal door. Produce the CSV from the terminal (clientsCsv is already a plain function) and say where it went.