Consent and one-click unsubscribe

Applies to The Fabrica v0.1.2. Documentation source: 1ee1bc9cb661, including post-release documentation corrections.

GET/POST /api/v1/email/unsubscribe?t=<token> is the only public, unauthenticated, side-effect-having endpoint in the factory. That’s not an oversight.

What gates it

The endpoint takes one query param: t — an HMAC-SHA256 token bound to (clerk_user_id, issued_at) signed with EMAIL_UNSUBSCRIBE_SECRET. The handler:

1. Verifies the HMAC. Bad/missing/forged → 401.
2. Looks up the user by clerk_user_id.
3. Sets User.marketing_consent_given = False.
4. Redirects to (marketing)/unsubscribed.

No Clerk session required. No CSRF token. No login.

The constraint: RFC 8058 + mailbox reality

RFC 8058 (“Signaling One-Click Functionality for List Email Headers”) mandates that the List-Unsubscribe URL in marketing email headers must work via a single HTTP request — no interactive auth, no multi-step flow. Gmail’s “Unsubscribe” button uses this. Apple Mail uses this. Outlook uses this.

If the endpoint were auth-gated, three failure modes:

1. The mailbox-on-another-device problem. User clicks “Unsubscribe” from their work Gmail. They’ve never logged in to your app on that machine. Auth-gated endpoint → “please log in to unsubscribe” → user gives up + clicks “Mark as spam” instead. Your sender reputation craters.
2. The lost-session problem. User receives the email 6 months after signup. Clicks unsubscribe. Their Clerk session expired. Auth-gated → login prompt → they don’t remember the password. Spam button gets clicked. Reputation, again.
3. RFC 8058 compliance. Gmail won’t show the inline Unsubscribe button in the message header unless the List-Unsubscribe-Post: List-Unsubscribe=One-Click header is present AND the endpoint accepts unauthenticated POST. If you gate auth, Gmail demotes your delivery score.

The HMAC token IS the auth

Cryptographically: the token is unforgeable without the secret + binds to a single user + has a TTL (no MAX_AGE in our default — Gmail caches links, so we tolerate replay; the worst case is “unsubscribe gets re-applied” which is idempotent). An attacker who:

• Doesn’t have the secret: can’t mint a valid token.
• Has the secret: has bigger problems than unsubscribing your users.
• Has someone else’s token (stolen email, phishing): can unsubscribe that user, which is annoying but not catastrophic — the user just re-opts-in via POST /me/consent.

So the threat model is: “someone can unsubscribe a user from marketing email” — recoverable, audit-logged, low-blast-radius. Worth trading for the deliverability + RFC compliance benefits.

The audit-log side

The handler writes action="email.unsubscribed" with details={"via": "one_click_link"} + the requester IP. If you ever need to investigate “did Alice really unsubscribe or was it malicious?”, the IP + timestamp are there.

What it doesn’t gate against

• CSRF: the endpoint accepts both GET and POST. There is no cross-site form that can mint a valid token + submit it, so CSRF via origin-spoofing isn’t viable. (The query-param HMAC is the CSRF defense.)
• Replay: an old token still works. By design — Gmail caches the URL in the message header for weeks. We accept the “unsubscribe is idempotent” trade-off to support that.

Receipts

• Endpoint: backend/src/api/routers/email.py:unsubscribe
• Token primitive: backend/src/services/unsubscribe.py
• Header injection: backend/src/services/email.py:send_marketing

Provenance. Documentation source: 1ee1bc9cb6619c19f57766731e7884b37f515dc9 (main).

Extracted from docs/recipes/why-unsubscribe-is-public.md.

That commit is later than the release these pages describe: it carries documentation corrections made after thefabrica-v0.1.2 went out. Nothing that changes how the product behaves landed between the two, which is what makes naming that version honest.