Klantportaal token-hashing - server bewaart geen plaintext meer

SHA-256 hash van de portaaltoken in de DB; een gelekte dump levert geen werkende inloggegevens meer op.

Klantportaal-tokens zijn de auth-grens tussen kantoor en klant; klanten loggen er op in om documentaanvragen af te handelen en de gebrande vragenlijst in te vullen. Tot mei 2026 bewaarde Taxmo de token in plaintext (legacy schema). Een gelekte database-dump zou dus direct werkende portaalcredentials bevatten. Per Wave-12 (mei 2026) bewaart Taxmo enkel de SHA-256 hex digest server-side; de plaintext token gaat één keer naar de klant per uitnodigingsmail en wordt daarna door de server vergeten.

Welke kolom is veranderd?

client_portal_tokens.token is gedeprecateerd en mag NULL zijn. Een nieuwe kolom token_hash bevat de SHA-256 hex digest van de oorspronkelijke token. Een partial index idx_client_portal_tokens_hash (WHERE token_hash IS NOT NULL) ondersteunt de lookup. Bij nieuwe uitgiftes schrijft Taxmo NULL in token en de digest in token_hash; bij legacy rijen worden token + token_hash beide gevuld bij de eerste hit (lazy backfill) en token gewist.

Hoe werkt de lookup?

De inkomende token wordt server-side gehasht (crypto.createHash('sha256').update(token).digest('hex')). Eerst hash-first lookup tegen idx_client_portal_tokens_hash. Geen match? Fallback naar plaintext-match op client_portal_tokens.token WITH client_portal_tokens.token_hash IS NULL - daarna wordt het gevonden plaintext-record gemigreerd (token_hash gevuld, token gewist) zodat het bij de volgende lookup direct hash-first matcht. Na 30 dagen kan een one-shot script de overgebleven plaintext-rijen NULL zetten en de fallback verwijderen.

Welke bewaarklasse heeft de token?

256-bit random (crypto.randomBytes(32).toString('hex') - 64 hex chars). Geen salt nodig: een 256-bit random heeft genoeg entropie tegen brute-force. SHA-256 zonder salt is consistent met onze bestaande mobiele-token-hashing (auth.ts:hashToken). De token zelf wordt teruggegeven aan de aanroeper (het kantoor of de uitnodigingsmail) en daarna door de server vergeten. Verlies van de token-string betekent dat de klant een nieuwe moet aanvragen - er is geen recovery-pad op basis van de hash.

Wat ziet een aanvaller in een gelekte dump?

Alleen de SHA-256 digest. Tokens zijn 256-bit random; offline brute-force is computationeel onhaalbaar (2^256). Een aanvaller kan dus de portaaltoken niet reconstrueren uit de hash. Vergelijk met de oude situatie waarin een gelekte dump direct werkende portaalcredentials bevatte - dat is de hele reden voor de migratie.

Veelgestelde vragen

Waarom SHA-256 en niet bcrypt voor portaaltokens?
Bcrypt is ontworpen voor low-entropy passwords (om brute-force te vertragen). Portaaltokens zijn high-entropy random (256 bit) - een snelle hash zoals SHA-256 is voldoende en de juiste keuze. Bcrypt op random tokens voegt geen security toe en verhoogt CPU per lookup.
Hoe lang duurt de migratie van bestaande tokens?
Op de eerste lookup van een legacy token wordt deze gemigreerd (token_hash gevuld + token gewist). Een eenmalige bulk-backfill (encode(digest(token,'sha256'),'hex')) draait bij elke deploy via ensureSchema (pgcrypto extension vereist). Praktisch: binnen 30 dagen na deploy is elke legacy token gemigreerd.
Welk endpoint genereert een nieuwe token?
POST /api/kantoor/clients/:clientId/portal-token - gegated door requireKantoorWrite. Oude tokens worden eerst gewist via DELETE FROM client_portal_tokens WHERE office_client_id = :id, dan wordt een 64-char hex random gegenereerd en de SHA-256 hash bewaard. Het audit_log krijgt een tokenPrefix-veld (eerste 8 chars) voor forensisch ondersteuning zonder de plaintext te onthullen.
Wat als de pgcrypto extensie niet geinstalleerd is?
De bulk-backfill wordt overgeslagen (try/catch in ensureSchema) en de lazy migratie tijdens lookups dekt de overige rijen. Geen impact op portaal-toegang; alleen de migratie verloopt iets trager.