Where a sent forge link stands
This page is for the person who sends forges to clients and wants to know, without asking, whether a client took the link. It extends client-forge.md.
The four states
/forges, the terminal's forges screen and MCP tool forges say the same
words for each forge sent, read from what is already kept:
- Sent: the link was made and not opened. The time is when it was sent.
- Opened: the link was spent, but nobody has signed in yet.
- Signed in: the client made an account. The time is when the link was
spent; when the child did not say, no time is shown.
- Last tell: the client told the crew something. The time is the latest
tell the child's heartbeat carries (it carries the latest, not the first).
Resend
The button on every unclaimed row says Send a new link: it opens a preview (who it is for, what stops working), and only its confirm issues the link and ends the old one; each issue writes a forge.claim_reissued event naming the forge and whom it was for. The API takes { "dryRun": true } on the same route, and MCP claim_link without reveal returns the same preview.
A link unopened for three days reads "Not opened in 3 days", and the page's
button says Resend (it opens /forges/<name>/claim-link, the same preview as
"Send a new link"; its confirm issues the new link and the old one stops working). In MCP, the row's
stage.resend is true; the action is MCP tool claim_link with the forge's
name. A claimed forge is never marked.
In the terminal, Forges you sent has n (an admin's): pick an unclaimed forge, read the same preview, and choose "Send a new link" to confirm; the palette's "A fresh claim link for a forge I sent" asks the name and shows the same preview. Both go through previewDoor and reissueDoor, so who may is the page's rule. Tested in test/forge-link-reissue.test.ts.
Left out
- The first tell's time: the heartbeat carries only the latest tell.
- A one-call resend in MCP:
claim_linkis that call.
What a client's link page says
/claim (tested in test/forge-link-landing.test.ts, no cookie, no script):
- A good link is server-rendered under 20 KB: one sentence naming who made
the forge for them ("alice made maria for you."), a username and one button
(the passkey button, or a password form where the browser cannot make one).
The page has no top bar or footer. The link's secret rides the #
fragment, so it is in no request, no outgoing link and no Referer; a script
moves it into a hidden field. With no script the server cannot see a
fragment, so a <noscript> field asks for the part of the link after the #
to be pasted, beside the password form; the test submits that form and
succeeds. The page sends the security floor and Referrer-Policy.
- The terminal has no claim screen: a claim link is for a client in a
browser, and the terminal has no account to claim into before it exists.
- A withdrawn, expired or unknown link says which, in its own words, for
the recipient and for the person who started the forge: see forge-link-dead.md. A link already used still says so and offers sign-in, since its owner needs that.
- Link validation itself is unchanged.
Sent, opened, last seen
The sender's /forges row and the terminal's forges screen (an admin's; a
guest sees none of it) carry one line from the same code (seenOf):
"sent 3d ago · opened 1d ago · last seen 2h ago". It replaces the separate
stage and "a person last did something" words, which said the same thing; a
resend notice and the last tell keep their own words.
- Opened means a browser asked for the claim page, not that a person read
it. The client forge notes the first such request while the link is open and
keeps it with the link, so it survives a restart and needs no migration. A
link preview, unfurl or prefetch does not count: a request that does not ask
for HTML, or that says Purpose, Sec-Purpose, X-Purpose or X-Moz is
prefetch or preview. Those headers are written by the client, so anyone
holding the link can mark it opened; one write per link, only while open.
- The client's own link (
/welcome) never notes an open. - A link spent before opens were noted reads "opened (time not noted)": the
spend time is not shown as the open time, because the open came earlier.
- Not opened yet is said while no browser has asked.
- Last seen appears once the client signed in: the time of a person's last
action there. It is blank before, never "now".
- Nothing is said while the forge is still being made or did not answer.
- Link replaced appears after the sender taps Send again: the earlier link
stopped working and a fresh one is waiting, and the time is that of the
receipt (forge.claim_reissued). It shows only while the forge is unclaimed;
once the client has claimed, it is dropped and "last seen" stands alone.
A way back for a claimed owner who lost every passkey
A forge another forge made sends no mail, so /recover there says so and shows
no email form; on a standalone forge with no mail it points to a site admin.
A claimed owner who lost every passkey
- The account that sent the forge (or a site admin) opens Forges, then
Recovery link on the claimed row (/forges/<name>/recovery-link), or the
terminal palette entry "A recovery link for a forge's owner who lost their
passkey".
- The preview says who it signs in as. Only its confirm mints the link, shown
once.
- Hand it to the owner privately. Opening
/recover?token=...on their forge
registers a new passkey and signs them in. It works once, for 7 days
(core/edge_handover.ts); making another ends the earlier one.
An unclaimed forge is refused: send it a new claim link instead.
Decisions:
- The sender may mint, as well as a site admin (
mayReissue). The sender is the
only person who knows the owner; this is the same trust as the claim link.
The cost is that they can sign in as the owner, so every link is recorded:
the forge's own events get account.way_back_minted naming the sender, and the
sender's forge gets forge.recovery_minted with the sender as actor.
- At most 5 links an hour per account.
Tested in test/forge-recovery.test.ts.