linktoken

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 25, 2026 License: AGPL-3.0 Imports: 10 Imported by: 0

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

This section is empty.

Variables

View Source
var ErrInvalid = errors.New("linktoken: invalid token")

ErrInvalid is returned for malformed or forged tokens.

View Source
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 IssueDay

func IssueDay(t time.Time) uint32

IssueDay is the day a link was issued, for tokens that expire (their Link field).

func IssuedOn

func IssuedOn(day uint32) time.Time

IssuedOn is the day an expiring token was issued.

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
)

Token kinds.

type Signer

type Signer struct {
	// contains filtered or unexported fields
}

Signer signs and verifies tokens with a key derived from the instance key.

func NewSigner

func NewSigner(master []byte) (*Signer, error)

NewSigner derives the signing key from the instance master key with HKDF.

func (*Signer) Digest

func (s *Signer) Digest(parts ...[]byte) []byte

Digest is a keyed hash of parts that must not be reversible, such as the daily key that counts a referral link's visits once per network and browser without cookies. It is stable for the instance.

func (*Signer) Sign

func (s *Signer) Sign(c Claims) string

Sign returns a URL-safe token.

func (*Signer) Verify

func (s *Signer) Verify(token string, want Kind) (Claims, error)

Verify checks a token and returns its claims; want limits the accepted kind.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL