notes

9.4 KB

1. // hl:crypto — passwords first. JS transpiler twin of plugins/crypto/crypto.zig.
2. //
3. // Parity contract with the native plugin:
4. // hash(password, options) → a PHC string, freshly salted every call
5. // verify(password, stored) → boolean, timing-safe comparison
6. // parsePhc(stored) → the stored string described, or null
7. // kdf() → the algorithm THIS engine hashes with
8. // sha256(data) → 64 lowercase hex characters
9. // randomBytes(n, encoding) → "hex" (default) or "base64"
10. // toBase64(data) → base64 of a String's UTF-8 or of a Bytes (ticket #90)
11. // fromBase64(text) → a Bytes, or null when text is not base64
12. //
13. // The PHC STRING FORMAT, the strictness of the parser, the cost knob and its cap,
14. // and the salt/output lengths are identical on both engines — a `$scrypt$` string
15. // written by either one verifies on the other, byte for byte, because RFC 7914 is
16. // RFC 7914 whether it is reached through Node's crypto or through libcrypto's
17. // EVP_PBE_scrypt.
18. //
19. // THE ONE DIFFERENCE, stated rather than hidden: Node has no argon2 of any kind,
20. // so this engine hashes with scrypt where the native plugin prefers argon2id on a
21. // host whose libcrypto has it. `parsePhc` still reads argon2id strings here — the
22. // format is just a string — but `verify` on one THROWS instead of answering
23. // `false`, because "I cannot compute this algorithm" is not "wrong password".
25. import { createHash, randomBytes as nodeRandomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
26. // Bytes are the runtime's: this file is copied to hl-modules/crypto.js, beside hl-runtime.js.
27. import { hlMakeBytes, hlIsBytes } from '../hl-runtime.js';
29. // The cost knob: base-2 log of the working memory in KiB. Same numbers as the
30. // native plugin — 15 is 32 MiB (scrypt N = 2^15, r = 8, p = 1 is 128·N·r bytes).
31. const COST_DEFAULT = 15;
32. const COST_MIN = 10; // 1 MiB
33. const COST_MAX = 17; // 128 MiB — see the note in crypto.zig; the two engines
34. // must cap at the same number or a string one of them
35. // wrote would be out of range for the other.
37. const SALT_LEN = 16;
38. const HASH_LEN = 32;
39. // The floor a stored string must clear to be READ at all — see decodePhc().
40. const MIN_SALT_LEN = 8;
41. const MIN_HASH_LEN = 16;
42. const SCRYPT_R = 8;
43. const SCRYPT_P = 1;
44. // Node refuses a derivation whose 128·N·r exceeds maxmem, default 32 MiB — which
45. // the DEFAULT cost sits exactly on. Raised past the cost cap so the cap is the
46. // only thing that limits anything.
47. const SCRYPT_MAXMEM = 2 * 1024 * 1024 * 1024;
49. const B64_CHARS = /^[A-Za-z0-9+/]+$/;
51. function b64(buf) {
52. return buf.toString('base64').replace(/=+$/, '');
53. }
55. // Deliberately strict, to match the Zig decoder, and BOTH halves of that are
56. // load-bearing:
57. // • Node's base64 reader silently skips characters outside the alphabet, so a
58. // string with junk in it would parse rather than be refused;
59. // • it also drops NON-CANONICAL TRAILING BITS. A 32-byte hash is 43 base64
60. // characters, whose last character carries only two significant bits — so
61. // "…L8E" and "…L8F" decode to the SAME 32 bytes and, before this check,
62. // editing the last character of a stored hash did not change what it
63. // verified against. Zig's decoder refuses that outright; re-encoding is how
64. // this engine reaches the same answer.
65. function unb64(text) {
66. if (!B64_CHARS.test(text)) return null;
67. const buf = Buffer.from(text, 'base64');
68. if (buf.length === 0) return null;
69. if (b64(buf) !== text) return null;
70. return buf;
71. }
73. function paramValue(field, key) {
74. for (const pair of field.split(',')) {
75. const eq = pair.indexOf('=');
76. if (eq < 0) continue;
77. if (pair.slice(0, eq) !== key) continue;
78. const raw = pair.slice(eq + 1);
79. if (!/^[0-9]+$/.test(raw)) return null;
80. const n = Number(raw);
81. return Number.isSafeInteger(n) ? n : null;
82. }
83. return null;
84. }
86. /** Strict PHC decode. Any deviation at all is null — that is what makes a
87. * tampered string fail rather than half-parse into something comparable.
88. *
89. * Including the LENGTH FLOOR: a KDF derives as many bytes as it is asked for,
90. * so a stored string whose hash field had been cut down to eight base64
91. * characters derived six bytes and compared six bytes — and six bytes of a
92. * correct derivation match. Truncating the stored value was a way to make a
93. * wrong password verify until this check existed (both engines had it). */
94. function decodePhc(stored) {
95. if (typeof stored !== 'string' || stored.length < 2 || stored[0] !== '$') return null;
96. const parts = stored.slice(1).split('$');
97. if (parts.length > 8) return null;
99. if (parts[0] === 'argon2id') {
100. if (parts.length !== 5) return null;
101. if (!parts[1].startsWith('v=') || !/^[0-9]+$/.test(parts[1].slice(2))) return null;
102. const version = Number(parts[1].slice(2));
103. const m = paramValue(parts[2], 'm');
104. const t = paramValue(parts[2], 't');
105. const p = paramValue(parts[2], 'p');
106. if (m === null || t === null || p === null) return null;
107. const salt = unb64(parts[3]);
108. const hash = unb64(parts[4]);
109. if (!salt || !hash) return null;
110. if (salt.length < MIN_SALT_LEN || hash.length < MIN_HASH_LEN) return null;
111. return { kdf: 'argon2id', version, m, t, p, salt, hash };
112. }
114. if (parts[0] === 'scrypt') {
115. if (parts.length !== 4) return null;
116. const ln = paramValue(parts[1], 'ln');
117. const r = paramValue(parts[1], 'r');
118. const p = paramValue(parts[1], 'p');
119. if (ln === null || r === null || p === null) return null;
120. const salt = unb64(parts[2]);
121. const hash = unb64(parts[3]);
122. if (!salt || !hash) return null;
123. if (salt.length < MIN_SALT_LEN || hash.length < MIN_HASH_LEN) return null;
124. return { kdf: 'scrypt', version: null, ln, r, p, salt, hash };
125. }
127. return null;
128. }
130. function clampCost(value) {
131. if (typeof value !== 'number' || Number.isNaN(value)) return COST_DEFAULT;
132. return Math.trunc(Math.max(COST_MIN, Math.min(COST_MAX, value)));
133. }
135. export function hash(password, options) {
136. if (typeof password !== 'string') throw new Error('hl:crypto hash() expects a string password');
137. const opts = options && typeof options === 'object' ? options : {};
138. const cost = clampCost(opts.cost);
139. const want = typeof opts.kdf === 'string' ? opts.kdf : 'scrypt';
140. if (want === 'argon2id') {
141. throw new Error('hl:crypto hash(): this engine has no argon2id — Node ships no argon2');
142. }
143. if (want !== 'scrypt') {
144. throw new Error('hl:crypto hash(): unknown kdf — expected "argon2id" or "scrypt"');
145. }
146. const salt = nodeRandomBytes(SALT_LEN);
147. const derived = scryptSync(password, salt, HASH_LEN, {
148. N: 2 ** cost, r: SCRYPT_R, p: SCRYPT_P, maxmem: SCRYPT_MAXMEM,
149. });
150. return `$scrypt$ln=${cost},r=${SCRYPT_R},p=${SCRYPT_P}$${b64(salt)}$${b64(derived)}`;
151. }
153. export function verify(password, stored) {
154. if (typeof password !== 'string') return false;
155. const phc = decodePhc(stored);
156. if (phc === null) return false;
157. if (phc.hash.length === 0 || phc.hash.length > 64) return false;
159. if (phc.kdf === 'argon2id') {
160. throw new Error('hl:crypto verify(): stored password is argon2id and this engine has none — Node ships no argon2');
161. }
162. if (phc.ln === 0 || phc.ln > 30 || phc.r === 0 || phc.p === 0) return false;
164. let computed;
165. try {
166. computed = scryptSync(password, phc.salt, phc.hash.length, {
167. N: 2 ** phc.ln, r: phc.r, p: phc.p, maxmem: SCRYPT_MAXMEM,
168. });
169. } catch {
170. // A stored string asking for more memory than this host will give is not a
171. // wrong password, but it is also not something to crash a login over.
172. return false;
173. }
174. return timingSafeEqual(computed, phc.hash);
175. }
177. export function parsePhc(stored) {
178. const phc = decodePhc(stored);
179. if (phc === null) return null;
180. const params = phc.kdf === 'argon2id'
181. ? { m: phc.m, t: phc.t, p: phc.p }
182. : { ln: phc.ln, r: phc.r, p: phc.p };
183. return {
184. kdf: phc.kdf,
185. version: phc.version,
186. params,
187. saltLen: phc.salt.length,
188. hashLen: phc.hash.length,
189. };
190. }
192. export function kdf() {
193. return 'scrypt';
194. }
196. export function sha256(data) {
197. if (typeof data !== 'string') throw new Error('hl:crypto sha256() expects a string');
198. return createHash('sha256').update(data, 'utf8').digest('hex');
199. }
201. export function randomBytes(n, encoding) {
202. if (typeof n !== 'number' || !(n >= 1) || n > 1024) {
203. throw new Error('hl:crypto randomBytes(): count must be between 1 and 1024');
204. }
205. const buf = nodeRandomBytes(Math.trunc(n));
206. const enc = typeof encoding === 'string' ? encoding : 'hex';
207. if (enc === 'hex') return buf.toString('hex');
208. if (enc === 'base64') return buf.toString('base64');
209. throw new Error('hl:crypto randomBytes(): encoding must be "hex" or "base64"');
210. }
212. // Base64, standard alphabet (ticket #90) — the rules are crypto.zig's: encoding
213. // pads; decoding takes padded or unpadded text and answers null for anything an
214. // encoder would not have written. Node's own decoder skips what it does not
215. // understand, so the text is checked first and the result re-encoded after.
216. export function toBase64(data) {
217. if (hlIsBytes(data)) return Buffer.from(data._d).toString('base64');
218. if (typeof data !== 'string') throw new Error('hl:crypto toBase64() expects a String or a Bytes');
219. return Buffer.from(data, 'utf8').toString('base64');
220. }
222. export function fromBase64(text) {
223. if (typeof text !== 'string') throw new Error('hl:crypto fromBase64() expects a String');
224. let core = text;
225. if (core.length % 4 === 0) core = core.replace(/={1,2}$/, '');
226. if (core.length % 4 === 1 || !/^[A-Za-z0-9+/]*$/.test(core)) return null;
227. const buf = Buffer.from(core, 'base64');
228. if (buf.toString('base64').replace(/=+$/, '') !== core) return null;
229. return hlMakeBytes(new Uint8Array(buf));
230. }