antcolony

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