Public: anyone can read this; the crew can change it.
A forge link that was revoked says so in its own words, apart from an expired one #13625
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/13584-a-forge-link-that-was-revoked-says-so-in → main 8 commits fork 3 threads · 3 unresolved
7 files
changed +118
−28
docs/features/README.md +1
| @@ -319,6 +319,7 @@ Read with the guide page [Hosting forges for others, and getting paid](../guide- | ||
| 319 | 319 | - [](machines-disks.md) |
| 320 | 320 | - [](forge-ready.md) |
| 321 | 321 | - [](forge-link-revoke.md) |
| 322 | - [](forge-link-dead.md) | |
| 322 | 323 | - [](fleet.md) |
| 323 | 324 | - [](forge-it.md) |
| 324 | 325 | - [](forges-side-by-side.md) |
docs/features/forge-link-dead.md added +47
| @@ -0,0 +1,47 @@ | ||
| 1 | # What a forge link says when it no longer works | |
| 2 | ||
| 3 | A forge link works once and for a day, and its sender can withdraw it sooner | |
| 4 | ([](forge-link-revoke.md)). When it no longer works, the | |
| 5 | page says why in plain words, so the person holding it knows what to do next. | |
| 6 | It extends [](forge-link-states.md). | |
| 7 | ||
| 8 | ## Who reads it | |
| 9 | ||
| 10 | - **The recipient** opens the link the sender gave them: `/claim`. | |
| 11 | - **The starter**, the person who started the forge themselves, opens their | |
| 12 | own link: `/welcome`. There is no sender for them to ask. | |
| 13 | ||
| 14 | ## What each one sees | |
| 15 | ||
| 16 | | Link | Status | Recipient (`/claim`) | Starter (`/welcome`) | | |
| 17 | | --- | --- | --- | --- | | |
| 18 | | Withdrawn | 404 | **This link was withdrawn**: "The sender withdrew this link. Ask *alice* to send you a new one." | "You withdrew this link. Start the forge again from the home page." | | |
| 19 | | Expired | 410 | **This link has expired**: "Ask *alice* to send you a new one." | "Start the forge again from the home page." | | |
| 20 | | Unknown | 404 | **This link does not work**: "Sorry, this link does not work any more. Please ask whoever sent it for a new one." | "This link does not work any more. Start the forge again from the home page." | | |
| 21 | ||
| 22 | The starter sees the same title and status with their own sentence. *alice* is the sender's display name, else their username, escaped. An unknown | |
| 23 | link names no one. A withdrawn link never says "expired", and an expired one | |
| 24 | never says "withdrew". A used link and a forge that already has an owner | |
| 25 | keep their own words and a **Sign in** button. No dead link sets a session. | |
| 26 | ||
| 27 | The passkey step (`POST /claim/options`, `/welcome/options`) answers JSON | |
| 28 | `{ "error": "refused", "message": … }` with the same status. A withdrawn link | |
| 29 | gives the message "The sender withdrew this link. Ask them to send you a new | |
| 30 | one." | |
| 31 | ||
| 32 | ## What a guess learns | |
| 33 | ||
| 34 | The link's secret is after the `#`, so it never reaches the server on a GET. | |
| 35 | `GET /claim` and `GET /welcome` read the forge's one current link: anyone who | |
| 36 | opens the bare page learns whether that link was used, expired or withdrawn, | |
| 37 | but never its secret. The POSTs judge the token they carry, so a made-up or | |
| 38 | stale token only ever meets "This link does not work". | |
| 39 | ||
| 40 | ## In the terminal | |
| 41 | ||
| 42 | The terminal has no claim screen: a link is for a browser, and there is no | |
| 43 | account yet to sign in with. The sender's side is in the terminal: *Forges you | |
| 44 | sent* shows `link open`, `link ended, undo with u` or `link ended` on each | |
| 45 | row (see [](forge-link-revoke.md)). | |
| 46 | ||
| 47 | Tested in `test/forge-link-landing.test.ts` and `test/claim-revoke.test.ts`. |
docs/features/forge-link-revoke.md +1 −1
| @@ -6,6 +6,6 @@ A forge you sent carries a claim link that works once and for a day. Its sender | ||
| 6 | 6 | - **Terminal.** Open *Forges you sent* from the palette (admins only). `l` picks a forge whose link is open and ends it; `u` picks one whose link ended in the last minute and brings it back. Each row says `link open` or `link ended, undo with u`. |
| 7 | 7 | - **MCP.** `claim_link` with `{ name, action: "revoke" }` or `{ name, action: "undo" }`. Without `action`, it still re-issues, and only with `reveal: true`. |
| 8 | 8 | |
| 9 | What the client sees: an ended link answers a plain 410 ("This link has ended") and sets no session. A used link cannot be revoked; an expired or used link cannot be undone; an undo after 60 s is refused. | |
| 9 | What the client sees: a withdrawn link answers 404, "The sender withdrew this link", and sets no session ([](forge-link-dead.md) has every case). A used link cannot be revoked; an expired or used link cannot be undone; an undo after 60 s is refused. | |
| 10 | 10 | |
| 11 | 11 | Every change is an admin's, same-origin, and writes `forge.claim_revoked` or `forge.claim_restored`. The link's secret is in no event. The state shown on `/forges` is what the child last said to the parent's probe (no extra database open on the list); a revoke or undo forgets it, so the next list asks again. |
docs/features/forge-link-states.md +4 −5
| @@ -48,11 +48,10 @@ In the terminal, **Forges you sent** has `n` (an admin's): pick an unclaimed for | ||
| 48 | 48 | succeeds. The page sends the security floor and `Referrer-Policy`. |
| 49 | 49 | - **The terminal** has no claim screen: a claim link is for a client in a |
| 50 | 50 | browser, and the terminal has no account to claim into before it exists. |
| 51 | - **A revoked, expired or unknown link** answers the same 404 page, word for | |
| 52 | word: "Sorry, this link does not work any more. Please ask whoever sent it | |
| 53 | for a new one." It names no sender and does not say which of the three it | |
| 54 | is. A link already used still says so and offers sign-in, since its owner | |
| 55 | needs that. | |
| 51 | - **A withdrawn, expired or unknown link** says which, in its own words, for | |
| 52 | the recipient and for the person who started the forge: see | |
| 53 | [](forge-link-dead.md). A link already used still says so | |
| 54 | and offers sign-in, since its owner needs that. | |
| 56 | 55 | - Link validation itself is unchanged. |
| 57 | 56 | |
| 58 | 57 | ## Sent, opened, last seen |
src/web/pages/claim.ts +16 −7
| @@ -13,8 +13,8 @@ | ||
| 13 | 13 | * The GET only shows the form — a link unfurled in a chat app must not |
| 14 | 14 | * spend itself — and the POST, same-origin, makes the account and burns the |
| 15 | 15 | * link in one step. A link that is used or expired says which in one |
| 16 | * sentence and names who sent it (410); one that is revoked or made up is a plain 404; a forge that | |
| 17 | * was not spawned has no claim page at all. | |
| 16 | * sentence and names who sent it (410); one that is revoked says it was withdrawn (404); one made | |
| 17 | * up is a plain 404; a forge that was not spawned has no claim page at all. | |
| 18 | 18 | * |
| 19 | 19 | * Who keeps access is never silent. By default the spawner's account leaves |
| 20 | 20 | * the organisation's Owners when the forge is claimed (the new owner can |
| @@ -113,8 +113,13 @@ function dead( | ||
| 113 | 113 | own = false, |
| 114 | 114 | ): Response { |
| 115 | 115 | const ask = sender === undefined ? "whoever sent it" : sender; |
| 116 | // Only a link that once was real says so (used, expired) and names its | |
| 117 | // sender; unknown and revoked stay one plain 404 naming no one. | |
| 116 | // Only a link that once was real says so (used, expired, revoked) and names | |
| 117 | // its sender; an unknown one stays a plain 404 naming no one. The POSTs | |
| 118 | // (/claim, /welcome and their /options) judge the posted token, so a guess | |
| 119 | // only ever meets "unknown". GET /claim and /welcome carry no token (it | |
| 120 | // rides the fragment) and read the forge's one current link: anyone who | |
| 121 | // opens the bare page learns whether that link was used, expired or | |
| 122 | // withdrawn, never its secret, as used and expired already did. | |
| 118 | 123 | const gone = { |
| 119 | 124 | status: 404, |
| 120 | 125 | title: "This link does not work", |
| @@ -132,7 +137,11 @@ function dead( | ||
| 132 | 137 | title: "This link has expired", |
| 133 | 138 | text: `Ask ${ask} to send you a new one.`, |
| 134 | 139 | }, |
| 135 | revoked: gone, | |
| 140 | revoked: { | |
| 141 | status: 404, | |
| 142 | title: "This link was withdrawn", | |
| 143 | text: `The sender withdrew this link. Ask ${ask} to send you a new one.`, | |
| 144 | }, | |
| 136 | 145 | owned: { |
| 137 | 146 | status: 410, |
| 138 | 147 | title: "This forge already has an owner", |
| @@ -144,7 +153,7 @@ function dead( | ||
| 144 | 153 | unknown: "This link does not work any more. Start the forge again from the home page.", |
| 145 | 154 | used: "If it was you, sign in. Otherwise start a forge of your own from the home page.", |
| 146 | 155 | expired: "Start the forge again from the home page.", |
| 147 | revoked: "This link does not work any more. Start the forge again from the home page.", | |
| 156 | revoked: "You withdrew this link. Start the forge again from the home page.", | |
| 148 | 157 | }; |
| 149 | 158 | if (own) says.text = mine[state] ?? says.text; |
| 150 | 159 | return page( |
| @@ -394,7 +403,7 @@ const LINK_REFUSED: Record<Exclude<ClaimState["state"], "ok">, string> = { | ||
| 394 | 403 | unknown: "This link does not work any more.", |
| 395 | 404 | used: "This link was already used.", |
| 396 | 405 | expired: "This link has expired.", |
| 397 | revoked: "This link does not work any more.", | |
| 406 | revoked: "The sender withdrew this link. Ask them to send you a new one.", | |
| 398 | 407 | owned: "This forge already has an owner.", |
| 399 | 408 | }; |
| 400 | 409 |
test/claim-revoke.test.ts +23 −1
| @@ -112,7 +112,29 @@ describe("revoking a forge link", () => { | ||
| 112 | 112 | }); |
| 113 | 113 | expect(post.status).toBe(404); |
| 114 | 114 | expect(post.headers.get("set-cookie")).toBeNull(); |
| 115 | expect(await post.text()).toContain("This link does not work"); | |
| 115 | expect(await post.text()).toContain("The sender withdrew this link"); | |
| 116 | }); | |
| 117 | ||
| 118 | test("the starter's own page says 'You withdrew this link'; the recipient's never does, nor the reverse", async () => { | |
| 119 | // "one" is still revoked by the test above; the next test undoes it. | |
| 120 | const url = kids["one"]!.servers.url; | |
| 121 | const send = (path: string) => | |
| 122 | fetch(`${url}${path}`, { | |
| 123 | method: "POST", | |
| 124 | headers: { origin: url }, | |
| 125 | body: new URLSearchParams({ token: kids["one"]!.token, username: "x", email: "[email protected]" }), | |
| 126 | redirect: "manual", | |
| 127 | }); | |
| 128 | const own = await send("/welcome"); | |
| 129 | const ownText = await own.text(); | |
| 130 | expect(own.status).toBe(404); | |
| 131 | expect(own.headers.get("set-cookie")).toBeNull(); | |
| 132 | expect(ownText).toContain("You withdrew this link"); | |
| 133 | expect(ownText).not.toContain("The sender withdrew this link"); | |
| 134 | const theirs = await send("/claim"); | |
| 135 | const theirText = await theirs.text(); | |
| 136 | expect(theirText).toContain("The sender withdrew this link"); | |
| 137 | expect(theirText).not.toContain("You withdrew this link"); | |
| 116 | 138 | }); |
| 117 | 139 | |
| 118 | 140 | test("a revoke is receipted, and undone within the minute", async () => { |
test/forge-link-landing.test.ts +26 −14
| @@ -1,8 +1,8 @@ | ||
| 1 | 1 | /** |
| 2 | 2 | * A forge link's landing page (#12416), fetched with no cookie and no script: |
| 3 | 3 | * a good link is server-rendered, small, names who made the forge, leaks no |
| 4 | * token, and carries the security floor; a revoked, expired or unknown link | |
| 5 | * answers one identical kind page, so a stranger cannot tell which it is. | |
| 4 | * token, and carries the security floor; an unknown link answers one kind page that names no one, | |
| 5 | * and a revoked link says the sender withdrew it (#13584), apart from an expired one. | |
| 6 | 6 | */ |
| 7 | 7 | import { afterAll, beforeAll, describe, expect, test } from "bun:test"; |
| 8 | 8 | import { mkdtemp, rm } from "node:fs/promises"; |
| @@ -84,29 +84,39 @@ describe("a forge link's landing page", () => { | ||
| 84 | 84 | expect(text).not.toMatch(/href="[^"]*token[^"]*"/i); |
| 85 | 85 | }); |
| 86 | 86 | |
| 87 | test("revoked and unknown answer the same 404 and name no one; expired is a 410 naming the sender", async () => { | |
| 87 | test("a revoked link says the sender withdrew it; an unknown token says only that it does not work; neither names the forge", async () => { | |
| 88 | 88 | setStored({ e: future(), r: new Date().toISOString() }); |
| 89 | 89 | const revoked = await get(); |
| 90 | setStored({ r: undefined, e: new Date(Date.now() - 3_600_000).toISOString() }); | |
| 91 | const expired = await get(); | |
| 90 | const withToken = await fetch(`${childServers.url}/claim`, { | |
| 91 | method: "POST", | |
| 92 | headers: { origin: childServers.url }, | |
| 93 | body: new URLSearchParams({ token }), | |
| 94 | }); | |
| 92 | 95 | const unknown = await fetch(`${childServers.url}/claim`, { |
| 93 | 96 | method: "POST", |
| 94 | 97 | headers: { origin: childServers.url }, |
| 95 | 98 | body: new URLSearchParams({ token: "x".repeat(43) }), |
| 96 | 99 | }); |
| 97 | const bodies = await Promise.all([revoked, unknown].map((r) => r.text())); | |
| 98 | for (const r of [revoked, unknown]) { | |
| 100 | setStored({ r: undefined, e: new Date(Date.now() - 3_600_000).toISOString() }); | |
| 101 | const expired = await get(); | |
| 102 | const [rev, tok, unk] = await Promise.all([revoked, withToken, unknown].map((r) => r.text())); | |
| 103 | for (const r of [revoked, withToken, unknown]) { | |
| 99 | 104 | expect(r.status).toBe(404); |
| 100 | 105 | expect(r.headers.get("x-content-type-options")).toBe("nosniff"); |
| 101 | 106 | expect(r.headers.get("set-cookie")).toBeNull(); |
| 102 | 107 | } |
| 103 | const strip = (t: string) => t.replace(/nonce="[^"]*"|<time[^>]*>/g, ""); | |
| 104 | expect(strip(bodies[0]!)).toBe(strip(bodies[1]!)); | |
| 105 | expect(bodies[0]).toContain("does not work any more"); | |
| 106 | expect(bodies[0]).not.toMatch(/expired|revoked|ended|alice|made-up/i); | |
| 107 | expect(Buffer.byteLength(bodies[0]!)).toBeLessThan(20 * 1024); | |
| 108 | for (const t of [rev!, tok!]) { | |
| 109 | expect(main(t)).toContain("The sender withdrew this link."); | |
| 110 | expect(main(t)).toContain("to send you a new one."); | |
| 111 | expect(main(t)).not.toMatch(/expired/i); | |
| 112 | } | |
| 113 | expect(unk).toContain("does not work any more"); | |
| 114 | expect(unk).not.toMatch(/expired|revoked|withdrew|ended|alice|made-up/i); | |
| 115 | expect(Buffer.byteLength(rev!)).toBeLessThan(20 * 1024); | |
| 108 | 116 | expect(expired.status).toBe(410); |
| 109 | expect(await expired.text()).toContain("This link has expired"); | |
| 117 | const exp = await expired.text(); | |
| 118 | expect(exp).toContain("This link has expired"); | |
| 119 | expect(exp).not.toContain("withdrew"); | |
| 110 | 120 | }); |
| 111 | 121 | |
| 112 | 122 | const sendersName = (name: string) => |
| @@ -142,7 +152,9 @@ describe("a forge link's landing page", () => { | ||
| 142 | 152 | setStored({ e: future(), u: new Date().toISOString() }); |
| 143 | 153 | expect((await optionsFor()).status).toBe(410); |
| 144 | 154 | setStored({ u: null, r: new Date().toISOString() }); |
| 145 | expect((await optionsFor()).status).toBe(404); | |
| 155 | const revoked = await optionsFor(); | |
| 156 | expect(revoked.status).toBe(404); | |
| 157 | expect(await revoked.text()).toContain("The sender withdrew this link."); | |
| 146 | 158 | setStored({ r: undefined, e: future() }); |
| 147 | 159 | }); |
| 148 | 160 |
new above
offline
This comment claims revoked is told apart on POST only with its own token. GET /claim and /claim/options carry no token and still say withdrawn. Reword it to say what happens.