What a forge link says when it no longer works
A forge link works once and for a day, and its sender can withdraw it sooner (forge-link-revoke.md). When it no longer works, the page says why in plain words, so the person holding it knows what to do next. It extends forge-link-states.md.
Who reads it
- The recipient opens the link the sender gave them:
/claim. - The starter, the person who started the forge themselves, opens their
own link: /welcome. There is no sender for them to ask.
What each one sees
| Link | Status | Recipient (/claim) | Starter (/welcome) |
|---|---|---|---|
| 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." |
| Expired | 410 | This link has expired: "Ask alice to send you a new one." | "Start the forge again from the home page." |
| 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." |
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 link names no one. A withdrawn link never says "expired", and an expired one never says "withdrew". A used link and a forge that already has an owner keep their own words and a Sign in button. No dead link sets a session.
The passkey step (POST /claim/options, /welcome/options) answers JSON
{ "error": "refused", "message": … } with the same status. A withdrawn link
gives the message "The sender withdrew this link. Ask them to send you a new
one."
What a guess learns
The link's secret is after the #, so it never reaches the server on a GET.
GET /claim and GET /welcome read the forge's one current link: anyone who
opens the bare page learns whether that link was used, expired or withdrawn,
but never its secret. The POSTs judge the token they carry, so a made-up or
stale token only ever meets "This link does not work".
In the terminal
The terminal has no claim screen: a link is for a browser, and there is no
account yet to sign in with. The sender's side is in the terminal: Forges you
sent shows link open, link ended, undo with u or link ended on each
row (see forge-link-revoke.md).
Tested in test/forge-link-landing.test.ts and test/claim-revoke.test.ts.