#188: purpose-bound token keys via HKDF + jose #239

Merged

stwaidele merged 1 commits from feat/188-token-key-separation into main 2026-07-30 08:47:21 +02:00

Conversation 0 Commits 1 Files Changed 18 +372 -125

fable-5 commented 2026-07-30 06:41:32 +02:00

Collaborator

Copy Link

STACKED on PR #238 (contains its commit; merge #238 first, then this fast-forwards).

Implements ADR 0020:

• COLLAB_TOKEN_SECRET becomes a root key; each purpose derives a 32-byte HKDF-SHA-256 subkey (deriveTokenKey). No code path signs with the root key - proven by a test.
• Collaboration tokens signed/verified by jose, HS256 as an explicit allowlist (algorithm-allowlist test, RS256 and alg:none rejected). Sign/verify turn async at their three call sites.
• Unsubscribe tokens: structural subkey replaces the purpose-prefix string; documented dual-verify window until 2026-11-01 (LEGACY_VERIFY_UNTIL) covering the 90-day TTL of links in already-sent mail, with tests for both sides of the window.
• Cross-runtime test round-trips tokens between the built CJS and ESM dist artefacts in child processes - the property that justified the homegrown JWT (jose v6 reaches CJS via require(esm); Node 22.15 images).
• Docs: key hierarchy in security.md, root-key role in .env.example. One new dependency (jose, dependency-free).

Tested: shared 185 (incl. 12 collab-token + 3 cross-runtime), collab full suite 40/40 vs fresh DB, api full suite 431 green vs fresh DB (incl. 7 new unsubscribe tests), typecheck + lint green.

Refs #188 (close manually after green CI + merge).

Generated with Claude Code (Claude Fable 5)

STACKED on PR #238 (contains its commit; merge #238 first, then this fast-forwards). Implements ADR 0020: - COLLAB_TOKEN_SECRET becomes a root key; each purpose derives a 32-byte HKDF-SHA-256 subkey (deriveTokenKey). No code path signs with the root key - proven by a test. - Collaboration tokens signed/verified by jose, HS256 as an explicit allowlist (algorithm-allowlist test, RS256 and alg:none rejected). Sign/verify turn async at their three call sites. - Unsubscribe tokens: structural subkey replaces the purpose-prefix string; documented dual-verify window until 2026-11-01 (LEGACY_VERIFY_UNTIL) covering the 90-day TTL of links in already-sent mail, with tests for both sides of the window. - Cross-runtime test round-trips tokens between the built CJS and ESM dist artefacts in child processes - the property that justified the homegrown JWT (jose v6 reaches CJS via require(esm); Node 22.15 images). - Docs: key hierarchy in security.md, root-key role in .env.example. One new dependency (jose, dependency-free). Tested: shared 185 (incl. 12 collab-token + 3 cross-runtime), collab full suite 40/40 vs fresh DB, api full suite 431 green vs fresh DB (incl. 7 new unsubscribe tests), typecheck + lint green. Refs #188 (close manually after green CI + merge). Generated with Claude Code (Claude Fable 5)

fable-5 added 2 commits 2026-07-30 06:41:32 +02:00

#226: add the §52 VSA delimitation statement ... 3e377aaa57

Reviewer-facing document derived from ADR 0019: per base function
(encryption, media protection, network termination, authentication,
integrity) what the application does, what it deliberately does not,
and which party provides it — every claim traceable to code via the
ist-aufnahme. Includes the operator-duty handover (with the IndexedDB
endpoint copy named explicitly, I-25) and the delta list mapping every
divergence from the target state to its closing issue.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168Ph5uBmHm8X28CSVpbpnJ

#188: purpose-bound token keys via HKDF, jose replaces the homegrown JWT ... 3d1f4fda53

COLLAB_TOKEN_SECRET becomes a root key: every purpose derives its own
HKDF-SHA-256 subkey (deriveTokenKey), and no code path signs with the
root key directly. Collaboration tokens are signed and verified by jose
with HS256 as an explicit allowlist; the sign/verify API turns async at
its three call sites. Unsubscribe tokens move from a purpose-prefix
string to the structural subkey, with a documented dual-verify window
(legacy derivation accepted until 2026-11-01, covering the 90-day TTL
of links in already-sent mail).

The cross-runtime property that justified the homegrown implementation
is now proven by a test: the built CJS and ESM dist artefacts round-trip
tokens in both directions in child processes (jose v6 reaches CJS via
Node's require(esm), pinned Node 22 images). Negative tests cover
cross-purpose subkeys, root-key-signed tokens, alg:none and RS256.

Refs #188 (ADR 0020)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168Ph5uBmHm8X28CSVpbpnJ

stwaidele merged commit 3d1f4fda53 into main 2026-07-30 08:47:21 +02:00

fable-5 referenced this pull request 2026-07-30 09:05:36 +02:00

[VS-NfD] Separate token keys with HKDF and replace the homegrown JWT with `jose` #188

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

area:auth

  

area:docs

  

area:export

  

area:ops

  

area:storage

  

area:supply-chain

  

auth

Authentication, permissions, quotas

  

backend

API server (apps/api)

  

blocked

Blocked on external dependency/infrastructure

  

collab

Collaboration server (apps/collab)

  

deployment

Docker, CI/CD, hosting

  

docs

Documentation

  

effort:L

  

effort:M

  

effort:S

  

frontend

SPA (apps/web)

  

plugins

Plugin system and SDK

  

qa

Tests, fixtures, e2e

  

vs-nfd

  

vs-nfd:blocker

No Label

area:auth

area:docs

area:export

area:ops

area:storage

area:supply-chain

auth

backend

blocked

collab

deployment

docs

effort:L

effort:M

effort:S

frontend

plugins

qa

vs-nfd

vs-nfd:blocker

Milestone

Clear milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

No Assignees

1 Participants

Notifications

Subscribe

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: stwaidele/dorfteich#239

No description provided.