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
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
//! Token-based enrollment.
//!
//! Replaces "copy the certificate bundle to the client machine by hand" with a one-time,
//! time-limited token the operator reads out (or pastes) to the person enrolling a new
//! viewer -- or, on the coordinator's WORKER enrollment listener, a new joining worker.
//!
//! # Two listeners, one per role
//!
//! `serve` runs one enrollment listener per client role: the VIEWER one next to the
//! viewer port (default 7879) and the WORKER one next to the worker port (default
//! 7881). Each has its own [`EnrollRegistry`] (so a token only ever claims on the
//! listener that issued it), mints certificates of its own role only (a worker's
//! Common Name is `worker:<name>`, see `crate::pki::role`) and appends a claimed
//! fingerprint to its own role's allowlist. No wire change: `cert issue-token --role
//! worker` sends its `Issue` name as `worker:<name>`, and each listener refuses an
//! `Issue` for the other role (a viewer listener refuses a `worker:` name, a worker
//! listener refuses a name without it) rather than silently minting the wrong kind.
//!
//! # Why this needs its own listener, not the render port
//!
//! The render listener (`crate::serve`) requires mutual TLS: every connection must
//! already present a certificate signed by this worker's CA. An enrolling client has no
//! such certificate yet, so it structurally cannot use that listener. Enrollment gets
//! its own listener and TLS config that never requires a client certificate, whose
//! connection handler ([`handle_enroll_connection`]) never calls into
//! [`crate::stream_emit`] or [`crate::serve::handle_connection_with_gpu`] -- a claim
//! connection cannot reach `RenderRequest` handling because the code path doesn't exist
//! on this listener, not merely because it's rejected at runtime.
//!
//! # The token
//!
//! See `indicatrix_net::token`'s doc comment for the wire encoding. Three security
//! properties, all enforced here:
//!
//! 1. **The secret is a fresh 256-bit CSPRNG value, never the certificate's
//! fingerprint** -- the fingerprint is public (it crosses the wire on every TLS
//! handshake and is what `allowlist.txt` stores), so a bearer secret must never
//! double as it.
//! 2. **The server stores only [`sha2::Sha256`] of the secret**
//! ([`PendingEnrollment::secret_hash`]), compared in [`EnrollRegistry::claim`] via
//! [`subtle::ConstantTimeEq`], not `==`.
//! 3. **The token commits to the server's identity**: it carries the worker's CA
//! fingerprint alongside the secret, and `indicatrix_net::enroll::claim` verifies the
//! enrollment listener's certificate chains to that exact CA *before* sending the
//! secret (`PinnedCaVerifier`) -- otherwise a MITM could impersonate the worker and
//! walk away with a validly issued client certificate.
//!
//! # Lifecycle
//!
//! - Single use: [`EnrollRegistry::claim`] removes the entry before returning it.
//! - [`TOKEN_TTL_SECS`] (180s), checked server-side against [`Instant::now`] on every
//! claim -- never a client-side courtesy.
//! - The issued bundle lives only in [`EnrollRegistry`]'s in-memory `Vec`
//! ([`crate::pki::issue_client_in_memory`]), never written to disk by this process; it
//! reaches disk only on the claiming machine via `crate::enroll_client::claim`.
//! - The claimed fingerprint is appended to `allowlist.txt` only inside
//! [`handle_enroll_connection`]'s `Claim` arm, strictly after
//! [`EnrollRegistry::claim`] returns a match, never at issue time.
//! - On claim, expiry, or registry drop, pending key material is explicitly zeroized:
//! [`PendingEnrollment`]/[`EnrollBundle`] hold sensitive fields as
//! [`zeroize::Zeroizing`], so `Drop` overwrites the bytes before the allocator frees
//! them. Does not protect against the process being killed abruptly (`Drop` never
//! runs).
//! - A `serve` restart starts a brand new, empty [`EnrollRegistry`] -- fail-closed and
//! intentional; an operator re-issues a token.
//!
//! # Where issuing happens
//!
//! Issuing and claiming must happen inside the *same* running `serve` process, since the
//! bundle lives only in memory from the moment it's minted. `cert issue-token`
//! (`crate::enroll_client::run_issue_token`) is a small TLS client that connects to this
//! listener using the operator's own `ca.pem` for normal server verification.
//!
//! Issuing is restricted twice. The peer must be on loopback, checked against the actual
//! accepted `TcpStream::peer_addr()` (the same listener also accepts non-loopback claim
//! connections under `--allow-remote`). And the request must carry the operator secret,
//! `<pki_dir>/issue.secret`: 32 random bytes, hex, created with owner-only permissions the
//! first time `serve` starts an enrollment listener and compared in constant time. A
//! loopback source alone is not authority -- any local user, and any port forward onto the
//! loopback listener, appears as loopback -- whereas reading `issue.secret` needs the same
//! access as reading `ca.key`, which already lets an operator mint certificates directly.
//! A registry built without a secret refuses every `Issue`.
use cratepki;
use ;
use ;
use Zeroizing;
/// The per-listener pending-enrollment table ([`EnrollRegistry`]) and why issuing one
/// failed ([`EnrollIssueError`]) -- see [`registry`]'s own module doc comment.
pub use ;
/// How long an issued token remains claimable. Fixed, not operator-configurable -- the
/// TTL is enforced server-side, never a courtesy either side can override.
pub const TOKEN_TTL_SECS: u64 = 180;
/// Caps how many enrollments can be pending at once, purely to bound memory against a
/// runaway or misbehaving admin caller -- the `Issue` path needs loopback and the operator
/// secret, so this is a sanity bound, not a defense against a remote attacker.
const MAX_PENDING: usize = 64;
/// This listener's own cap on concurrent AUTHENTICATED-phase (post-TLS-handshake)
/// connections (F-06b).
///
/// Deliberately small, and NEVER a clone of the matching viewer/worker listener's real
/// `--max-connections` limiter. Before this fix, `EnrollConfig` was built with that
/// shared limiter (see `crate::serve::start_inner`'s old call sites): 64 anonymous
/// connections to the enrollment port (no client certificate required at all -- see the
/// module doc comment) could exhaust every real viewer/worker slot on the OTHER port,
/// since both listeners drew from the same counter. A claim/issue exchange is brief and
/// one-shot, so this cap is unrelated to how many real viewers/workers
/// `--max-connections` allows.
pub const ENROLL_MAX_CONNECTIONS: usize = 8;
/// How many bare, not-yet-TLS-handshaked enrollment connections are allowed in flight at
/// once, as a multiple of [`ENROLL_MAX_CONNECTIONS`] -- this listener's own counterpart
/// to `crate::serve::limiter::PRE_AUTH_HANDSHAKE_MULTIPLIER` (not reused directly: that
/// constant lives behind `#[cfg(feature = "worker")]` re-exports, but this module runs
/// in every build). Checked in the accept loop BEFORE a thread is even spawned,
/// mirroring `serve::accept::run_accept_loop`'s own order (F-06b).
const ENROLL_HANDSHAKE_MULTIPLIER: usize = 4;
/// Builds the enrollment listener's TLS server config: TLS 1.3 only, presenting
/// `[server_cert, ca_cert]` as the chain -- deliberately including the CA certificate
/// so a claiming client (which has no CA file of its own) receives the bytes it needs
/// to hash and compare against its token's fingerprint. See
/// `crate::enroll_client::PinnedCaVerifier`.
///
/// Requires no client certificate: an enrolling client has none yet, and `cert
/// issue-token` authenticates by connecting from loopback with the operator secret
/// instead -- a weaker TLS posture than the render listener's, hence a separate config on
/// a separate port.
///
/// # Errors
///
/// A human-readable message if the server certificate/key/CA can't be loaded from
/// `cert_path`/`key_path`/`ca_path`, or don't form a valid TLS server configuration.
/// Configuration [`spawn_enroll_listener`] needs, gathered once at `serve` startup from
/// the same `--ca`/`--cert`/`--key` args the listeners validated.
/// Loads `<pki_dir>/issue.secret`, creating it (32 fresh CSPRNG bytes, owner-only
/// permissions) when it does not exist yet.
///
/// # Errors
///
/// A human-readable message if an existing file is unreadable or malformed (never
/// silently replaced), or a new one can't be created.
/// Binds `config.bind_addr` and spawns a background thread accepting enrollment
/// connections forever.
///
/// Mirrors `crate::serve::run`'s accept-loop shape (one `thread::spawn` per connection,
/// `catch_unwind`-wrapped). Returns as soon as the bind succeeds, so a bad
/// `--enroll-bind` is reported synchronously at `serve` startup.
///
/// Returns the listener's actual bound address (useful when `config.bind_addr`'s port
/// was `0`; this crate's tests use that for an ephemeral port).
///
/// # Errors
///
/// A human-readable message if the bind itself fails (e.g. the port is already in use).