Skip to content

fix(session): a tailnet login survives restarts and ends on rotation (#231) - #233

Merged
davison merged 10 commits into
mainfrom
task/231-tailnet-sessions-that-survive-restarts-a
Sep 30, 2026
Merged

davison merged 10 commits into
mainfrom
task/231-tailnet-sessions-that-survive-restarts-a

Conversation

@davison

@davison davison commented Sep 30, 2026

Copy link
Copy Markdown
Owner

Closes #231

Replaces #232, which GitHub never linked to #231; its review rounds are there: #232 (comment)

A tailnet login now survives daemon restarts, upgrades and reboots, and ends when the token is rotated. Milestone M12 (#230); this adopts capture #229, which task finish closes.

What changed

  • internal/session: the in-memory store is replaced by a stateless signed value: v1.<issued-at>.<random id>.<HMAC-SHA256>. The MAC covers the fields and the tailnet host name, and its key is derived from the token. The check is strict about shape, compares with hmac.Equal, and refuses an issued-at from the future or one past the idle limit.
  • internal/token: the generation counter is replaced by Derive(purpose) and AuthenticateDerive(presented, purpose), which keep the one-read guarantee the login relies on.
  • internal/server: the guard checks the cookie against the key of the token in force now. It reissues a session a day old or more, but only on a response it serves. Every cookie, whether from a login or a reissue, gets the same attributes from one function.
  • Docs: the introduction's "A browser on the tailnet" section, docs/running.md and contrib/mdn.1 say how long a login lasts, what ends it, and that every device logs in once more at the upgrade to v0.3.1.

Requirements

  • M12-R1 (survives a restart): TestTailnetSessionSurvivesARestart, and ui/e2e/tailnet-session.test.mjs in Chromium behind TLS. The upgrade and newer-build legs were measured with a scratch rig; the table is in the Decision linked below.
  • M12-R2 (rotation ends every session, with no forgery or replay): TestTailnetRotationEndsTheSession (existing), TestTailnetRotationWhileStoppedEndsTheSession, TestTailnetRotationEndsTheSessionAcrossARestart, TestTailnetCookieFromAnotherTokenIsRefused, TestTailnetCookieIsBoundToItsHostName, TestTailnetRejectsAForgedCookie (existing), and the session package's tamper, truncation and other-key tests. The e2e suite covers rotation while running and while stopped.
  • M12-R3 (refreshed on use, and the remaining bound stated): TestTailnetSessionIsRefreshedOnUse, TestTailnetUnusedSessionLapses and TestTailnetRefusedRequestIsNotReissued. The idle limit is 30 days, chosen by the operator on the checkpoint (option A, Tailnet sessions that survive restarts and end on rotation #231 (comment)). It lives in session.Idle (internal/session/session.go:48) and in the docs at docs/introduction.md:431 (Max-Age=2592000 in the Set-Cookie example), :448, :451-452, and contrib/mdn.1:59-60. Each says the limit counts idle time, not a fixed lifetime.
  • M12-R4 (protections kept, nothing new at rest): the cookie attributes are asserted in the unit tests and the e2e suite. Nothing is written to disk. The throttle, loopback and bearer-token tests pass unchanged.
  • M12-R5 (this task's share): the introduction and the man page. The record belongs to the doc-synthesizer.

Decisions and deviations

Checks

make check and make e2e pass locally (Chromium 153). Run against the v0.3.0 tree's binary, the new e2e suite fails on the restart leg, as it should.

No feat commit: nothing user-facing is added. The commits are fix, test, and one docs for the prose.

🤖 Generated with Claude Code

davison and others added 9 commits September 30, 2026 11:20
serveBase starts a second Server over the notes and token file an earlier
one used, which is what a restarted process has and nothing more.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…231)

A session was a random id in the daemon's memory, so every restart,
upgrade and reboot logged every device out. It is now a signed value:
v1.<issued-at>.<random id>.<HMAC-SHA256>, the MAC over the fields and the
tailnet name, keyed by a key derived from the token (token.Store.Derive).
Nothing about sessions is held in memory or on disk, so:

- a daemon started over the same token file derives the same key and
  accepts the cookie the browser kept;
- mdn token --rotate, or a token file replaced while stopped, changes the
  key, and every older cookie fails its MAC on the next request;
- no secret is at rest beyond the token file.

A session a day old or more is reissued on a request the guard serves,
with Max-Age equal to the idle limit (session.Idle, 30 days pending the
operator's answer on the checkpoint), and refused once unused for that
long. The token's generation counter is replaced by the derived key;
AuthenticateDerive keeps the one-read guarantee the login needs. The
throttle, loopback, the bearer token's exemption and the cookie's
attributes are unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Chromium logs in through a local TLS proxy that stands in for tailscale
serve; the daemon is stopped and started and the same cookie is still a
session; a rotation while running, and one while stopped, end it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The introduction's browser-on-the-tailnet section and the running guide:
a login survives restarts and upgrades, ends on rotation or after 30 days
unused, and every device logs in once more at the upgrade to v0.3.1.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review nit 3 on PR #232: removing the id-length check went unnoticed.
Three re-signed cases, a byte short, a byte long and empty, now fail
against that mutation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…#231)

Review nits 2 and 4 on PR #232: the introduction's rotation bullet says
that writing an earlier token back makes its sessions good again, up to
the idle limit; docs/running.md no longer says an upgrade never logs a
device out, and is rewrapped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…me (#231)

The operator chose a 30-day idle limit on the checkpoint; the page now
says idle, as the introduction does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@davison

davison commented Sep 30, 2026

Copy link
Copy Markdown
Owner Author

Review — 1211ba6

Round two: the delta review of the fix pass for round one (#232 review). The code under review has not changed since round one. This PR has the same five commits as #232 (175f8f7…5f8bf1c), and the delta is four commits, 5f8bf1c..1211ba6: one test and three to the docs and man page. The round-one verification of the code (MAC, rotation, host binding, refresh, cookie attributes, e2e against v0.3.0, the Chromium table) still applies.

Round-one findings

  1. The gate: cleared. The operator resolved it as option A, 30 days idle (Tailnet sessions that survive restarts and end on rotation #231 (comment)), and cc:needs-decision is off Tailnet sessions that survive restarts and end on rotation #231 (labels: cc:task only). The code already held 30 days, so nothing in it changes.

  2. A restored token revives its sessions: fixed. The addendum Decision records it with the trade-off, and why no state is added to prevent it (Tailnet sessions that survive restarts and end on rotation #231 (comment)). The introduction's rotation bullet now says so (docs/introduction.md:445-447), in the terms I measured: good again, up to the idle limit.

  3. The id length check is now tested. 829fd6c adds three resign cases: a byte short, a byte long, and empty. I reverted the check in my worktree (err != nil || len(raw) != idBytes → &&) and ran go test ./internal/session. It fails on all three:

    --- FAIL: TestTamperingIsRefused
        session_test.go:105: id a byte short: "v1.1790845200.AAAAAAAAAAAAAAAAAAAA.8xxq_…" was accepted
        session_test.go:105: id a byte long: "v1.1790845200.AAAAAAAAAAAAAAAAAAAAAAA.CcCV…" was accepted
        session_test.go:105: id empty: "v1.1790845200..N99r…" was accepted
    

    Restored, go test ./internal/session ./internal/server ./internal/token passes.

  4. Docs: fixed. The places that name the limit:

    • docs/introduction.md:431, the Set-Cookie example with Max-Age=2592000. It is a header, so it cannot say "idle", and 30 days is correct as the chosen value.
    • :448, "unused for 30 days".
    • :451-452, "after 30 days idle … 30 days from the last reissue, not from the first login".
    • contrib/mdn.1:59-60, "after 30 days idle: a session in use is renewed, and has no fixed lifetime". man --warnings -l is clean and it renders as intended.

    All match session.Idle and the resolved gate. The introduction's "from the last reissue" is exactly what the code counts. The shorter "30 days idle" is right to within a day, since a used session is reissued only once it is a day old; that is fine for prose. docs/running.md:65-67 now names the one-off extra login at the v0.3.1 upgrade, and the paragraph is rewrapped. Everywhere else in the docs still reads true.

  5. The plan's same-id refresh: recorded. The addendum Decision corrects the plan and gives the reason. The code is unchanged, which is right.

Finding 6, the PR-to-issue link, is left out of this verdict at the coordinator's direction; the operator is handling it. For the record, closingIssuesReferences on #233 is still [] with a first line of Closes #231, so the qualified form was not the cause I guessed in round one.

Commit types (local rule)

I read each new commit against its files:

  • 829fd6c test(session): internal/session/session_test.go only.
  • 3621f42 docs: docs/introduction.md and docs/running.md, prose only. Correct.
  • ecf9baf fix(man): contrib/mdn.1. Not docs, so CI runs for it. Correct.
  • 1211ba6 docs: docs/introduction.md only. Correct.

The PR mixes docs with other types, so check and e2e ran, and CI shows both SUCCESS on the head.

Nits (non-blocking, no re-review needed)

  • docs/introduction.md:452 ends early ("…not from the first login. A lost") and the next line carries the rest. It needs a reflow.

Verdict: approve

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@davison davison linked an issue Sep 30, 2026 that may be closed by this pull request
@davison

davison commented Sep 30, 2026

Copy link
Copy Markdown
Owner Author

Operator confirmation: reviewed and accepted by @davison as both author and operator (pure solo tier, SPEC §5) — no independent principal exists in this project.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tailnet sessions that survive restarts and end on rotation

1 participant