← back to index

U13 — Faster PIN verify (PBKDF2 100k → 25k + opportunistic rehash)LOCAL

Pivot from the original U13 spec. Original spec ("router.refresh rework") was already shipped by Slice J (2026-05-18, -2966ms / -67%). This U13 attacks the remaining architectural floor: the PIN verify itself. Despite the Slice J memo's "bcrypt 300ms" label, the PIN hash is actually PBKDF2-SHA-256 at 100,000 iterations via Web Crypto — bcrypt is only used for web user passwords. Dropping iterations 100k → 25k is ~4× faster on CF Workers (~225ms shaved) and still exceeds the NIST 800-63B minimum (10k) by 2.5×. PIN hash cost is largely security theater for low-entropy PINs anyway — real defense is online rate-limiting + DB access control.

Summary

Status: 8/8 local · typecheck clean · awaiting Gate 1 approval
Repo: nix-cafe only — no migration, no backend, no schema
Files: 3 modified · ~80 LOC net (5 LOC constant change + ~75 LOC helpers + wiring)
Expected prod win: Slice J's 1437ms floor → ~1210-1240ms (-150-225ms shave). PIN verify cold-isolate: ~250-300ms → ~60-75ms.

What ships

MOD lib/auth/pin.ts — ITERATIONS constant flipped 100_000 → 25_000. New exported needsRehash(stored): boolean helper returns true when stored hash's iter count differs from the current default. hashPin + verifyPin unchanged in shape (already iter-count-aware via the $pbkdf2$<iters>$<salt>$<hash> storage format).
MOD lib/db/pin_identities.ts — new rehashPinIdentity + maybeRehashPinIdentity helpers. Both verifyPinForIdentity (single-row path used by unlockRegisterAction) and verifyPinIdentity (linear-scan path) await the maybeRehash call on successful verify. In a Next request scope, after() queues the rehash off the response critical path; outside a request (tsx probes), falls back to inline-await so migration still happens deterministically.
MOD lib/db/tenant_users.ts — same shape for the manager-override POS PIN. verifyPosPinForUser awaits maybeRehashPosPin on success.

Why this is safe — security analysis

4-digit PIN entropy ≈ 13 bits (10,000 combos). An attacker with the DB can iterate the full keyspace in seconds at any hash cost. Bumping iterations gives diminishing returns past a low floor.
Real defenses are online controls: R8.2 sid rotation + active-cashier cookie → lockout on rate-limit; tenant DB access controls; encryption at rest.
NIST 800-63B minimum: PBKDF2-SHA-256 at 10,000 iterations. 25k is 2.5× over that floor — still in compliance.
OWASP's 600k recommendation is for high-entropy passwords, not PINs. PINs ≠ passwords; hash-cost math is fundamentally different.
No mass invalidation. Existing rows keep verifying at 100k (their stored cost); they organically migrate to 25k via opportunistic rehash on each successful verify. Cashiers see no disruption.

8/8 local checks ✓

✓	`ITERATIONS` constant = 25,000 + U13 rationale comment present
✓	`needsRehash` exported; returns false for fresh hashes, true for legacy 100k / malformed / wrong-algo, false for empty
✓	`hashPin` produces a hash with `iters=25000` in the storage format
✓	`verifyPin` accepts BOTH a manually-built legacy 100k hash AND a new 25k hash; rejects wrong PINs on both
✓	`pin_identities.ts`: `maybeRehashPinIdentity` helper exists; both `verifyPinForIdentity` + `verifyPinIdentity` (linear scan) await it on success
✓	`tenant_users.ts`: `maybeRehashPosPin` helper exists; `verifyPosPinForUser` awaits it on success
✓	DAO round-trip on local lumiere: seed pin_identity with hand-crafted 100k legacy hash → `verifyPinForIdentity` returns row → poll DB → pinHash flipped to `iters=25000` (rehash worked via the inline-fallback path in tsx)
✓	Local timing: 25k verify is ≥1.5× faster than 100k on the test runner's CPU (typical ratio ≈ 3-4× — soft floor at 1.5× to keep harness stable)

Typecheck: npx tsc --noEmit on nix-cafe → 0 errors.

Gate 2 plan

Commit nix-cafe (single-line).
Push to karouna-dev → CF auto-deploy.
test-u13-prod.mjs on lumiere: drive the full PIN unlock flow on lumiere, time PIN-Enter → workspace top-bar visible. Assert ≤1300ms (target floor from 1437ms baseline). Reset a test cashier's PIN to verify the new hash lands at 25k. Verify a legacy 100k cashier (if any exist on prod) unlocks successfully + the post-verify row update flips it to 25k.
Regression sweep 51/51 (phase2-cafe-multishop solo).
Publish prod gallery.

Followups (not in scope)

Lower iterations further (e.g. 10k) — would shave another ~30ms but offers no security gain past the floor. Only worth pursuing if a measurable user-perceived improvement justifies it.
Migrate to argon2id — modern + WASM-on-Workers viable but architecturally heavier (new dep, dual-verify migration path, params tuning). PBKDF2 25k already lands the win without these costs. Argon2 buys little for this threat model.
Web user password bcrypt — kept as-is. Different threat model (high-entropy passwords); bcrypt's cost is right there.