#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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8

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 {
+import { signUnsubscribeToken, verifyUnsubscribeToken } from './unsubscribe-token';
-  LEGACY_VERIFY_UNTIL,
-  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', () => {
+  it('rejects pre-separation legacy tokens — the dual-verify window is gone (#296)', () => {
-    const inWindow = LEGACY_VERIFY_UNTIL - 24 * 60 * 60 * 1000;
+    const now = Date.now();
-    expect(verifyUnsubscribeToken(legacyToken('u1', inWindow - TTL_MS / 2), secret, inWindow)).toBe(
+    // Unexpired on its own terms — rejected because only the subkey verifies.
-      'u1',
+    expect(verifyUnsubscribeToken(legacyToken('u1', now - 1000), secret, now)).toBeNull();
-    );
   });
 
-  it('rejects a legacy token once the dual-verify window has closed', () => {
+  it('verifies freshly minted tokens via the subkey', () => {
-    const afterWindow = LEGACY_VERIFY_UNTIL + 1000;
+    const now = Date.now();
-    // Unexpired on its own terms — rejected purely because the window closed.
+    const token = signUnsubscribeToken('u1', secret, now);
-    const token = legacyToken('u1', afterWindow - 1000);
+    expect(verifyUnsubscribeToken(token, secret, now + 1000)).toBe('u1');
-    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');
   });
 });

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;
 
-/**
+// The pre-#188 dual-verify window (root secret + `digest-unsubscribe.`
- * Dual-verify window (#188, ADR 0020): before the key separation, tokens
+// prefix) was removed EARLY by operator decision at the ADR 0020
- * were HMACed with the root secret over a `digest-unsubscribe.` prefix.
+// acceptance (issue #296): links in mails sent before the key separation
- * Those links live in digest mails that are already sent and stay valid
+// no longer work — recipients use the in-app notification settings.
- * for their full 90-day TTL, so verification accepts the legacy derivation
+// Verification is subkey-only; the regression test pins that the legacy
- * until every pre-separation token has expired. Tokens are only ever
+// derivation can never verify again.
- * 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';
 
 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));
+  if (!matches(provided, signature(body, rootSecret))) return null;
-  const legacy =
-    !current && now < LEGACY_VERIFY_UNTIL && matches(provided, legacySignature(body, rootSecret));
-  if (!current && !legacy) return null;
   try {
     const payload = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) as {
       userId?: string;

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
+- Dual-verify window: REMOVED early by operator decision at the ADR 0020
-  live in already-sent mail (90-day TTL). Verification accepts the legacy
+  acceptance (issue #296, 2026-07-31). Verification is subkey-only;
-  derivation (root key + purpose prefix) until **2026-11-01**
+  unsubscribe links minted before the key separation no longer work —
-  (`LEGACY_VERIFY_UNTIL` in `apps/api/src/notifications/unsubscribe-token.ts`),
+  recipients use the in-app notification settings instead. A regression
-  after which the legacy path goes dead automatically. New tokens are only
+  test pins that the legacy derivation (root key + purpose prefix) can
-  ever signed with the subkey.
+  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.