Skip to main content

dekopon_brokerd/
lib.rs

1#![forbid(unsafe_code)]
2#![cfg(unix)]
3#![cfg_attr(test, allow(clippy::unwrap_used))]
4#![cfg_attr(
5    test,
6    allow(
7        clippy::disallowed_methods,
8        clippy::disallowed_types,
9        reason = "tests spawn, join and drain freely; production sites carry their own expectation"
10    )
11)]
12mod assets;
13pub mod capabilities;
14
15const BROKER_PRINCIPAL: &str = "dekopon-broker";
16const RECONCILIATION_OWNER: &str = "dekopon-gatewayd";
17mod config;
18mod github_app;
19mod lock_watch;
20#[cfg(test)]
21mod private_read_witness;
22mod provider_manager;
23mod reaper;
24mod refresh_scheduler;
25mod secrets;
26mod server;
27mod socket;
28mod workflows;
29
30use std::{
31    collections::{BTreeMap, BTreeSet},
32    future::Future,
33    path::{Path, PathBuf},
34    sync::Arc,
35    time::Duration,
36};
37
38use config::{LoadMode, Resident};
39use dekopon_broker::{
40    AuditLog, Broker, ConstraintCatalog, IdentityDirectory, Leniency, PolicyBuildError,
41    PolicyEngine, PolicyWorld, TraceOnlyAuditLog,
42};
43use dekopon_broker_host::BrokerProviderRegistry;
44pub use dekopon_broker_host::enable_test_component_memoization;
45use dekopon_broker_protocol::ResponseEnvelope;
46use dekopon_capability::EffectKind;
47use dekopon_core::{SecretDrn, bounded_problems, error_chain};
48use thiserror::Error;
49
50pub use config::{
51    AgentBindingConfig, AssetsConfig, BrokerdConfig, CONFIG_API_VERSION, ConfigApiVersion,
52    ConfigError, HostLimitsConfig, ManagedProviderSetConfig, PeerIdentity, PrincipalConfig,
53    ResolvedConfig, ResolvedTelemetry, ServerLimitsConfig, StorageConfig, TelemetryConfig,
54};
55pub use dekopon_broker::MAX_SECRET_BINDINGS as HARD_MAX_SECRET_BINDINGS;
56pub use provider_manager::{
57    HARD_MAX_PROVIDER_COMPONENT_BYTES, HARD_MAX_PROVIDER_MANIFEST_BYTES,
58    HARD_MAX_PROVIDER_STATE_BYTES, HARD_MAX_PROVIDER_STORE_BLOBS, HARD_MAX_PROVIDER_STORE_BYTES,
59    PROVIDER_ARTIFACT_TYPE, PROVIDER_LAYER_MEDIA_TYPE, ProviderLock, ProviderLockApiVersion,
60    ProviderManager, ProviderManagerError, ProviderManagerOptions, ProviderManagerPaths,
61    ProviderSet, ProviderSetApiVersion, ProviderSkillStatus, ProviderStatus, ProviderSyncReport,
62    ProviderVerifyReport,
63};
64pub use secrets::{
65    HARD_MAX_SECRET_BYTES, HARD_MAX_SECRET_MAP_BYTES, HARD_MAX_SECRETS, SECRET_MAP_API_VERSION,
66    SecretMapError, SourceError,
67};
68pub use server::{BrokerServer, MappedPeer, ServerError, ServerLimits, ShutdownDeadline};
69pub use socket::{SocketError, SocketGuard, current_uid};
70
71pub const HARD_MAX_PROVIDERS: usize = 64;
72
73pub async fn telemetry_settings(
74    config_path: impl AsRef<Path>,
75    uid: u32,
76) -> Result<Option<ResolvedTelemetry>, BrokerdError> {
77    Ok(config::load(config_path, uid).await?.telemetry)
78}
79
80pub async fn run<F>(
81    config_path: impl AsRef<Path>,
82    shutdown: F,
83    deadline: ShutdownDeadline,
84) -> Result<(), BrokerdError>
85where
86    F: Future<Output = ()> + Send,
87{
88    serve(config_path, shutdown, deadline, lock_watch::POLL).await
89}
90
91async fn serve<F>(
92    config_path: impl AsRef<Path>,
93    shutdown: F,
94    deadline: ShutdownDeadline,
95    lock_poll: Duration,
96) -> Result<(), BrokerdError>
97where
98    F: Future<Output = ()> + Send,
99{
100    let (candidate, report) = load_candidate(config_path.as_ref(), Mode::Boot).await;
101    for warning in &report.warnings {
102        warning.log();
103    }
104    let candidate = match candidate {
105        Some(Loaded::Candidate(candidate)) => *candidate,
106        Some(Loaded::Unchanged) | None => {
107            return Err(BrokerdError::from_problems(report.problems));
108        }
109    };
110    let uid = current_uid();
111    let limits = candidate.limits;
112    let socket_path = candidate.socket_path.clone();
113    let provider_lock = candidate.provider_lock.clone();
114    let storage = candidate.storage.clone();
115    let coordination = Arc::new(Coordination::new(
116        config_path.as_ref().to_path_buf(),
117        candidate,
118    ));
119    let server = BrokerServer::for_generations(Arc::clone(&coordination), limits)?
120        .with_shutdown_deadline(deadline.clone());
121    let (listener, mut socket_guard) = socket::bind(&socket_path, uid).await?;
122    coordination.active().ready.policy_loaded();
123    tracing::info!(event = "broker_started", "broker.started");
124    let mut lock_stop = None;
125    let stop = async {
126        lock_stop = stopped(shutdown, provider_lock.as_ref(), uid, lock_poll).await;
127        deadline.start(limits.shutdown_grace);
128        // Unlinking at admission close sends a new connect to NotFound, which clients retry,
129        // instead of into a listener that will never accept it.
130        if let Err(error) = socket_guard.cleanup() {
131            tracing::warn!(
132                event = "broker_socket_cleanup_failed",
133                error = %error_chain(&error),
134                "broker.socket.cleanup.failed"
135            );
136        }
137    };
138    let serving = async {
139        let result = server.serve(listener, stop).await;
140        deadline.start(limits.shutdown_grace);
141        result
142    };
143    let result = refresh_scheduler::serve(
144        reaper::serve(
145            serving,
146            storage,
147            || {
148                coordination
149                    .active()
150                    .ready
151                    .broker
152                    .storage_retention_policies()
153            },
154            deadline.clone(),
155        ),
156        || coordination.active().ready.scheduled.clone(),
157        deadline.clone(),
158    )
159    .await;
160
161    coordination.drain_credentials().await;
162
163    // Checking result before cleanup here is deliberate: propagating cleanup's error first would
164    // mask the real failure and skip logging broker_stopped.
165    let cleanup = socket_guard.cleanup();
166    if let Err(error) = &cleanup {
167        tracing::warn!(
168            event = "broker_socket_cleanup_failed",
169            error = %error_chain(error),
170            "broker.socket.cleanup.failed"
171        );
172    }
173
174    result?;
175    tracing::info!(event = "broker_stopped", "broker.stopped");
176    cleanup?;
177    match lock_stop {
178        None | Some(lock_watch::LockStop::Changed) => Ok(()),
179        Some(lock_watch::LockStop::Unsettled) => Err(BrokerdError::ProviderLockUnsettled),
180    }
181}
182
183async fn stopped<F>(
184    shutdown: F,
185    lock: Option<&lock_watch::LoadedLock>,
186    uid: u32,
187    poll: Duration,
188) -> Option<lock_watch::LockStop>
189where
190    F: Future<Output = ()>,
191{
192    let Some(lock) = lock else {
193        shutdown.await;
194        return None;
195    };
196    tokio::select! {
197        () = shutdown => None,
198        stop = lock_watch::watch(lock, uid, poll) => Some(stop),
199    }
200}
201
202#[derive(Debug)]
203pub struct CheckProviders {
204    pub provider_set: PathBuf,
205    pub store: PathBuf,
206}
207
208#[derive(Debug, Default)]
209pub struct CheckReport {
210    pub problems: Vec<BrokerdError>,
211    pub warnings: Vec<StartupWarning>,
212    pub policy_digest: Option<String>,
213    pub identity_digest: Option<String>,
214    pub continuity: Option<dekopon_broker::ContinuityReport>,
215    private_sources: Vec<PathBuf>,
216    pub peak_rss_bytes: Option<u64>,
217}
218
219pub async fn check(
220    config_path: impl AsRef<Path>,
221    providers: Option<CheckProviders>,
222    workflows: Option<&Path>,
223) -> CheckReport {
224    let mut report = load_candidate(
225        config_path.as_ref(),
226        Mode::Check {
227            providers,
228            workflows,
229        },
230    )
231    .await
232    .1;
233    report.peak_rss_bytes = dekopon_broker_host::peak_rss_bytes();
234    report
235}
236
237#[derive(Clone, Copy, Debug, Eq, PartialEq)]
238pub enum Stage {
239    ProviderSet,
240    FrameLimits,
241    Runtime,
242    Providers,
243    Workflows,
244}
245
246impl std::fmt::Display for Stage {
247    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
248        formatter.write_str(match self {
249            Self::ProviderSet => "provider set",
250            Self::FrameLimits => "frame limits",
251            Self::Runtime => "runtime files",
252            Self::Providers => "providers, policy and capabilities",
253            Self::Workflows => "essential workflows",
254        })
255    }
256}
257
258enum Mode<'a> {
259    Boot,
260    Reload(&'a Candidate),
261    Check {
262        providers: Option<CheckProviders>,
263        workflows: Option<&'a Path>,
264    },
265}
266
267enum Residents<'a> {
268    Open,
269    Borrow(&'a Candidate),
270    Scratch,
271}
272
273struct Candidate {
274    digest: String,
275    fingerprint: Option<PrivateFingerprint>,
276    ready: Ready,
277    socket_path: PathBuf,
278    provider_lock: Option<lock_watch::LoadedLock>,
279    limits: ServerLimits,
280    storage: Option<dekopon_storage_host::StorageHost>,
281    assets: Option<dekopon_http_host::asset::AssetDirectory>,
282    locked_providers: Option<Vec<dekopon_broker_host::LockedProviderSource>>,
283    snapshot: config::ConfigSnapshot,
284}
285
286enum Loaded {
287    Candidate(Box<Candidate>),
288    Unchanged,
289}
290
291struct Coordination {
292    config_path: PathBuf,
293    loading: tokio::sync::Semaphore,
294    state: parking_lot::Mutex<GenerationState>,
295}
296
297struct GenerationState {
298    active: Arc<Candidate>,
299    prepared: Option<(u32, Arc<Candidate>, Arc<Candidate>)>,
300    reported: Option<RawCandidate>,
301    retired_credentials: Vec<std::sync::Weak<dekopon_model::chatgpt::CredentialFile>>,
302}
303
304impl GenerationState {
305    fn unreported(&mut self, raw: RawCandidate) -> bool {
306        self.reported.replace(raw) != Some(raw)
307    }
308
309    fn owned_by(&self, uid: u32) -> bool {
310        self.active
311            .ready
312            .identities
313            .get(&uid)
314            .is_some_and(MappedPeer::is_reconciliation_owner)
315    }
316}
317
318impl Coordination {
319    fn new(config_path: PathBuf, active: Candidate) -> Self {
320        Self {
321            config_path,
322            loading: tokio::sync::Semaphore::new(1),
323            state: parking_lot::Mutex::new(GenerationState {
324                active: Arc::new(active),
325                prepared: None,
326                reported: None,
327                retired_credentials: Vec::new(),
328            }),
329        }
330    }
331
332    async fn drain_credentials(&self) {
333        let credentials = {
334            let state = self.state.lock();
335            let mut credentials = state.active.ready.chatgpt.clone();
336            credentials.extend(
337                state
338                    .retired_credentials
339                    .iter()
340                    .filter_map(std::sync::Weak::upgrade),
341            );
342            credentials
343        };
344        for credential in credentials {
345            credential.drain().await;
346        }
347    }
348
349    fn active(&self) -> Arc<Candidate> {
350        Arc::clone(&self.state.lock().active)
351    }
352
353    fn owns(&self, uid: u32) -> bool {
354        self.state.lock().owned_by(uid)
355    }
356
357    async fn prepare(
358        &self,
359        expected_active: &str,
360        uid: u32,
361    ) -> (String, dekopon_broker_protocol::GenerationOutcome) {
362        use dekopon_broker_protocol::GenerationOutcome;
363        let Ok(_permit) = self.loading.acquire().await else {
364            return (self.active().digest.clone(), GenerationOutcome::Refused);
365        };
366        let active = {
367            let state = self.state.lock();
368            if state.active.digest != expected_active
369                || !state.owned_by(uid)
370                || state
371                    .prepared
372                    .as_ref()
373                    .is_some_and(|(owner, _, _)| *owner != uid)
374            {
375                return (state.active.digest.clone(), GenerationOutcome::Refused);
376            }
377            Arc::clone(&state.active)
378        };
379        let (loaded, report) = load_candidate(&self.config_path, Mode::Reload(&active)).await;
380        let Some(loaded) = loaded else {
381            let entries = report
382                .problems
383                .iter()
384                .flat_map(reload_entries)
385                .collect::<Vec<_>>();
386            let count = entries.len();
387            let error = bounded_problems(entries.into_iter());
388            let raw = RawCandidate::of(
389                self.config_path.clone(),
390                report.private_sources,
391                error.clone(),
392            )
393            .await;
394            let unreported = self.state.lock().unreported(raw);
395            let unreadable = report.problems.iter().any(|problem| {
396                matches!(
397                    problem,
398                    BrokerdError::Config(config::ConfigError::Read { .. })
399                )
400            });
401            match (unreported, unreadable) {
402                (false, _) => {}
403                (true, true) => {
404                    tracing::warn!(event = "broker_reload_monitor_failed", applied = false, error = %error, "broker.reload.monitor.failed");
405                }
406                (true, false) => tracing::warn!(
407                    event = "broker_reload_refused",
408                    applied = false,
409                    problems = count,
410                    error = %error,
411                    "broker.reload.refused"
412                ),
413            }
414            return (active.digest.clone(), GenerationOutcome::Refused);
415        };
416        let next = {
417            let mut state = self.state.lock();
418            if !Arc::ptr_eq(&state.active, &active)
419                || !state.owned_by(uid)
420                || state
421                    .prepared
422                    .as_ref()
423                    .is_some_and(|(owner, _, _)| *owner != uid)
424            {
425                return (state.active.digest.clone(), GenerationOutcome::Refused);
426            }
427            state.reported = None;
428            match loaded {
429                Loaded::Unchanged => {
430                    state.prepared = None;
431                    return (active.digest.clone(), GenerationOutcome::Active);
432                }
433                Loaded::Candidate(next) => {
434                    let next = Arc::<Candidate>::from(next);
435                    state.prepared = Some((uid, active, Arc::clone(&next)));
436                    next
437                }
438            }
439        };
440        next.ready.scheduled.inspect_records().await;
441        (next.digest.clone(), GenerationOutcome::Prepared)
442    }
443
444    fn commit(&self, digest: &str, uid: u32) -> dekopon_broker_protocol::GenerationOutcome {
445        use dekopon_broker_protocol::GenerationOutcome;
446        let mut state = self.state.lock();
447        if !state.owned_by(uid) {
448            return GenerationOutcome::Refused;
449        }
450        let Some((owner, base, next)) = state.prepared.take() else {
451            return GenerationOutcome::Refused;
452        };
453        if owner != uid || next.digest != digest || !Arc::ptr_eq(&base, &state.active) {
454            state.prepared = Some((owner, base, next));
455            return GenerationOutcome::Refused;
456        }
457        let categories = state.active.snapshot.changed_categories(&next.snapshot);
458        state
459            .retired_credentials
460            .retain(|credential| credential.strong_count() > 0);
461        let retired: Vec<_> = state
462            .active
463            .ready
464            .chatgpt
465            .iter()
466            .map(Arc::downgrade)
467            .collect();
468        state.retired_credentials.extend(retired);
469        state.active = next;
470        state.active.ready.policy_loaded();
471        tracing::info!(
472            event = "broker_reload_applied",
473            generation.digest = digest,
474            category.count = categories.len(),
475            categories = %categories.join(","),
476            "broker.reload.applied"
477        );
478        GenerationOutcome::Applied
479    }
480
481    fn abort(&self, digest: &str, uid: u32) -> dekopon_broker_protocol::GenerationOutcome {
482        use dekopon_broker_protocol::GenerationOutcome;
483        let mut state = self.state.lock();
484        if state.owned_by(uid)
485            && state
486                .prepared
487                .as_ref()
488                .is_some_and(|(owner, _, next)| *owner == uid && next.digest == digest)
489        {
490            state.prepared = None;
491            GenerationOutcome::Aborted
492        } else {
493            GenerationOutcome::Refused
494        }
495    }
496}
497
498#[expect(
499    clippy::too_many_lines,
500    reason = "independent validation stages aggregate failures before preparing a candidate"
501)]
502async fn load_candidate(config_path: &Path, mode: Mode<'_>) -> (Option<Loaded>, CheckReport) {
503    let mut report = CheckReport::default();
504    let uid = current_uid();
505    let load_mode = match mode {
506        Mode::Boot => LoadMode::Boot,
507        Mode::Reload(active) => LoadMode::Reload {
508            locked_providers: active.locked_providers.as_deref(),
509            provider_lock: active.provider_lock.as_ref(),
510        },
511        Mode::Check { .. } => LoadMode::Check,
512    };
513    let essential = match &mode {
514        Mode::Check {
515            workflows: Some(directory),
516            ..
517        } => match workflows::load(directory, uid).await {
518            Ok(files) => Some(files),
519            Err(error) => {
520                report.problems.push(error.into());
521                None
522            }
523        },
524        Mode::Boot
525        | Mode::Reload(_)
526        | Mode::Check {
527            workflows: None, ..
528        } => None,
529    };
530    let mut provider_lock_file = None;
531    let Some(mut config) = (match config::load_in(config_path, uid, load_mode).await {
532        Ok((config, refusal)) => {
533            report.problems.extend(refusal.map(BrokerdError::from));
534            report.private_sources.extend(
535                [&config.secret_map_path, &config.policies_path]
536                    .into_iter()
537                    .flatten()
538                    .cloned(),
539            );
540            Some(config)
541        }
542        Err(error) => {
543            report.problems.push(error.into());
544            None
545        }
546    }) else {
547        for stage in [
548            Stage::ProviderSet,
549            Stage::FrameLimits,
550            Stage::Runtime,
551            Stage::Providers,
552        ] {
553            report.skipped(stage);
554        }
555        if essential.is_some() {
556            report.skipped(Stage::Workflows);
557        }
558        return (None, report);
559    };
560    let (providers_resolved, residents) = match mode {
561        Mode::Boot => (true, Residents::Open),
562        Mode::Reload(active) => (true, Residents::Borrow(active)),
563        Mode::Check { providers, .. } => {
564            if config.identities.is_empty() {
565                report.warnings.push(StartupWarning::IdentitiesRequired);
566            }
567            report.warnings.extend(
568                config
569                    .identities
570                    .iter()
571                    .filter_map(|identity| identity.attestor.as_ref()?.namespaces.as_ref())
572                    .flatten()
573                    .filter(|scope| scope.names_every_kind())
574                    .map(|scope| StartupWarning::ScopeKinds {
575                        scope: scope.to_string(),
576                        kinds: scope.kinds().iter().map(ToString::to_string).collect(),
577                    }),
578            );
579            // A Check load leaves a providerSet's providers for this function to resolve.
580            let resolved = match (config.providers.is_empty(), providers) {
581                (true, Some(providers)) => {
582                    provider_lock_file = Some(providers.store.join(PROVIDER_LOCK_FILE));
583                    match resolve_provider_set(providers, uid).await {
584                        Ok(sources) => {
585                            config.providers = sources
586                                .iter()
587                                .map(|source| source.path().to_path_buf())
588                                .collect();
589                            config.locked_providers = Some(sources);
590                            true
591                        }
592                        Err(error) => {
593                            report.problems.push(error);
594                            false
595                        }
596                    }
597                }
598                (true, None) => {
599                    report.problems.push(BrokerdError::ProviderSetRequired);
600                    false
601                }
602                (false, Some(_)) => {
603                    report.problems.push(BrokerdError::ProviderSetUnused);
604                    true
605                }
606                (false, None) => true,
607            };
608            (resolved, Residents::Scratch)
609        }
610    };
611    let restart_categories = match residents {
612        Residents::Borrow(active) => active.snapshot.restart_required(&config.snapshot),
613        Residents::Open | Residents::Scratch => Vec::new(),
614    };
615    if !restart_categories.is_empty() {
616        report.problems.push(BrokerdError::RestartRequired {
617            categories: restart_categories.clone(),
618        });
619    }
620    let frame_limits = keep(
621        &mut report.problems,
622        config
623            .server_limits
624            .frame_limits()
625            .map_err(BrokerdError::from),
626    );
627    let mut scratch = None;
628    let runtime = match residents {
629        Residents::Open => boot_runtime(&mut config, uid, &mut report.problems).await,
630        Residents::Borrow(active) => {
631            reload_runtime(&mut config, uid, active, &mut scratch, &mut report.problems).await
632        }
633        Residents::Scratch => {
634            let secrets = match config.secret_map_path.as_deref() {
635                Some(path) => match secrets::load_shapes(path, uid).await {
636                    Ok(catalog) => Some(Secrets::Shapes(catalog)),
637                    Err(secrets::SecretMapError::Read { .. }) => Some(Secrets::Unchecked),
638                    Err(
639                        error @ (secrets::SecretMapError::Decode { .. }
640                        | secrets::SecretMapError::Validation { .. }
641                        | secrets::SecretMapError::Client { .. }
642                        | secrets::SecretMapError::Source { .. }
643                        | secrets::SecretMapError::Catalog { .. }),
644                    ) => {
645                        report.problems.push(error.into());
646                        None
647                    }
648                },
649                None => Some(Secrets::Shapes(dekopon_broker::SecretCatalog::empty())),
650            };
651            keep(&mut report.problems, scratch_host(&config, &mut scratch))
652                .zip(secrets)
653                .map(|(storage, secrets)| Runtime {
654                    secrets,
655                    chatgpt: Vec::new(),
656                    fingerprint: None,
657                    storage,
658                    assets: None,
659                })
660        }
661    };
662    let (Some(frame_limits), Some(mut runtime), true) = (frame_limits, runtime, providers_resolved)
663    else {
664        report.skipped(Stage::Providers);
665        if essential.is_some() {
666            report.skipped(Stage::Workflows);
667        }
668        return (None, report);
669    };
670    let digest = config.snapshot.digest();
671    match residents {
672        Residents::Borrow(active)
673            if report.problems.is_empty()
674                && runtime.fingerprint.is_some()
675                && runtime.fingerprint == active.fingerprint
676                && digest.as_ref().is_ok_and(|digest| *digest == active.digest) =>
677        {
678            // A provider's ownership and mode are not in the digest, so same bytes still recheck them.
679            return match validate_unmanaged_providers(&config, Some(&active.ready.registry), uid) {
680                Ok(()) => (Some(Loaded::Unchanged), report),
681                Err(error) => {
682                    report.problems.push(error);
683                    (None, report)
684                }
685            };
686        }
687        Residents::Open | Residents::Borrow(_) | Residents::Scratch => {}
688    }
689    let limits = ServerLimits {
690        frame: frame_limits,
691        max_connections: config.server_limits.max_connections,
692        shutdown_grace: config.server_limits.shutdown_grace(),
693    };
694    let socket_path = std::mem::take(&mut config.socket_path);
695    let provider_lock = config.provider_lock.take();
696    let locked_providers = config.locked_providers.clone();
697    let reuse_registry = provider_lock.is_some() || restart_categories.is_empty();
698    let storage = runtime.storage.clone();
699    let assets = runtime.assets.clone();
700    let fingerprint = runtime.fingerprint.take();
701    let snapshot = config.snapshot.clone();
702    let resident_registry = match residents {
703        Residents::Borrow(active) if reuse_registry => Some(active.ready.registry.clone()),
704        Residents::Open | Residents::Borrow(_) | Residents::Scratch => None,
705    };
706    let prepared = prepare(
707        config,
708        frame_limits.max_frame_bytes,
709        runtime,
710        &mut report,
711        resident_registry,
712    )
713    .await;
714    drop(scratch);
715    match (&prepared, &essential) {
716        (Ok(ready), Some(files)) => {
717            let versions = workflows::versions(provider_lock_file.as_deref(), uid).await;
718            report.problems.extend(
719                workflows::run(ready, files, &versions)
720                    .await
721                    .into_iter()
722                    .map(BrokerdError::Workflow),
723            );
724        }
725        (Err(_), Some(_)) => report.skipped(Stage::Workflows),
726        (Ok(_) | Err(_), None) => {}
727    }
728    match prepared {
729        Ok(ready) if report.problems.is_empty() => {
730            let digest = match digest {
731                Ok(digest) => digest,
732                Err(source) => {
733                    report.problems.push(BrokerdError::Snapshot { source });
734                    return (None, report);
735                }
736            };
737            (
738                Some(Loaded::Candidate(Box::new(Candidate {
739                    digest,
740                    fingerprint,
741                    ready,
742                    socket_path,
743                    provider_lock,
744                    limits,
745                    storage,
746                    assets,
747                    locked_providers,
748                    snapshot,
749                }))),
750                report,
751            )
752        }
753        Ok(_) => (None, report),
754        Err(problems) => {
755            report.problems.extend(problems);
756            (None, report)
757        }
758    }
759}
760
761impl CheckReport {
762    fn skipped(&mut self, stage: Stage) {
763        self.warnings.push(StartupWarning::Skipped { stage });
764    }
765}
766
767async fn boot_runtime(
768    config: &mut ResolvedConfig,
769    uid: u32,
770    problems: &mut Vec<BrokerdError>,
771) -> Option<Runtime> {
772    let private = private_inputs(config, uid, problems).await;
773    if let Some(private) = &private {
774        private.scheduled.inspect_records().await;
775    }
776    let storage = keep(
777        problems,
778        config
779            .storage
780            .as_ref()
781            .map(|storage| {
782                dekopon_storage_host::StorageHost::open(&storage.root_path, storage.limits.clone())
783            })
784            .transpose()
785            .map_err(BrokerdError::Storage),
786    );
787    tracing::info!(
788        max_connections = config.server_limits.max_connections,
789        max_memory_bytes = config.host_limits.max_memory_bytes,
790        aggregate_ceiling_bytes = config.host_options.max_total_memory_bytes,
791        cwasm_cache = config
792            .host_options
793            .cwasm_dir
794            .as_ref()
795            .map(|path| path.display().to_string()),
796        "broker.memory.budget"
797    );
798    if !config.plaintext_hosts.is_empty() {
799        let hosts = config.plaintext_hosts.iter().collect::<Vec<_>>().join(", ");
800        tracing::info!(
801            event = "broker_plaintext_hosts",
802            "http plaintext hosts allowed: [{hosts}]"
803        );
804    }
805    let assets = match &config.assets {
806        Some(config) => keep(
807            problems,
808            assets::initialize(config)
809                .await
810                .map(Some)
811                .map_err(BrokerdError::Assets),
812        ),
813        None => Some(None),
814    };
815    let (private, storage, assets) = (private?, storage?, assets?);
816    Some(Runtime {
817        chatgpt: private.chatgpt,
818        secrets: Secrets::Loaded(private.secrets, private.scheduled),
819        fingerprint: Some(private.fingerprint),
820        storage,
821        assets,
822    })
823}
824
825async fn reload_runtime(
826    config: &mut ResolvedConfig,
827    uid: u32,
828    active: &Candidate,
829    scratch: &mut Option<tempfile::TempDir>,
830    problems: &mut Vec<BrokerdError>,
831) -> Option<Runtime> {
832    let private = private_inputs(config, uid, problems).await;
833    let storage = if active.snapshot.keeps(&config.snapshot, Resident::Storage) {
834        active.storage.clone()
835    } else {
836        keep(problems, scratch_host(config, scratch))?
837    };
838    let assets = if active.snapshot.keeps(&config.snapshot, Resident::Assets) {
839        active.assets.clone()
840    } else {
841        None
842    };
843    let private = private?;
844    Some(Runtime {
845        chatgpt: private.chatgpt,
846        secrets: Secrets::Loaded(private.secrets, private.scheduled),
847        fingerprint: Some(private.fingerprint),
848        storage,
849        assets,
850    })
851}
852
853#[cfg(test)]
854tokio::task_local! {
855    pub(crate) static AFTER_PRIVATE_READ: std::sync::Arc<dyn Fn() + Send + Sync>;
856    pub(crate) static BEFORE_BROKER_PREPARE: std::sync::Arc<dyn Fn() + Send + Sync>;
857}
858
859async fn private_inputs(
860    config: &mut ResolvedConfig,
861    uid: u32,
862    problems: &mut Vec<BrokerdError>,
863) -> Option<PrivateInputs> {
864    match socket::validate_socket_parent(&config.socket_path, uid) {
865        // An owner-only socket under a private parent means other configured UIDs could never
866        // connect — the broker starts healthy while peers loop on EACCES — so every unreachable
867        // peer is checked at startup.
868        Ok(parent) if dekopon_broker_protocol::ipc_socket_mode(&parent) == 0o600 => {
869            let configured = config
870                .identities
871                .iter()
872                .map(|identity| identity.uid)
873                .filter(|peer| *peer != uid)
874                .collect::<Vec<_>>();
875            if !configured.is_empty() {
876                problems.push(BrokerdError::UnreachablePeerUids {
877                    configured,
878                    server: uid,
879                });
880            }
881        }
882        Ok(_) => {}
883        Err(error) => problems.push(error.into()),
884    }
885    // A compilation cache holds compiled code the broker will execute. Anyone who can write into
886    // it can choose what the privileged process runs, so it must sit under a private parent.
887    if let Some(cache) = &config.host_options.cwasm_dir
888        && let Err(error) = socket::validate_private_parent(cache, uid)
889    {
890        problems.push(error.into());
891    }
892    let secrets = match &config.secret_map_path {
893        Some(path) => keep(
894            problems,
895            secrets::load_with_bytes(path, uid)
896                .await
897                .map(Some)
898                .map_err(BrokerdError::from),
899        ),
900        None => Some(None),
901    };
902    #[cfg(test)]
903    let _hook_ran = AFTER_PRIVATE_READ.try_with(|hook| hook()).is_ok();
904    let secrets = secrets?;
905    if let Err(error) = config
906        .snapshot
907        .record_authority_references(secrets.as_ref().map(|loaded| loaded.bytes.as_slice()))
908    {
909        problems.push(error.into());
910    }
911    let fingerprint = PrivateFingerprint::of(
912        secrets
913            .as_ref()
914            .map(|loaded| (loaded.bytes.as_slice(), &loaded.key_digest)),
915    );
916    Some(match secrets {
917        Some(loaded) => PrivateInputs {
918            chatgpt: loaded.chatgpt,
919            secrets: loaded.catalog,
920            scheduled: loaded.scheduled,
921            fingerprint,
922        },
923        None => PrivateInputs {
924            chatgpt: Vec::new(),
925            secrets: dekopon_broker::SecretCatalog::empty(),
926            scheduled: secrets::ScheduledCatalog::default(),
927            fingerprint,
928        },
929    })
930}
931
932struct PrivateInputs {
933    chatgpt: Vec<Arc<dekopon_model::chatgpt::CredentialFile>>,
934    secrets: dekopon_broker::SecretCatalog,
935    scheduled: secrets::ScheduledCatalog,
936    fingerprint: PrivateFingerprint,
937}
938
939#[derive(PartialEq, Eq)]
940struct PrivateFingerprint([u8; 32]);
941
942impl PrivateFingerprint {
943    fn of(secret_map: Option<(&[u8], &[u8; 32])>) -> Self {
944        use sha2::{Digest as _, Sha256};
945        let mut hasher = Sha256::new();
946        match secret_map {
947            Some((bytes, keys)) => {
948                hasher.update([1]);
949                hasher.update(bytes);
950                hasher.update(keys);
951            }
952            None => hasher.update([0]),
953        }
954        Self(hasher.finalize().into())
955    }
956}
957
958const MAX_RAW_SOURCE_BYTES: u64 = 16 << 20;
959
960#[derive(Clone, Copy, PartialEq, Eq)]
961struct RawCandidate([u8; 32]);
962
963impl RawCandidate {
964    async fn of(config: PathBuf, private: Vec<PathBuf>, refusal: String) -> Self {
965        use std::io::Read as _;
966
967        use sha2::{Digest as _, Sha256};
968        let digest = tokio::task::spawn_blocking(move || {
969            let mut paths = std::fs::read_dir(&config).map_or_else(
970                |_| vec![config.clone()],
971                |entries| {
972                    entries
973                        .filter_map(|entry| Some(entry.ok()?.path()))
974                        .collect()
975                },
976            );
977            paths.sort();
978            paths.extend(private);
979            let mut hasher = Sha256::new();
980            for path in paths {
981                let bytes = std::fs::metadata(&path)
982                    .and_then(|metadata| {
983                        if !metadata.is_file() {
984                            return Err(std::io::ErrorKind::InvalidInput.into());
985                        }
986                        let mut bytes = Vec::new();
987                        std::fs::File::open(&path)?
988                            .take(MAX_RAW_SOURCE_BYTES)
989                            .read_to_end(&mut bytes)?;
990                        Ok(bytes)
991                    })
992                    .unwrap_or_else(|error| error.to_string().into_bytes());
993                for part in [path.as_os_str().as_encoded_bytes(), &bytes] {
994                    hasher.update(part.len().to_le_bytes());
995                    hasher.update(part);
996                }
997            }
998            hasher.update(refusal.as_bytes());
999            hasher.finalize().into()
1000        })
1001        .await;
1002        Self(digest.unwrap_or_default())
1003    }
1004}
1005
1006const PROVIDER_LOCK_FILE: &str = "providers.lock.yaml";
1007
1008async fn resolve_provider_set(
1009    providers: CheckProviders,
1010    uid: u32,
1011) -> Result<Vec<dekopon_broker_host::LockedProviderSource>, BrokerdError> {
1012    let mut directory = tokio::fs::DirBuilder::new();
1013    directory.mode(0o700);
1014    match directory.create(&providers.store).await {
1015        Ok(()) => {}
1016        Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {}
1017        Err(source) => {
1018            return Err(BrokerdError::CheckDirectory {
1019                path: providers.store,
1020                source,
1021            });
1022        }
1023    }
1024    let lock_file = providers.store.join(PROVIDER_LOCK_FILE);
1025    let store = providers.store.join("store");
1026    let manager = ProviderManager::new(ProviderManagerOptions {
1027        paths: ProviderManagerPaths {
1028            provider_set: Some(providers.provider_set),
1029            lock_file: lock_file.clone(),
1030            store: store.clone(),
1031        },
1032        plaintext_loopback_registries: Vec::new(),
1033    })
1034    .await
1035    .map_err(BrokerdError::ProviderSet)?;
1036    manager.sync().await.map_err(BrokerdError::ProviderSet)?;
1037    manager
1038        .precompile()
1039        .await
1040        .map_err(BrokerdError::ProviderSet)?;
1041    provider_manager::load_locked_sources(&lock_file, &store, uid)
1042        .await
1043        .map_err(BrokerdError::ProviderSet)
1044}
1045
1046fn scratch_host(
1047    config: &ResolvedConfig,
1048    scratch: &mut Option<tempfile::TempDir>,
1049) -> Result<Option<dekopon_storage_host::StorageHost>, BrokerdError> {
1050    let Some(storage) = &config.storage else {
1051        return Ok(None);
1052    };
1053    let (directory, host) = scratch_storage(storage)?;
1054    *scratch = Some(directory);
1055    Ok(Some(host))
1056}
1057
1058fn scratch_storage(
1059    storage: &StorageConfig,
1060) -> Result<(tempfile::TempDir, dekopon_storage_host::StorageHost), BrokerdError> {
1061    let scratch = tempfile::tempdir().map_err(|source| BrokerdError::CheckDirectory {
1062        path: std::env::temp_dir(),
1063        source,
1064    })?;
1065    let root = std::fs::canonicalize(scratch.path())
1066        .map_err(|source| BrokerdError::CheckDirectory {
1067            path: scratch.path().to_path_buf(),
1068            source,
1069        })?
1070        .join("storage");
1071    let host = dekopon_storage_host::StorageHost::open(root, storage.limits.clone())
1072        .map_err(BrokerdError::Storage)?;
1073    Ok((scratch, host))
1074}
1075
1076enum Secrets {
1077    Loaded(dekopon_broker::SecretCatalog, secrets::ScheduledCatalog),
1078    Shapes(dekopon_broker::SecretCatalog),
1079    Unchecked,
1080}
1081
1082struct Runtime {
1083    chatgpt: Vec<Arc<dekopon_model::chatgpt::CredentialFile>>,
1084    secrets: Secrets,
1085    fingerprint: Option<PrivateFingerprint>,
1086    storage: Option<dekopon_storage_host::StorageHost>,
1087    assets: Option<dekopon_http_host::asset::AssetDirectory>,
1088}
1089
1090struct Ready {
1091    identity_digest: String,
1092    broker: Arc<Broker<TraceOnlyAuditLog>>,
1093    scheduled: secrets::ScheduledCatalog,
1094    chatgpt: Vec<Arc<dekopon_model::chatgpt::CredentialFile>>,
1095    identities: BTreeMap<u32, MappedPeer>,
1096    registry: BrokerProviderRegistry,
1097}
1098
1099impl Ready {
1100    fn policy_loaded(&self) {
1101        tracing::info!(
1102            target: "dekopon_broker::audit",
1103            { audit.event = "broker.policy.loaded", policy.digest = self.broker.policy_digest(), identity.digest = self.identity_digest.as_str() },
1104            "broker.policy.loaded"
1105        );
1106    }
1107}
1108
1109fn validate_unmanaged_providers(
1110    config: &ResolvedConfig,
1111    resident_registry: Option<&BrokerProviderRegistry>,
1112    uid: u32,
1113) -> Result<(), BrokerdError> {
1114    // Locked artifacts were checked at boot; a pruned old blob is not a new authority source.
1115    let locked = match resident_registry {
1116        Some(_) => config.locked_providers.as_ref().map_or(0, Vec::len),
1117        None => 0,
1118    };
1119    for provider in config.providers.iter().skip(locked) {
1120        socket::validate_owned_file(provider, uid)?;
1121    }
1122    Ok(())
1123}
1124
1125#[expect(
1126    clippy::too_many_lines,
1127    reason = "reshaped by the unit that next rewrites this"
1128)]
1129async fn prepare(
1130    config: ResolvedConfig,
1131    max_frame_bytes: usize,
1132    runtime: Runtime,
1133    report: &mut CheckReport,
1134    resident_registry: Option<BrokerProviderRegistry>,
1135) -> Result<Ready, Vec<BrokerdError>> {
1136    #[cfg(test)]
1137    let _hook_ran = BEFORE_BROKER_PREPARE.try_with(|hook| hook()).is_ok();
1138    let warnings = &mut report.warnings;
1139    validate_unmanaged_providers(&config, resident_registry.as_ref(), current_uid())
1140        .map_err(|error| vec![error])?;
1141    let mut registry = if let Some(registry) = resident_registry {
1142        Ok(registry)
1143    } else {
1144        match config.locked_providers {
1145            Some(sources) => {
1146                BrokerProviderRegistry::load_locked_with_options(
1147                    sources,
1148                    config.host_limits,
1149                    runtime.storage,
1150                    &config.host_options,
1151                )
1152                .await
1153            }
1154            None => {
1155                BrokerProviderRegistry::load_with_options(
1156                    config.providers,
1157                    config.host_limits,
1158                    runtime.storage,
1159                    &config.host_options,
1160                )
1161                .await
1162            }
1163        }
1164    }
1165    .map_err(|error| vec![BrokerdError::Host(error)])?;
1166    if let Some(directory) = runtime.assets {
1167        registry.set_assets(directory);
1168    }
1169    let mut problems = Vec::new();
1170    if let Err(error) = validate_manifest_metadata(
1171        &registry,
1172        max_frame_bytes.saturating_sub(config::MINIMUM_RESPONSE_OVERHEAD_BYTES),
1173    ) {
1174        problems.push(error);
1175    }
1176    let identity_directory = keep(
1177        &mut problems,
1178        IdentityDirectory::new(config.principals.iter().flat_map(|(principal, entry)| {
1179            entry
1180                .subjects
1181                .iter()
1182                .map(|subject| (subject.clone(), principal.clone()))
1183        }))
1184        .map_err(BrokerdError::Broker),
1185    );
1186    let world = keep(
1187        &mut problems,
1188        PolicyWorld::new(
1189            config
1190                .identities
1191                .iter()
1192                .map(|identity| identity.principal.clone())
1193                .chain(config.principals.keys().cloned()),
1194            registry
1195                .capabilities()
1196                .map(|(provider, capability)| (capability.id.clone(), provider.clone())),
1197        )
1198        .map(|world| {
1199            world
1200                .with_subjects(config.principals.iter().flat_map(|(principal, entry)| {
1201                    entry
1202                        .subjects
1203                        .iter()
1204                        .map(|subject| (subject.clone(), principal.clone()))
1205                }))
1206                .with_group_members(config.principals.iter().flat_map(|(principal, entry)| {
1207                    entry
1208                        .groups
1209                        .iter()
1210                        .map(|group| (principal.clone(), group.clone()))
1211                }))
1212                .with_read_only(
1213                    registry
1214                        .capabilities()
1215                        .filter(|(_, capability)| capability.effect == EffectKind::ReadOnly)
1216                        .map(|(_, capability)| capability.id.clone()),
1217                )
1218        })
1219        .map_err(|source| BrokerdError::Policy { source }),
1220    );
1221    let world = world.map(|world| match &runtime.secrets {
1222        Secrets::Loaded(catalog, _) | Secrets::Shapes(catalog) => {
1223            world.with_secrets(catalog.drns().cloned())
1224        }
1225        Secrets::Unchecked => world,
1226    });
1227    let secrets_unchecked = match &runtime.secrets {
1228        Secrets::Loaded(_, _) | Secrets::Shapes(_) => false,
1229        Secrets::Unchecked => true,
1230    };
1231    let (secret_catalog, scheduled) = match runtime.secrets {
1232        Secrets::Loaded(catalog, scheduled) => (Some(catalog), Some(scheduled)),
1233        Secrets::Shapes(catalog) => (Some(catalog), None),
1234        Secrets::Unchecked => (None, None),
1235    };
1236    let identity_digest = world.as_ref().map(PolicyWorld::identity_digest);
1237    let policy = world.and_then(|world| {
1238        keep(
1239            &mut problems,
1240            build_policy(
1241                &config.policies,
1242                world,
1243                config.strict,
1244                secrets_unchecked,
1245                warnings,
1246            ),
1247        )
1248    });
1249    report.identity_digest = identity_digest.clone();
1250    report.policy_digest = policy
1251        .as_ref()
1252        .filter(|_| !secrets_unchecked)
1253        .map(|policy| policy.digest().to_owned());
1254    let (constraint_sets, capability_problems) =
1255        capabilities::constraint_sets(&config.capabilities, |provider| {
1256            let declared = registry
1257                .capabilities()
1258                .filter(|(owner, _)| *owner == provider)
1259                .map(|(_, capability)| capabilities::ManifestCapability {
1260                    id: &capability.id,
1261                    effect: capability.effect,
1262                    risk: capability.risk,
1263                })
1264                .collect::<Vec<_>>();
1265            (!declared.is_empty()).then_some(declared)
1266        });
1267    let (tolerable, fatal): (Vec<_>, Vec<_>) = capability_problems
1268        .into_iter()
1269        .partition(|problem| problem.is_unloaded_name() && !config.strict);
1270    if !fatal.is_empty() {
1271        problems.push(BrokerdError::Capabilities { problems: fatal });
1272    }
1273    warnings.extend(
1274        tolerable
1275            .into_iter()
1276            .map(StartupWarning::UnloadedCapability),
1277    );
1278    let (Some(identity_directory), Some(policy), true) =
1279        (identity_directory, policy, problems.is_empty())
1280    else {
1281        return Err(problems);
1282    };
1283    if secret_catalog.is_none()
1284        && constraint_sets
1285            .values()
1286            .any(|set| set.default_secret_use.is_some())
1287    {
1288        warnings.push(StartupWarning::DefaultSecretsUnchecked);
1289    }
1290    let constraints = ConstraintCatalog::new(constraint_sets)
1291        .map_err(|error| vec![BrokerdError::Broker(error)])?
1292        .with_agent_secrets(
1293            config
1294                .agents
1295                .into_iter()
1296                .map(|(agent, binding)| (agent, binding.secrets))
1297                .collect(),
1298        );
1299    let leniency = if config.strict {
1300        Leniency::Strict
1301    } else {
1302        Leniency::Tolerant
1303    };
1304    let shared_registry = registry.clone();
1305    let (broker, broker_warnings) = Broker::start(
1306        registry,
1307        BROKER_PRINCIPAL
1308            .parse()
1309            .expect("the broker principal is a valid identifier"),
1310        policy,
1311        constraints,
1312        identity_directory,
1313        Arc::new(TraceOnlyAuditLog),
1314        config.broker_limits,
1315        leniency,
1316    )
1317    .map_err(|error| vec![BrokerdError::Broker(error)])?;
1318    warnings.extend(broker_warnings.into_iter().map(StartupWarning::Broker));
1319    let broker = match secret_catalog {
1320        Some(catalog) => broker
1321            .with_secret_catalog(catalog)
1322            .map_err(|error| vec![BrokerdError::Broker(error)])?,
1323        None => broker,
1324    };
1325    let broker = match config.chat_memory {
1326        Some(memory) => broker
1327            .with_chat_memory(memory)
1328            .map_err(|error| vec![BrokerdError::Broker(error)])?,
1329        None => broker,
1330    };
1331    report.continuity = broker
1332        .continuity_report()
1333        .filter(|_| !secrets_unchecked)
1334        .cloned();
1335    let mut identities = BTreeMap::new();
1336    for identity in config.identities {
1337        identities.insert(
1338            identity.uid,
1339            MappedPeer {
1340                context: identity
1341                    .context()
1342                    .map_err(|error| vec![BrokerdError::Context(error)])?,
1343                attestor: identity.attestor,
1344            },
1345        );
1346    }
1347    validate_capability_responses(&broker, &identities, max_frame_bytes)
1348        .map_err(|error| vec![error])?;
1349    Ok(Ready {
1350        identity_digest: identity_digest.expect("a ready policy has an identity world"),
1351        broker: Arc::new(broker),
1352        scheduled: scheduled.unwrap_or_default(),
1353        chatgpt: runtime.chatgpt,
1354        identities,
1355        registry: shared_registry,
1356    })
1357}
1358
1359fn keep<T>(problems: &mut Vec<BrokerdError>, result: Result<T, BrokerdError>) -> Option<T> {
1360    result.map_err(|error| problems.push(error)).ok()
1361}
1362
1363fn build_policy(
1364    policies: &str,
1365    mut world: PolicyWorld,
1366    strict: bool,
1367    secrets_unchecked: bool,
1368    warnings: &mut Vec<StartupWarning>,
1369) -> Result<PolicyEngine, BrokerdError> {
1370    let mut admitted = BTreeSet::new();
1371    loop {
1372        let built = if strict {
1373            PolicyEngine::new(policies, &world).map(|policy| (policy, Vec::new()))
1374        } else {
1375            PolicyEngine::new_lenient(policies, &world)
1376        };
1377        let source = match built {
1378            Ok((policy, unresolved)) => {
1379                warnings.extend(unresolved.into_iter().map(|entry| {
1380                    StartupWarning::UnresolvedPolicyName {
1381                        policy: entry.policy,
1382                        kind: entry.kind.label(),
1383                        name: entry.name,
1384                    }
1385                }));
1386                return Ok(policy);
1387            }
1388            Err(source) => source,
1389        };
1390        let PolicyBuildError::UnknownSecret { policy, secret } = &source else {
1391            return Err(BrokerdError::Policy { source });
1392        };
1393        let drn = match secret.parse::<SecretDrn>() {
1394            Ok(drn) if secrets_unchecked && admitted.insert(drn.clone()) => drn,
1395            Ok(_) | Err(_) => return Err(BrokerdError::Policy { source }),
1396        };
1397        warnings.push(StartupWarning::SecretRequired {
1398            policy: policy.clone(),
1399            secret: secret.clone(),
1400        });
1401        world = world.with_secrets([drn]);
1402    }
1403}
1404
1405#[derive(Debug, Error)]
1406pub enum StartupWarning {
1407    #[error(
1408        "policy {policy} names {kind} {name:?}, which no loaded provider declares; it can never match"
1409    )]
1410    UnresolvedPolicyName {
1411        policy: String,
1412        kind: &'static str,
1413        name: String,
1414    },
1415    #[error("{0}")]
1416    UnloadedCapability(capabilities::CapabilityProblem),
1417    #[error("{0}")]
1418    Broker(dekopon_broker::StartupWarning),
1419    #[error(
1420        "the secret map is unreadable here, so no default secret was checked against its bindings; \
1421         boot refuses a default without exactly one"
1422    )]
1423    DefaultSecretsUnchecked,
1424    #[error("policy {policy} names secret {secret}; boot requires it in secretMapPath")]
1425    SecretRequired { policy: String, secret: String },
1426    #[error("no identities; boot requires them, from a fragment or the chart's peers.yaml")]
1427    IdentitiesRequired,
1428    #[error("{stage} not checked: a stage it needs failed")]
1429    Skipped { stage: Stage },
1430    #[error("attestor scope {scope} covers the kinds {}", kinds.join(", "))]
1431    ScopeKinds { scope: String, kinds: Vec<String> },
1432}
1433
1434impl StartupWarning {
1435    fn log(&self) {
1436        match self {
1437            Self::UnresolvedPolicyName { policy, kind, name } => tracing::warn!(
1438                target: "dekopon_brokerd::audit",
1439                {
1440                    audit.event = "policy.name.unresolved",
1441                    policy.id = %policy,
1442                    name.kind = kind,
1443                    name = %name,
1444                },
1445                "{self}"
1446            ),
1447            Self::UnloadedCapability(problem) => tracing::warn!(
1448                target: "dekopon_brokerd::audit",
1449                { audit.event = "config.startup.warning", reason = "unloaded-capability" },
1450                "{problem}"
1451            ),
1452            Self::Broker(warning) => tracing::warn!(
1453                target: "dekopon_brokerd::audit",
1454                {
1455                    audit.event = "config.startup.warning",
1456                    reason = warning.reason(),
1457                    capability.id = %warning.capability(),
1458                },
1459                "{warning}"
1460            ),
1461            Self::Skipped { .. } => tracing::warn!(
1462                target: "dekopon_brokerd::audit",
1463                { audit.event = "config.startup.warning", reason = "skipped-stage" },
1464                "{self}"
1465            ),
1466            Self::ScopeKinds { .. } => tracing::warn!(
1467                target: "dekopon_brokerd::audit",
1468                { audit.event = "config.startup.warning", reason = "wildcard-kind-scope" },
1469                "{self}"
1470            ),
1471            Self::DefaultSecretsUnchecked
1472            | Self::SecretRequired { .. }
1473            | Self::IdentitiesRequired => tracing::warn!(
1474                target: "dekopon_brokerd::audit",
1475                { audit.event = "config.startup.warning", reason = "unchecked-reference" },
1476                "{self}"
1477            ),
1478        }
1479    }
1480}
1481
1482fn validate_capability_responses<A: AuditLog>(
1483    broker: &Broker<A>,
1484    identities: &BTreeMap<u32, MappedPeer>,
1485    maximum: usize,
1486) -> Result<(), BrokerdError> {
1487    for peer in identities.values() {
1488        let (capabilities, command_words, command_word_help) =
1489            broker.capability_view(&peer.context);
1490        let response =
1491            ResponseEnvelope::capabilities(capabilities, command_words, command_word_help);
1492        let length = encoded_capability_response(&response)?;
1493        if length > maximum {
1494            return Err(BrokerdError::CapabilityResponseTooLarge { length, maximum });
1495        }
1496    }
1497    // Direct peers are granted almost nothing in a gateway deployment; the real capability sets are
1498    // reachable only through attested sessions that can't be enumerated at startup, so the broker
1499    // bounds their worst case instead.
1500    let (capabilities, command_words, command_word_help) = broker.capability_ceiling();
1501    let space = capabilities
1502        .iter()
1503        .map(|available| available.capability.id.clone())
1504        .collect();
1505    let response = ResponseEnvelope::chat_capabilities(
1506        capabilities,
1507        command_words,
1508        command_word_help,
1509        broker.chat_memory_ceiling(),
1510        broker.principal_ceiling(),
1511    )
1512    .with_space(Some(space));
1513    let length = encoded_capability_response(&response)?;
1514    if length > maximum {
1515        return Err(BrokerdError::CapabilityCeilingTooLarge { length, maximum });
1516    }
1517    Ok(())
1518}
1519
1520fn encoded_capability_response(response: &ResponseEnvelope) -> Result<usize, BrokerdError> {
1521    Ok(serde_json::to_vec(response)
1522        .map_err(|source| BrokerdError::CapabilityResponse { source })?
1523        .len())
1524}
1525
1526fn validate_manifest_metadata(
1527    registry: &BrokerProviderRegistry,
1528    maximum: usize,
1529) -> Result<(), BrokerdError> {
1530    let mut length = 0_usize;
1531    for manifest in registry.manifests() {
1532        let encoded = serde_json::to_vec(manifest)
1533            .map_err(|source| BrokerdError::ManifestMetadata { source })?;
1534        length =
1535            length
1536                .checked_add(encoded.len())
1537                .ok_or(BrokerdError::ManifestMetadataTooLarge {
1538                    length: usize::MAX,
1539                    maximum,
1540                })?;
1541        if length > maximum {
1542            return Err(BrokerdError::ManifestMetadataTooLarge { length, maximum });
1543        }
1544    }
1545    Ok(())
1546}
1547
1548#[derive(Debug, Error)]
1549pub enum BrokerdError {
1550    #[error("broker socket security validation failed")]
1551    Socket(#[from] SocketError),
1552    #[error("broker configuration is invalid")]
1553    Config(#[from] ConfigError),
1554    #[error("capability configuration is invalid: {}", render_problems(.problems))]
1555    Capabilities {
1556        problems: Vec<capabilities::CapabilityProblem>,
1557    },
1558    #[error("broker private secret map is unavailable or invalid")]
1559    Secrets(#[from] SecretMapError),
1560    #[error("broker provider storage could not start")]
1561    Storage(#[source] dekopon_storage_host::StorageHostError),
1562    #[error("broker storage reaper task failed")]
1563    StorageReaper(#[source] tokio::task::JoinError),
1564    #[error("broker assets could not start")]
1565    Assets(#[source] assets::AssetsStartupError),
1566    #[error("broker provider host could not start")]
1567    Host(#[source] dekopon_broker_host::BrokerHostError),
1568    #[error("broker generation snapshot could not be encoded")]
1569    Snapshot {
1570        #[source]
1571        source: serde_json::Error,
1572    },
1573    #[error("broker provider metadata could not be encoded")]
1574    ManifestMetadata {
1575        #[source]
1576        source: serde_json::Error,
1577    },
1578    #[error("broker provider metadata is {length} bytes; maximum is {maximum}")]
1579    ManifestMetadataTooLarge { length: usize, maximum: usize },
1580    #[error("broker capability response could not be encoded")]
1581    CapabilityResponse {
1582        #[source]
1583        source: serde_json::Error,
1584    },
1585    #[error("broker capability response is {length} bytes; frame maximum is {maximum}")]
1586    CapabilityResponseTooLarge { length: usize, maximum: usize },
1587    #[error(
1588        "broker could answer a session with a {length}-byte capability response; frame maximum is {maximum}"
1589    )]
1590    CapabilityCeilingTooLarge { length: usize, maximum: usize },
1591    #[error("broker policy could not start")]
1592    Broker(#[source] dekopon_broker::BrokerBuildError),
1593    #[error("broker policy set is invalid")]
1594    Policy {
1595        #[source]
1596        source: PolicyBuildError,
1597    },
1598    #[error("broker peer identity is invalid")]
1599    Context(#[source] dekopon_broker::ContextError),
1600    #[error(
1601        "broker socket parent grants no group traversal, so the socket is owner-only for server UID {server}; configured peer UID(s) {} can never connect",
1602        .configured.iter().map(u32::to_string).collect::<Vec<_>>().join(", ")
1603    )]
1604    UnreachablePeerUids { configured: Vec<u32>, server: u32 },
1605    #[error("broker server failed")]
1606    Server(#[from] ServerError),
1607    #[error("{}", render_errors(.problems))]
1608    Startup { problems: Vec<BrokerdError> },
1609    #[error("broker configuration changed restart-required categories: {categories:?}")]
1610    RestartRequired { categories: Vec<String> },
1611    #[error("the configuration names a providerSet; check it with --provider-set and --store")]
1612    ProviderSetRequired,
1613    #[error("the configuration names provider paths; --provider-set does not apply to it")]
1614    ProviderSetUnused,
1615    #[error("the provider set could not be resolved")]
1616    ProviderSet(#[source] ProviderManagerError),
1617    #[error(
1618        "the provider lock never read as one stable file; the broker drained so a restart rereads it"
1619    )]
1620    ProviderLockUnsettled,
1621    #[error("check could not prepare its private directory {path}")]
1622    CheckDirectory {
1623        path: PathBuf,
1624        #[source]
1625        source: std::io::Error,
1626    },
1627    #[error("essential workflows could not be loaded")]
1628    WorkflowFile(#[from] workflows::WorkflowFileError),
1629    #[error("would break essential workflows")]
1630    Workflow(#[source] workflows::StepRefusal),
1631}
1632
1633impl BrokerdError {
1634    fn from_problems(mut problems: Vec<Self>) -> Self {
1635        match (problems.pop(), problems.is_empty()) {
1636            (Some(only), true) => only,
1637            (Some(last), false) => {
1638                problems.push(last);
1639                Self::Startup { problems }
1640            }
1641            (None, _) => Self::Startup { problems },
1642        }
1643    }
1644}
1645
1646fn reload_entries(problem: &BrokerdError) -> Vec<String> {
1647    if let BrokerdError::Secrets(SecretMapError::Validation { problems }) = problem {
1648        problems
1649            .iter()
1650            .map(|item| format!("private secret map has conflicts: {item}"))
1651            .collect()
1652    } else if let BrokerdError::Capabilities { problems } = problem {
1653        problems
1654            .iter()
1655            .map(|item| format!("capability configuration is invalid: {item}"))
1656            .collect()
1657    } else if let BrokerdError::Config(error) = problem {
1658        vec![format!("{problem}: {error}")]
1659    } else if let BrokerdError::Secrets(error) = problem {
1660        vec![format!("{problem}: {error}")]
1661    } else {
1662        vec![problem.to_string()]
1663    }
1664}
1665
1666fn render_errors(problems: &[BrokerdError]) -> String {
1667    problems
1668        .iter()
1669        .map(|problem| error_chain(problem))
1670        .collect::<Vec<_>>()
1671        .join("; ")
1672}
1673
1674#[cfg(test)]
1675mod tests;
1676
1677fn render_problems(problems: &[capabilities::CapabilityProblem]) -> String {
1678    problems
1679        .iter()
1680        .map(ToString::to_string)
1681        .collect::<Vec<_>>()
1682        .join("; ")
1683}
1684
1685#[cfg(test)]
1686mod test_tls;