Skip to content

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

Closed
davison wants to merge 9 commits into
mainfrom
task/231-sessions
Closed

davison wants to merge 9 commits into
mainfrom
task/231-sessions

Conversation

@davison

@davison davison commented Sep 30, 2026

Copy link
Copy Markdown
Owner

Closes #231

Replaces #233 and #232, which GitHub never linked to #231. The review rounds are on #232: #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

Closing: opened from a fresh branch name (task/231-sessions) to test whether the linked branch was why GitHub never connected #232 or #233 to #231. It made no difference: closingIssuesReferences stayed empty and #231 got no connected event after a minute of polling. #233 stays open as the PR for #231; this branch is deleted.

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