Files
HealthLog/src/lib/clinician-share/passphrase.ts
T
Marc-André Bombeck 1aeb6f7957 Mint a passphrase second factor on share-link create
Every new share link now carries a high-entropy passphrase (80-bit,
Crockford-base32, grouped XXXX-XXXX-XXXX-XXXX). The create response
returns the raw passphrase, the share URL, and a QR deep link EXACTLY
ONCE alongside the token; the server stores only the passphrase's HMAC
hash (the same key as the token hash). The QR deep link carries the
passphrase in the URL fragment (#k=) so it never reaches a server log,
referrer, or access record.

Add the passphrase generator, normaliser, and constant-time verifier;
the short-lived token-scoped unlock-cookie mint/verify; a gate-state
resolver that reports live + passphrase status without bumping access
counters; and the unlock request schema.
2026-06-19 22:03:36 +02:00

109 lines
4.1 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* v1.18.7 — clinician share-link passphrase second factor.
*
* A share URL is now possession AND knowledge: a leaked `/c/<token>` link
* without the passphrase cannot open the record. Every new link gets a
* high-entropy passphrase minted here, returned to the owner EXACTLY ONCE,
* and stored only as its HMAC-SHA256 hash (the same `hashToken` scheme as the
* token itself, keyed by `API_TOKEN_HMAC_KEY`). There is no recovery path.
*
* Shape: 16 Crockford-base32 characters grouped `XXXX-XXXX-XXXX-XXXX`. The raw
* 16 chars carry 80 bits of entropy; we draw them from 10 random bytes (80
* bits) so the human-typeable form is the full secret with no truncation. The
* QR payload (built by the create route) carries this in the URL FRAGMENT so it
* never reaches a server log, referrer, or access record.
*/
import { randomBytes, timingSafeEqual } from "node:crypto";
import { hashToken } from "@/lib/auth/hmac";
/**
* Crockford base32 alphabet (no I/L/O/U — removes the characters most often
* misread when typed by hand). 32 symbols → 5 bits each.
*/
const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
/** Group size for the human-typeable form (`XXXX-XXXX-XXXX-XXXX`). */
const GROUP = 4;
/** Total characters in a raw passphrase (16 × 5 bits = 80 bits). */
const LENGTH = 16;
/** The fragment key the QR / deep-link uses: `#k=<passphrase>`. */
export const PASSPHRASE_FRAGMENT_KEY = "k";
/**
* The canonical regex a submitted passphrase must match once normalised
* (uppercased, separators stripped): 16 Crockford-base32 characters.
*/
export const PASSPHRASE_PATTERN = new RegExp(`^[${ALPHABET}]{${LENGTH}}$`);
/**
* Generate a fresh passphrase in the grouped human-typeable form
* (`XXXX-XXXX-XXXX-XXXX`). Drawn from CSPRNG bytes via rejection-free
* masking — each character maps a 5-bit slice of the random stream onto the
* 32-symbol alphabet, so the distribution is uniform.
*/
export function generatePassphrase(): string {
// 16 chars × 5 bits = 80 bits → 10 bytes of entropy.
const bytes = randomBytes(10);
let bits = 0;
let value = 0;
const chars: string[] = [];
for (let i = 0; i < bytes.length && chars.length < LENGTH; i++) {
value = (value << 8) | bytes[i];
bits += 8;
while (bits >= 5 && chars.length < LENGTH) {
bits -= 5;
chars.push(ALPHABET[(value >>> bits) & 0x1f]);
}
}
const groups: string[] = [];
for (let i = 0; i < chars.length; i += GROUP) {
groups.push(chars.slice(i, i + GROUP).join(""));
}
return groups.join("-");
}
/**
* Normalise a passphrase a human (or a QR fragment) submitted: strip every
* separator / whitespace and uppercase. Lowercase `l`→`L` style confusions are
* left to the alphabet (which already excludes I/L/O/U), so a value that does
* not normalise to the canonical pattern is simply rejected by the caller.
* Returns the bare 16-char form, or `null` when it does not match the pattern.
*/
export function normalisePassphrase(raw: string): string | null {
const stripped = raw.replace(/[\s-]+/g, "").toUpperCase();
return PASSPHRASE_PATTERN.test(stripped) ? stripped : null;
}
/**
* Hash a passphrase for storage / comparison. Normalises first so the grouped
* and bare forms collide to one hash; throws (via `normalisePassphrase` →
* caller) only when the input is malformed. Returns the lowercase hex HMAC.
*/
export function hashPassphrase(normalised: string): string {
return hashToken(normalised);
}
/**
* Constant-time check of a submitted passphrase against a stored hash. Returns
* false for a malformed submission, a null stored hash, or any mismatch — and
* never short-circuits on length so timing leaks nothing about the secret.
*/
export function verifyPassphrase(
submitted: string,
storedHash: string | null,
): boolean {
if (!storedHash) return false;
const normalised = normalisePassphrase(submitted);
if (!normalised) return false;
const candidate = Buffer.from(hashPassphrase(normalised), "hex");
const expected = Buffer.from(storedHash, "hex");
if (candidate.length !== expected.length) return false;
try {
return timingSafeEqual(candidate, expected);
} catch {
return false;
}
}