Documentation
¶
Overview ¶
Package linktoken signs the tokens embedded in emails: open pixel, click redirect, one-click unsubscribe (RFC 8058), preference center, view online and double opt-in confirmation links. Tokens are compact, unforgeable (HMAC-SHA256 truncated to 128 bits) and carry no personal data in clear.
Index ¶
Constants ¶
const ConfirmValid = 30 * 24 * time.Hour
ConfirmValid is how long a double opt-in confirmation link works (review 2026-11 DP-3). A Confirm token carries the day it was issued in Link and, when it was sent for one signup, the form submission in MessageID.
Variables ¶
var ErrInvalid = errors.New("linktoken: invalid token")
ErrInvalid is returned for malformed or forged tokens.
var ErrSignature = fmt.Errorf("%w: the signature doesn't match", ErrInvalid)
ErrSignature is returned for a well-formed token of the wanted kind whose signature doesn't match: signed with an earlier instance key, or forged. It is also ErrInvalid.
Functions ¶
func Expired ¶
Expired reports whether a token issued on the day in c.Link is older than valid at now. The issue day counts whole, so a link gets a day's grace.
func Until ¶
Until is when a token made with UntilMinute stops working. A token signed without one (Link 0) stopped long ago.
func UntilMinute ¶
UntilMinute is the Link of a token that works until t, to the minute, for links whose life depends on where they're sent (a paid member's billing link: an hour when asked for, 30 days in an email).
Types ¶
type Claims ¶
type Claims struct {
Kind Kind
WorkspaceID uuid.UUID
MessageID uuid.UUID // uuid.Nil when not tied to a message
ContactID uuid.UUID
// Link is the index of the link in campaign_links for Click tokens.
Link uint32
}
Claims identify the message (or contact, for links outside a message).
type Kind ¶
type Kind byte
Kind is what a token is for; a token for one purpose never works for another.
const ( Open Kind = 1 Click Kind = 2 Unsubscribe Kind = 3 Preferences Kind = 4 ViewOnline Kind = 5 Confirm Kind = 6 // Polls and surveys (design expansion, X11: 110–119, numbered after // the workstream so parallel kinds never collide). Link is the poll's // or the survey's number. A poll link without a message and a contact // is the web archive's: its answers count apart, as non-contacts'. A // test link's MessageID names the test address (poll_test_recipients). Poll Kind = 110 Survey Kind = 111 PollTest Kind = 112 SurveyTest Kind = 113 // Grow (design expansion, X15: 150–159): a referrer's hub, the // recommendations page and a reward's download. Their Link holds the // day they were issued (IssueDay), so they expire. ReferralHub Kind = 150 Recommendations Kind = 151 RewardDownload Kind = 152 // Review 2026-10 (R05: 200–209): the hidden link of tracked emails, // which only machines follow (bot clicks, review AN-2). Its Link is // always 0. Honeypot Kind = 200 )
Token kinds. Packages declare their own kinds next to the code that signs them (earn 160–163, revenue 170, products 190–192, publicpages 194, clicktoken 201, push 220); every kind is used once, which TestKindsAreUnique checks across the source. Pick an unused number.
type Signer ¶
type Signer struct {
// contains filtered or unexported fields
}
Signer signs and verifies tokens with a key derived from the instance key. Tokens signed with a previous instance key still verify, so links in emails already sent keep working after a key rotation (review 2026-11 OP-5).
func NewSigner ¶
NewSigner derives the signing key from the instance master key with HKDF, and the verifying keys of the previous master keys.