From 1f56f341130239ac48b9d7168bab9e115f57c75d Mon Sep 17 00:00:00 2001 From: Claude Fable 5 Date: Fri, 31 Jul 2026 23:03:03 +0200 Subject: [PATCH] #296: remove the unsubscribe-token dual-verify window early Operator decision at the ADR 0020 acceptance: verification is subkey-only now instead of waiting for the stated 2026-11-01 expiry. Links in digest mails sent before the #188 key separation stop working; recipients use the in-app notification settings. A regression test pins that the legacy derivation (root key + purpose prefix) can never verify again; security.md records the removal. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8 --- .../notifications/unsubscribe-token.test.ts | 30 ++++++------------- .../src/notifications/unsubscribe-token.ts | 26 +++++----------- docs/architecture/security.md | 12 ++++---- 3 files changed, 22 insertions(+), 46 deletions(-) diff --git a/apps/api/src/notifications/unsubscribe-token.test.ts b/apps/api/src/notifications/unsubscribe-token.test.ts index 56ebf14..80f2900 100644 --- a/apps/api/src/notifications/unsubscribe-token.test.ts +++ b/apps/api/src/notifications/unsubscribe-token.test.ts @@ -3,11 +3,7 @@ import { createHmac } from 'node:crypto'; import { deriveTokenKey } from '@dorfteich/shared/token-crypto'; import { describe, expect, it } from 'vitest'; -import { - LEGACY_VERIFY_UNTIL, - signUnsubscribeToken, - verifyUnsubscribeToken, -} from './unsubscribe-token'; +import { signUnsubscribeToken, verifyUnsubscribeToken } from './unsubscribe-token'; const secret = 'test-secret-at-least-16-chars-long'; const TTL_MS = 90 * 24 * 60 * 60 * 1000; @@ -50,23 +46,15 @@ describe('unsubscribe token', () => { expect(verifyUnsubscribeToken(`${body}.${sig}`, secret)).toBeNull(); }); - it('accepts a pre-separation legacy token inside the dual-verify window', () => { - const inWindow = LEGACY_VERIFY_UNTIL - 24 * 60 * 60 * 1000; - expect(verifyUnsubscribeToken(legacyToken('u1', inWindow - TTL_MS / 2), secret, inWindow)).toBe( - 'u1', - ); + it('rejects pre-separation legacy tokens — the dual-verify window is gone (#296)', () => { + const now = Date.now(); + // Unexpired on its own terms — rejected because only the subkey verifies. + expect(verifyUnsubscribeToken(legacyToken('u1', now - 1000), secret, now)).toBeNull(); }); - it('rejects a legacy token once the dual-verify window has closed', () => { - const afterWindow = LEGACY_VERIFY_UNTIL + 1000; - // Unexpired on its own terms — rejected purely because the window closed. - const token = legacyToken('u1', afterWindow - 1000); - expect(verifyUnsubscribeToken(token, secret, afterWindow)).toBeNull(); - }); - - it('verifies freshly minted tokens via the subkey, independent of the window', () => { - const afterWindow = LEGACY_VERIFY_UNTIL + 24 * 60 * 60 * 1000; - const token = signUnsubscribeToken('u1', secret, afterWindow); - expect(verifyUnsubscribeToken(token, secret, afterWindow + 1000)).toBe('u1'); + it('verifies freshly minted tokens via the subkey', () => { + const now = Date.now(); + const token = signUnsubscribeToken('u1', secret, now); + expect(verifyUnsubscribeToken(token, secret, now + 1000)).toBe('u1'); }); }); diff --git a/apps/api/src/notifications/unsubscribe-token.ts b/apps/api/src/notifications/unsubscribe-token.ts index 87d18ea..c9e09b2 100644 --- a/apps/api/src/notifications/unsubscribe-token.ts +++ b/apps/api/src/notifications/unsubscribe-token.ts @@ -13,26 +13,17 @@ import { deriveTokenKey } from '@dorfteich/shared/token-crypto'; const TTL_SECONDS = 90 * 24 * 60 * 60; -/** - * Dual-verify window (#188, ADR 0020): before the key separation, tokens - * were HMACed with the root secret over a `digest-unsubscribe.` prefix. - * Those links live in digest mails that are already sent and stay valid - * for their full 90-day TTL, so verification accepts the legacy derivation - * until every pre-separation token has expired. Tokens are only ever - * SIGNED with the new subkey; the legacy path is verify-only and goes dead - * automatically on the date below (last possible legacy expiry, rounded up). - */ -export const LEGACY_VERIFY_UNTIL = Date.parse('2026-11-01T00:00:00Z'); -const LEGACY_PURPOSE = 'digest-unsubscribe'; +// The pre-#188 dual-verify window (root secret + `digest-unsubscribe.` +// prefix) was removed EARLY by operator decision at the ADR 0020 +// acceptance (issue #296): links in mails sent before the key separation +// no longer work — recipients use the in-app notification settings. +// Verification is subkey-only; the regression test pins that the legacy +// derivation can never verify again. function signature(body: string, rootSecret: string): Buffer { return createHmac('sha256', deriveTokenKey(rootSecret, 'unsubscribe')).update(body).digest(); } -function legacySignature(body: string, rootSecret: string): Buffer { - return createHmac('sha256', rootSecret).update(`${LEGACY_PURPOSE}.${body}`).digest(); -} - export function signUnsubscribeToken(userId: string, rootSecret: string, now = Date.now()): string { const body = Buffer.from( JSON.stringify({ userId, exp: Math.floor(now / 1000) + TTL_SECONDS }), @@ -59,10 +50,7 @@ export function verifyUnsubscribeToken( } catch { return null; } - const current = matches(provided, signature(body, rootSecret)); - const legacy = - !current && now < LEGACY_VERIFY_UNTIL && matches(provided, legacySignature(body, rootSecret)); - if (!current && !legacy) return null; + if (!matches(provided, signature(body, rootSecret))) return null; try { const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as { userId?: string; diff --git a/docs/architecture/security.md b/docs/architecture/security.md index ec3e128..ff2033d 100644 --- a/docs/architecture/security.md +++ b/docs/architecture/security.md @@ -221,12 +221,12 @@ job (out of scope, below). explicit allowlist), `unsubscribe` for the digest unsubscribe links. No code path signs with the root key directly, so a compromise of one purpose's tokens is not transferable to the other. -- Dual-verify window: unsubscribe links minted before the key separation - live in already-sent mail (90-day TTL). Verification accepts the legacy - derivation (root key + purpose prefix) until **2026-11-01** - (`LEGACY_VERIFY_UNTIL` in `apps/api/src/notifications/unsubscribe-token.ts`), - after which the legacy path goes dead automatically. New tokens are only - ever signed with the subkey. +- Dual-verify window: REMOVED early by operator decision at the ADR 0020 + acceptance (issue #296, 2026-07-31). Verification is subkey-only; + unsubscribe links minted before the key separation no longer work — + recipients use the in-app notification settings instead. A regression + test pins that the legacy derivation (root key + purpose prefix) can + never verify again. - Key rotation: rotating the root key rotates every derived subkey at once (desired: one secret to rotate) via env change plus rolling restart; procedure documented in `operations.md` runbooks. -- 2.45.2