Magic-link implementation notes

Token format

A magic-link token is 180 characters long, base64url-encoded. The decoded payload is a Protocol Buffers message containing the workspace UUID, the request timestamp (unix microseconds), the requester IP hash, and an Ed25519 signature computed over the preceding fields.

Signing keys

Ed25519, one active key at any moment, rotated every 30 days. Older keys are retained in verification mode for 24 hours after rotation to allow in-flight links to complete. Keys are held in a hardware-security-module-backed keyring, never exported.

Replay protection

Each token carries a UUIDv7 nonce. On successful verification, the nonce is atomically inserted into a distributed set with a 15-minute TTL. A repeat verification finds the nonce and rejects the request as a replay.

Rate limits

Five magic-link issuance requests per workspace email per hour, and five per source IP per hour, whichever binds first. Verification requests are not rate-limited (the token itself is the rate limit — you can only ever have five valid tokens in flight per email).

Session cookie issuance

On successful verification, the response sets the ax_ws cookie with a signed workspace-scoped session ID, Secure + HttpOnly + SameSite=Lax, 90-day Max-Age. The cookie is renewed on any authenticated request whose age exceeds 24 hours.

Threat model

In scope: token theft in transit, replay, phishing of the email destination, brute-force enumeration of workspace emails. Out of scope: full compromise of the destination email account (see the parent-account discussion in the blog post).