Signed tokens

The signing package issues tokens that cannot be forged or altered. They expire after an age you choose and survive secret-key rotation.

Use them when you need to know that your application created a value, and when:

• links in emails: confirm an address, accept an invitation, unsubscribe;
• values you hand to the browser and read back.

#Ask your agent

#Configure the secret key

Generate a key and supply it through your deployment’s secret configuration:

go tool cicadel secretkey       # prints a new 43-character random key
export CICADEL_SECRET_KEY=...   # never commit it

• Settings validation rejects short keys, fallbacks without a current key and repeated keys. It never prints them.
• go run manage.go check --deploy warns (settings:secret_key) when no key is set.
• apptest.Settings() uses the fixed apptest.TestSecretKey, so tests can sign tokens without configuration.

#Sign and verify in a handler

Each kind of token has a purpose: a stable printable name such as "accounts.confirm-email". A token signed for one purpose never verifies for another, even under the same secret key.

type confirmation struct {
	UserID int64  `json:"user_id"`
	Email  string `json:"email"`
}

func sendConfirmation(w http.ResponseWriter, r *http.Request) {
	s, err := signing.For(r.Context(), "accounts.confirm-email")
	if err != nil {
		response.Error(w, 500) // signing.ErrNoKey: CICADEL_SECRET_KEY is missing
		return
	}
	token, err := signing.SignJSON(s, confirmation{UserID: user.ID, Email: user.Email})
	if err != nil {
		response.Error(w, 500)
		return
	}
	link := "https://example.com/confirm?token=" + token // URL-safe; no escaping needed
	// email the link
}

func confirm(w http.ResponseWriter, r *http.Request) {
	s, err := signing.For(r.Context(), "accounts.confirm-email")
	if err != nil {
		response.Error(w, 500)
		return
	}
	c, err := signing.VerifyJSON[confirmation](s, r.URL.Query().Get("token"), 48*time.Hour)
	switch {
	case errors.Is(err, signing.ErrExpired):
		// genuine but too old: offer to send a new link
	case err != nil:
		response.Error(w, 400) // forged, altered, wrong purpose or retired key
		return
	}
	// c.UserID and c.Email are exactly what you signed
}

The application puts its keyring on every request’s context, so signing.For works in any handler. Outside a request, such as a management command or a background job, use app.Signer(purpose). Both use the same keys, so a token issued in a job verifies in a handler.

#API

Verification rules:

• Verify requires a positive maxAge. Zero is a programming error, not “no expiry”.
• errors.Is(err, signing.ErrInvalid) is true for every rejected token, including expired ones. Test signing.ErrExpired first to treat expiry differently.
• A token whose issue time is more than signing.ClockSkew (one minute) in the future is rejected.

#Single-use tokens

A signature proves who issued a token. It does not prove the token is unused.

To make a token single-use, include state that the action changes. Compare it on verification. Good choices are a hash of the current email address or of the password hash.

For example, a password-reset token that carries a hash of the stored password hash stops working once the password changes. Never put the raw secret in the token.

#Rotate the secret key

1. Generate a new key. Deploy it as CICADEL_SECRET_KEY and move the old key to CICADEL_SECRET_KEY_FALLBACKS. New tokens use the new key. Existing tokens still verify.
2. Wait for the longest maxAge your application uses.
3. Remove the old key from CICADEL_SECRET_KEY_FALLBACKS. Tokens signed with it now fail with signing.ErrInvalid.

#How it works

The token format is base64url(payload) "." base36(unix seconds) "." base64url(MAC).

• The MAC is HMAC-SHA256 over the first two parts.
• It uses a per-purpose key derived as HMAC-SHA256(secret key, "cicadel-signing-v1\x00" + purpose).
• Verification compares MACs in constant time against the current key and each fallback.
• Only the URL-safe base64 alphabet is accepted, so every token has exactly one encoding.
• The payload is decoded only after the MAC matches.
• Input longer than a maximum-size token is rejected before any work.

Tests that cover this:

• signing/signing_test.go: tampering at every position, purpose and key separation, expiry boundaries, clock skew, rotation, key validation, JSON strictness, concurrency and the FuzzVerify fuzz target.
• signing_test.go: request-context signing, rotation across deployments and settings validation through a running application.
• internal/scaffold/signing_test.go: a generated project loading keys from the environment.