1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
// SPDX-License-Identifier: MIT OR Apache-2.0
// This file is part of Nitr.
// See https://nitrweb.com/ for more information
// Copyright (C) 2024-present Jose Quintana <joseluisq.net>
//! The argon2id password surface: the caps, minting, stored-hash
//! verification with its closed reason set, and the enumeration-closing
//! dummy verify.
use OnceLock;
use Argon2;
use PasswordHash;
use ;
use ;
use rng_err;
/// Upper bound on a password handed to `password_hash`/`password_verify`,
/// in the same spirit as [`MAX_RANDOM_BYTES`]: a bound a real credential
/// never notices and a hostile caller cannot step over.
///
/// Argon2 hashes its input in full, so without a cap any login form is a
/// remote amplifier — one POST body of a few megabytes buys an attacker a
/// worker thread pinned at 19 MiB of scratch memory plus a full pass over
/// those megabytes, and nothing about it looks like an attack. The cap is
/// checked *before* any argon2 work, so an oversized password costs a
/// length comparison.
///
/// 1 KiB is deliberately generous. NIST SP 800-63B asks that verifiers
/// accept passwords of at least 64 characters; a 1024-byte passphrase is
/// an order of magnitude past that and still far below anything worth
/// spending CPU on. (This is *not* a bcrypt-style truncation guard —
/// bcrypt hashes cannot reach this verifier at all, since `$2b$`/`$2y$`
/// fails PHC parsing. Nothing here silently shortens a password.)
///
/// The two sides of the cap answer differently, on purpose.
/// `password_hash` raises — a credential that cannot be stored must fail
/// loudly, at registration, where the user is present to be told.
/// `password_verify` and the dummy verify answer a plain `false, nil` —
/// no stored hash was ever minted from a password this long, so it is
/// simply a credential that cannot match; raising there made every
/// oversized login POST a 500 unless the handler pre-checked the length
/// itself, and a *reason* there would hand strangers a log-spam lever
/// through the `if problem then log` pattern. Scripts that want a
/// pre-check anyway read the cap as `nitr.crypto.max_password_bytes`.
///
/// The value itself lives in [`crate::config`] (always compiled, like
/// the configuration types) so the CLI's stdin cap can share it in every
/// feature configuration; this re-import is the enforcing side.
pub use crateMAX_PASSWORD_BYTES;
/// Ceilings on the argon2 parameters Nitr honors in a *stored* hash.
///
/// A PHC hash is data, and it names the cost of its own verification:
/// `$argon2id$v=19$m=4194304,t=2,p=1$…` asks the verifier for 4 GiB before
/// it can answer "wrong password". The format's own limits are no help —
/// `Params::MAX_M_COST` is `u32::MAX` KiB (4 TiB) and `MAX_T_COST` is
/// `u32::MAX` — and the parameters come from the hash, not from
/// `Argon2::default()`, so whatever is in the row is what runs.
///
/// Nitr's own hashes are m=19456, t=2, p=1. These ceilings are ~13x that
/// memory and 4x that time — well past every OWASP-recommended argon2id
/// configuration (the strongest is m=47104, t=1), so a deployment that
/// migrates to stronger parameters still verifies — while bounding one
/// verification at roughly 256 MiB and a few seconds instead of letting a
/// database row decide. RFC 9106's 2 GiB variant is deliberately outside
/// this: a per-request login check cannot afford it, and refusing it with
/// a reason beats discovering it as an OOM.
const MAX_HASH_MEMORY_KIB: u32 = 256 * 1024;
const MAX_HASH_TIME_COST: u32 = 8;
const MAX_HASH_LANES: u32 = 8;
/// The password-hash and PHC error types have no `std::error::Error` impl
/// here, so their `Display` is carried over manually (they are two types
/// since password-hash 0.6: parsing errors are `phc::Error`, hashing and
/// verification errors are `password_hash::Error`).
/// Every reason `password_verify` can return as its second value. A
/// closed set, like `jwt.verify`'s: a reason outside it means the failure
/// path grew a case nobody wrote down. Re-exported through
/// `nitr_std::fuzzing` so the fuzz target checks the real list rather
/// than a copy of it.
///
/// Every entry means the *stored hash* can never verify anything — the
/// contract of the reason channel is "the row is at fault; log it". An
/// over-cap *submitted* password is deliberately NOT in this set: it
/// answers a plain `false, nil` (see [`MAX_PASSWORD_BYTES`]), because a
/// reason a stranger can trigger at will would turn the natural
/// `if problem then log` handler into a log-spam primitive.
pub const VERIFY_REASONS: & = &;
/// Refuses a password past [`MAX_PASSWORD_BYTES`] before any argon2 work.
///
/// The *hash-side* guard: minting is the one place over-long must be an
/// error, because silently truncating would weaken a credential nobody
/// asked to weaken, and a `nil` would surface as a confusing failure two
/// calls later. Registration handlers that would rather answer 400 than
/// 500 pre-check against `nitr.crypto.max_password_bytes`. The verify
/// side does not use this — see [`MAX_PASSWORD_BYTES`] for why it answers
/// `false` instead.
pub
/// Hashes a password with `Argon2::default()`: argon2id, v19, m=19456 KiB,
/// t=2, p=1, 32-byte output — OWASP's second recommended configuration.
///
/// The single place those parameters are chosen. `nitr hash-password`
/// reaches this through the same Lua function a handler calls, so an
/// operator-generated credential cannot drift from what the server
/// verifies.
pub
/// What a stored-hash verification concluded, as plain `Send` data.
///
/// The boundary type for the blocking offload: the verification runs on
/// the blocking pool, which cannot touch a `Lua`, so it reports an outcome
/// and the caller does the Lua-side logging.
pub
/// The blocking half of `password_verify`: parse the stored hash (which
/// enforces the parameter ceilings) and verify against it.
///
/// Note what this does *not* do. The ceilings cap a single verification;
/// they do not make an at-ceiling row cheap. A stored hash at m=262144,
/// t=8, p=8 is accepted by design, and verifying it can still buy roughly
/// 256 MiB and seconds of a blocking-pool slot — the offload relocates
/// that cost off the async worker, it does not bound it. That is
/// acceptable because the ceiling caps one verification, the state pool
/// caps concurrency at `workers`, and the hashes come from the
/// deployment's own database rather than from an attacker.
pub
/// Parses a stored hash, or names why it can never verify anything.
///
/// The checks the verifier does not do for us, in order:
///
/// * PHC parsing. bcrypt (`$2b$`, `$2y$`), md5crypt (`$1$`) and
/// sha512crypt (`$6$`) all fail here — the exact case an operator hits
/// mid-migration.
/// * A missing salt or output segment. This one matters most: the
/// `PasswordVerifier` blanket impl answers `Error::Password` for a hash
/// with no output, so a truncated column would otherwise be reported as
/// "wrong password" forever.
/// * The algorithm identifier: a PHC string naming scrypt or pbkdf2
/// parses fine and is not something this verifier can check.
/// * The cost parameters, against the ceilings above.
pub
/// Logs an unusable stored hash and returns `false` plus its reason.
///
/// The hash never reaches the log — only its PHC algorithm identifier,
/// which is public metadata (`2b`, `scrypt`, `argon2id`) and the one
/// piece that tells an operator which migration left the row behind.
pub
/// The PHC algorithm identifier of a stored hash, for the log line.
/// Bounded and filtered: the value is whatever the database held, and a
/// log field is not the place to find that out.
pub
/// The decoy hash [`dummy_verify`] compares against.
///
/// Built once per process from OS entropy and never stored anywhere, so
/// no caller can supply the password that matches it: the dummy verify is
/// structurally incapable of returning true.
pub static DECOY_HASH: = new;
/// Spends the same argon2 work a real verification costs, and answers
/// `false`.
///
/// This closes the user-enumeration oracle, which is compositional rather
/// than a flaw in any primitive here. The natural handler —
///
/// ```lua
/// local row = nitr.db:query_row("select ... where email = ?", { email })
/// if not row then return unauthorized() end
/// if not nitr.crypto.password_verify(pass, row.password_hash) then ... end
/// ```
///
/// — answers in microseconds for an address nobody registered and in
/// ~26 ms for one that exists. That thousandfold gap is measurable across
/// a network by an unauthenticated client, and it turns a login form into
/// a query interface over the user list. Calling this on the
/// no-such-user path makes both branches cost one argon2 hash.
///
/// The *submitted* password is hashed, not a fixed placeholder: argon2's
/// cost grows with the input, so hashing anything else would leave a
/// smaller version of the same difference behind.
///
/// The decoy is built lazily, so the first unknown-user request in a
/// process pays for two hashes instead of one. That is one sample of
/// noise, not an oracle — and the alternative, an unconditional 26 ms at
/// every state build, is a real cost for every deployment that never
/// calls this.
pub