alien-signing 3.3.72

Signed statements, signer lists, signing settings and the install ledger for installs that run only what the vendor signed
Documentation
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
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
//! `release/v2`: what a release may run, workload by workload, and how an
//! enforcer builds a workload from it.
//!
//! The control plane still decides placement, replica counts within signed
//! bounds, and the values of the few environment variables the release names
//! exactly as provided. Everything that decides which code runs, how it is
//! loaded and which resources it reaches comes from the signed body or from
//! the enforcer itself: the image digest, the command, fixed environment
//! values, runtime privileges, mounts, identity, and binding values the
//! enforcer computes from its own install.

use std::collections::{BTreeMap, BTreeSet};

use alien_error::AlienError;
use serde::{Deserialize, Serialize};

use crate::envelope::Kind;
use crate::error::{ErrorData, Result};

/// Environment variables that change how a runtime loads code. They can only
/// come from the release itself: no control-plane value, config statement or
/// provided-name pattern may set them.
pub const LOADER_ENV: &[&str] = &[
    "LD_PRELOAD",
    "LD_LIBRARY_PATH",
    "LD_AUDIT",
    "LD_BIND_NOW",
    "LD_DEBUG",
    "LD_PROFILE",
    "DYLD_INSERT_LIBRARIES",
    "DYLD_LIBRARY_PATH",
    "NODE_OPTIONS",
    "NODE_PATH",
    "NODE_EXTRA_CA_CERTS",
    "NODE_TLS_REJECT_UNAUTHORIZED",
    "PYTHONPATH",
    "PYTHONHOME",
    "PYTHONSTARTUP",
    "PYTHONINSPECT",
    "PYTHONUSERBASE",
    "PYTHONWARNINGS",
    "PERL5OPT",
    "PERL5LIB",
    "PERLLIB",
    "RUBYOPT",
    "RUBYLIB",
    "JAVA_TOOL_OPTIONS",
    "JDK_JAVA_OPTIONS",
    "_JAVA_OPTIONS",
    "CLASSPATH",
    "DOTNET_STARTUP_HOOKS",
    "CORECLR_ENABLE_PROFILING",
    "CORECLR_PROFILER",
    "CORECLR_PROFILER_PATH",
    "BASH_ENV",
    "ENV",
    "PATH",
    "GCONV_PATH",
    "SSL_CERT_FILE",
    "SSL_CERT_DIR",
    "GIT_SSH_COMMAND",
    "PHPRC",
    "PHP_INI_SCAN_DIR",
    "BUN_OPTIONS",
    "DENO_DIR",
    "GLIBC_TUNABLES",
    "LOCPATH",
    "NLSPATH",
    "PYTHONBREAKPOINT",
    "PYTHONEXECUTABLE",
    "PYTHONPLATLIBDIR",
    "PERL5DB",
    "RUBYGEMS_GEMDEPS",
    "NODE_REPL_EXTERNAL_MODULE",
    "LUA_INIT",
    "LUA_PATH",
    "LUA_CPATH",
    "DOTNET_ADDITIONAL_DEPS",
    "DOTNET_SHARED_STORE",
    "COR_ENABLE_PROFILING",
    "COR_PROFILER",
    "COR_PROFILER_PATH",
];

/// Families of loader variables, by prefix: the dynamic linkers' and
/// exported shell functions.
pub const LOADER_ENV_PREFIXES: &[&str] = &["LD_", "DYLD_", "BASH_FUNC_", "CORECLR_"];

/// Names a request never fills, whatever the signed release says: the address
/// the worker runtime listens on, and the list of public URLs. Releases signed
/// before these left the provided list may still name them.
const NEVER_FROM_REQUEST: &[&str] = &["ALIEN_WORKER_GRPC_ADDRESS", "ALIEN_PUBLIC_ENDPOINTS_JSON"];

/// Whether the workload's runtime ships telemetry: a switch the deployment sets, which can't say
/// where the telemetry goes.
pub const RUNTIME_SEND_OTLP: &str = "ALIEN_RUNTIME_SEND_OTLP";

/// Whether `name` is a loader variable.
pub fn is_loader_env(name: &str) -> bool {
    LOADER_ENV.contains(&name)
        || LOADER_ENV_PREFIXES
            .iter()
            .any(|prefix| name.starts_with(prefix))
}

/// Components whose builds a release pins. An enforcer runs only a build
/// whose digest the release names. The verifier isn't one: setup pins it.
pub const COMPONENTS: &[&str] = &[
    "machine-agent/linux-x86_64",
    "machine-agent/linux-aarch64",
    "operator",
];

/// Setup templates a release can carry digests of.
pub const SETUP_TEMPLATES: &[&str] = &[
    "cloudformation",
    "terraform-aws",
    "terraform-gcp",
    "terraform-azure",
    "helm",
];

/// What one release lets run on one platform.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct ReleaseBody {
    /// Platform the release is for, such as `aws` or `machines`.
    pub platform: String,
    /// Release channel, such as `production`. An install accepts only the
    /// channel its setup pinned.
    pub channel: String,
    /// Every workload, by name.
    pub workloads: Vec<Workload>,
    /// What `config/v1` statements may set.
    #[serde(default)]
    pub configurable: Configurable,
    /// Digest of each enforcer build this release runs with, by name from
    /// [`COMPONENTS`].
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub components: BTreeMap<String, String>,
    /// Digests of the setup templates this release renders, by name from
    /// [`SETUP_TEMPLATES`], so a customer can check what they install.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub setup: BTreeMap<String, SetupTemplate>,
    /// The full stack, for enforcers that deploy from it. It is signed with
    /// the rest of the body, so it is as trusted as the workloads.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub stack: Option<serde_json::Value>,
}

/// One setup template as the release rendered it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SetupTemplate {
    /// `sha256:<hex>` of the rendered template bytes.
    pub sha256: String,
    /// Parameters (or Helm values) the customer may choose. Every other
    /// parameter must keep the template's pinned value.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub allowed: Vec<String>,
}

/// Names config statements may set.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Configurable {
    /// Environment variable names, applied to every workload that lists them
    /// in its own `configurableEnv`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub env: Vec<String>,
    /// Developer input ids.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub inputs: Vec<String>,
}

/// What kind of compute a workload is.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub enum WorkloadKind {
    /// A long-running container.
    Container,
    /// One container per machine.
    Daemon,
    /// A serverless function.
    Function,
    /// A sandbox runtime.
    Sandbox,
    /// A build environment.
    Build,
}

/// One workload, exactly as it may run.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Workload {
    /// Workload name, unique in the release.
    pub name: String,
    /// What kind of compute it is.
    pub kind: WorkloadKind,
    /// `<repository>@sha256:<hex>`.
    pub image: String,
    /// Command overriding the image's, if any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub command: Option<Vec<String>>,
    /// Fixed environment values.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub env: BTreeMap<String, String>,
    /// Exact environment names whose values the control plane provides.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub provided_env: Vec<String>,
    /// Resources the workload is bound to: resource id to resource type.
    /// The enforcer computes each binding's value from its own install, so
    /// the control plane can't point a binding at another resource.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub bindings: BTreeMap<String, String>,
    /// Environment names a config statement may set on this workload.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub configurable_env: Vec<String>,
    /// Environment names whose values come from deployer inputs, by input
    /// id. The enforcer reads the values from the customer's own store; the
    /// control plane never supplies them.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub deployer_env: BTreeMap<String, String>,
    /// Secrets the workload may receive, by name.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub secrets: Vec<SecretBinding>,
    /// Runtime privileges and mounts.
    #[serde(default)]
    pub runtime: Runtime,
    /// Where the workload's persistent volume is mounted, if it has one.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub volume_mount_path: Option<String>,
    /// Permission profile the workload runs as, if any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub identity: Option<String>,
    /// Upper bounds the control plane may scale within.
    #[serde(default)]
    pub bounds: Bounds,
    /// Function settings, for `function` workloads.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub function: Option<FunctionSettings>,
}

/// A secret the workload may receive. The value is not signed; the name and
/// where it lands are.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct SecretBinding {
    /// Secret name.
    pub name: String,
    /// Environment variable that receives the value, if any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub env_name: Option<String>,
    /// File the value is written to, if any.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub file_path: Option<String>,
}

/// Runtime privileges. The defaults are the unprivileged ones.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Runtime {
    /// Full host capabilities.
    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
    pub privileged: bool,
    /// `host` to share the host PID namespace.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub pid_namespace: Option<String>,
    /// `host` to share the host network namespace.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub network_mode: Option<String>,
    /// `uid[:gid]` to run as.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub user: Option<String>,
    /// Host bind mounts.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub mounts: Vec<Mount>,
    /// Hardened execution settings.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub security: Option<Security>,
    /// `internet` for public-internet-only egress.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub egress: Option<String>,
}

/// A host bind mount.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Mount {
    /// Host path.
    pub source: String,
    /// Path in the container.
    pub target: String,
    /// Mount options such as `ro`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub options: Option<String>,
}

/// Hardened execution settings.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Security {
    /// `restricted`, `restrictedInternet`, or `unrestricted` (the workload's opt-out).
    pub profile: String,
    /// User id; absent means the image's own non-root user.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run_as_user: Option<i64>,
    /// Group id; absent means the image's own group.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub run_as_group: Option<i64>,
    /// Whether the root filesystem is read-only; absent means the profile's default.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub read_only_root_filesystem: Option<bool>,
    /// Absolute paths backed by a writable emptyDir.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub writable_paths: Vec<String>,
}

/// Upper bounds on what the control plane may request.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Bounds {
    /// Most CPU per replica, as a quantity such as `2` or `500m`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_cpu: Option<String>,
    /// Most memory per replica, as a quantity such as `512Mi`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_memory: Option<String>,
    /// Most replicas.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub max_replicas: Option<u32>,
}

/// Settings of a serverless function that change what runs.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct FunctionSettings {
    /// Memory in MiB.
    pub memory_mb: u32,
    /// Timeout in seconds.
    pub timeout_seconds: u32,
    /// CPU architecture, such as `arm64`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub architecture: Option<String>,
}

impl ReleaseBody {
    /// The ids of the signed stack's Live resources, whose names their controllers choose.
    pub fn live_resources(&self) -> BTreeSet<String> {
        self.stack
            .as_ref()
            .and_then(|stack| stack.get("resources"))
            .and_then(|resources| resources.as_object())
            .into_iter()
            .flatten()
            .filter(|(_, entry)| entry["lifecycle"] == "live")
            .map(|(id, _)| id.clone())
            .collect()
    }

    /// Check the rules a release must follow before any of it is used.
    pub fn validate(&self) -> Result<()> {
        let mut names = BTreeSet::new();
        for workload in &self.workloads {
            if !names.insert(workload.name.as_str()) {
                return Err(body_refused(format!(
                    "workload '{}' appears twice",
                    workload.name
                )));
            }
            workload.validate()?;
            for name in &workload.configurable_env {
                if !self.configurable.env.contains(name) {
                    return Err(workload_refused(
                        &workload.name,
                        format!(
                            "configurable env '{name}' is not in the release's configurable env"
                        ),
                    ));
                }
            }
        }
        for name in &self.configurable.env {
            check_settable_name(name).map_err(body_refused)?;
        }
        if self.channel.is_empty()
            || !self
                .channel
                .bytes()
                .all(|byte| matches!(byte, b'a'..=b'z' | b'0'..=b'9' | b'-'))
        {
            return Err(body_refused(format!(
                "channel '{}' is not [a-z0-9-]",
                self.channel
            )));
        }
        for (name, digest) in &self.components {
            if !COMPONENTS.contains(&name.as_str()) {
                return Err(body_refused(format!("'{name}' is not a component")));
            }
            if !is_sha256_digest(digest) {
                return Err(body_refused(format!(
                    "'{name}' digest '{digest}' is not sha256:<hex>"
                )));
            }
        }
        for (name, template) in &self.setup {
            if !SETUP_TEMPLATES.contains(&name.as_str()) {
                return Err(body_refused(format!("'{name}' is not a setup template")));
            }
            if !is_sha256_digest(&template.sha256) {
                return Err(body_refused(format!(
                    "setup '{name}' digest '{}' is not sha256:<hex>",
                    template.sha256
                )));
            }
        }
        Ok(())
    }

    /// The workload named `name`.
    pub fn workload(&self, name: &str) -> Result<&Workload> {
        self.workloads
            .iter()
            .find(|workload| workload.name == name)
            .ok_or_else(|| {
                workload_refused(name, "the signed release has no workload by this name")
            })
    }
}

impl Workload {
    fn validate(&self) -> Result<()> {
        let refuse = |reason: String| workload_refused(&self.name, reason);
        if self.name.is_empty() {
            return Err(refuse("the name is empty".to_string()));
        }
        if !is_pinned_image(&self.image) {
            return Err(refuse(format!(
                "image '{}' is not pinned by sha256 digest",
                self.image
            )));
        }
        for name in self
            .provided_env
            .iter()
            .chain(&self.configurable_env)
            .chain(self.deployer_env.keys())
        {
            check_settable_name(name).map_err(refuse)?;
            if self.env.contains_key(name) {
                return Err(refuse(format!(
                    "'{name}' has a fixed value and can't also be provided or configured"
                )));
            }
        }
        for secret in &self.secrets {
            if let Some(env_name) = &secret.env_name {
                check_settable_name(env_name).map_err(refuse)?;
            }
            if let Some(path) = &secret.file_path {
                if !path.starts_with('/') || path.split('/').any(|part| part == "..") {
                    return Err(refuse(format!(
                        "secret file path '{path}' is not absolute and plain"
                    )));
                }
            }
        }
        if let Some(max_cpu) = &self.bounds.max_cpu {
            parse_cpu_millis(max_cpu).map_err(refuse)?;
        }
        if let Some(max_memory) = &self.bounds.max_memory {
            parse_memory_bytes(max_memory).map_err(refuse)?;
        }
        for (id, resource_type) in &self.bindings {
            if id.is_empty() || resource_type.is_empty() {
                return Err(refuse("a binding needs a resource id and type".into()));
            }
            let name = crate::binding::binding_env_name(id);
            if self.env.contains_key(&name) || self.provided_env.contains(&name) {
                return Err(refuse(format!(
                    "{name} is a binding the enforcer computes; it can't also be fixed or provided"
                )));
            }
        }
        if (self.kind == WorkloadKind::Function) != self.function.is_some() {
            return Err(refuse(
                "function settings are required on functions and only on functions".into(),
            ));
        }
        Ok(())
    }
}

/// What the control plane supplies when it asks an enforcer to run one
/// replica of a workload. Nothing here can change the code that runs.
#[derive(Debug, Clone, Default)]
pub struct WorkloadRequest {
    /// The full environment the control plane computed. Signed names must
    /// carry their signed value; other names must be provided or configured.
    pub env: BTreeMap<String, String>,
    /// Secrets the control plane delivers, by name, with where they land.
    pub secrets: Vec<RequestedSecret>,
    /// CPU per replica.
    pub cpu: Option<String>,
    /// Memory per replica.
    pub memory: Option<String>,
    /// Replica count the control plane wants.
    pub replicas: Option<u32>,
}

/// Values the enforcer reads or computes itself, never from the control
/// plane.
#[derive(Debug, Clone, Default)]
pub struct LocalValues {
    /// The env the release's deployer inputs resolve to for this workload, by env name: the
    /// customer's stored value or the signed default. A name left out here is a variable the
    /// install does not set (an optional input with neither, or one whose `when` is off).
    pub deployer_env: BTreeMap<String, String>,
    /// Binding values, by environment name, from [`crate::resolve_bindings`].
    pub bindings: BTreeMap<String, String>,
    /// What the workload's own binding is checked against.
    pub own_binding: crate::binding::OwnBindingFacts,
}

/// A secret delivery the control plane asks for.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RequestedSecret {
    /// Secret name.
    pub name: String,
    /// Environment variable that receives it.
    pub env_name: Option<String>,
    /// File it is written to.
    pub file_path: Option<String>,
}

/// A workload built from its signed release.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BuiltWorkload {
    /// Workload name.
    pub name: String,
    /// The signed image.
    pub image: String,
    /// The signed command.
    pub command: Option<Vec<String>>,
    /// Signed values, then configured values, then provided values.
    pub env: BTreeMap<String, String>,
    /// The signed runtime.
    pub runtime: Runtime,
    /// The signed volume mount path.
    pub volume_mount_path: Option<String>,
    /// The signed permission profile.
    pub identity: Option<String>,
}

/// Build workload `name` from a verified release, applying config values
/// from a verified `config/v1`, the values the enforcer computed itself, and
/// the values the control plane provides.
///
/// A request that tries to change a signed or computed value, set a name the
/// release doesn't let it set, deliver an unbound secret or go past a bound
/// is refused, so the attempt is reported rather than silently dropped.
pub fn build_workload(
    release: &ReleaseBody,
    name: &str,
    config_env: &BTreeMap<String, String>,
    local: &LocalValues,
    request: &WorkloadRequest,
) -> Result<BuiltWorkload> {
    let workload = release.workload(name)?;
    let refuse = |reason: String| workload_refused(name, reason);

    let mut env = workload.env.clone();
    for (key, value) in config_env {
        if workload.configurable_env.contains(key) {
            env.insert(key.clone(), value.clone());
        }
    }
    for id in workload.bindings.keys() {
        let key = crate::binding::binding_env_name(id);
        let value = local.bindings.get(&key).ok_or_else(|| {
            refuse(format!(
                "the enforcer has no value for binding '{id}' ({key})"
            ))
        })?;
        env.insert(key, value.clone());
    }
    for key in workload.deployer_env.keys() {
        if let Some(value) = local.deployer_env.get(key) {
            env.insert(key.clone(), value.clone());
        }
    }
    let own_binding = crate::binding::binding_env_name(name);
    for (key, value) in &request.env {
        // Deployer inputs come from the customer's store; whatever the
        // control plane sends for them is ignored.
        if workload.deployer_env.contains_key(key) {
            continue;
        }
        if let Some(signed) = env.get(key) {
            if !same_value(signed, value) {
                return Err(refuse(format!(
                    "env {key} differs from its signed, configured or computed value"
                )));
            }
            continue;
        }
        if workload.configurable_env.contains(key) {
            return Err(refuse(format!(
                "env {key} is configurable and only a signed config statement may set it"
            )));
        }
        // The workload's own binding only describes the workload to itself.
        if *key == own_binding {
            crate::binding::check_own_binding(value, &local.own_binding).map_err(|reason| {
                refuse(format!(
                    "env {key} is the workload's own binding but {reason}"
                ))
            })?;
            env.insert(key.clone(), value.clone());
            continue;
        }
        // Whether the runtime ships telemetry at all; where it goes is never the request's.
        if key == RUNTIME_SEND_OTLP {
            if value != "true" && value != "false" {
                return Err(refuse(format!(
                    "env {key} is a switch, true or false, not '{value}'"
                )));
            }
            env.insert(key.clone(), value.clone());
            continue;
        }
        if NEVER_FROM_REQUEST.contains(&key.as_str()) {
            return Err(refuse(format!(
                "env {key} is set by the runtime, not by the control plane"
            )));
        }
        if is_loader_env(key) || !workload.provided_env.contains(key) {
            return Err(refuse(format!("env {key} is not in the signed release")));
        }
        env.insert(key.clone(), value.clone());
    }

    for secret in &request.secrets {
        let bound = workload.secrets.iter().any(|binding| {
            binding.name == secret.name
                && binding.env_name == secret.env_name
                && binding.file_path == secret.file_path
        });
        if !bound {
            return Err(refuse(format!(
                "secret '{}' is not bound to this workload at that location",
                secret.name
            )));
        }
    }

    if let (Some(cpu), Some(max)) = (&request.cpu, &workload.bounds.max_cpu) {
        if parse_cpu_millis(cpu).map_err(refuse)? > parse_cpu_millis(max).map_err(refuse)? {
            return Err(refuse(format!("cpu {cpu} is above the signed bound {max}")));
        }
    }
    if let (Some(memory), Some(max)) = (&request.memory, &workload.bounds.max_memory) {
        if parse_memory_bytes(memory).map_err(refuse)? > parse_memory_bytes(max).map_err(refuse)? {
            return Err(refuse(format!(
                "memory {memory} is above the signed bound {max}"
            )));
        }
    }
    if let (Some(replicas), Some(max)) = (request.replicas, workload.bounds.max_replicas) {
        if replicas > max {
            return Err(refuse(format!(
                "{replicas} replicas is above the signed bound {max}"
            )));
        }
    }

    Ok(BuiltWorkload {
        name: workload.name.clone(),
        image: workload.image.clone(),
        command: workload.command.clone(),
        env,
        runtime: workload.runtime.clone(),
        volume_mount_path: workload.volume_mount_path.clone(),
        identity: workload.identity.clone(),
    })
}

/// Whether two values of one variable are the same. Binding values are JSON
/// whose key order the control plane may not keep, so JSON objects compare
/// by content.
fn same_value(expected: &str, actual: &str) -> bool {
    if expected == actual {
        return true;
    }
    match (
        serde_json::from_str::<serde_json::Value>(expected),
        serde_json::from_str::<serde_json::Value>(actual),
    ) {
        (Ok(left @ serde_json::Value::Object(_)), Ok(right)) => left == right,
        _ => false,
    }
}

/// Whether `image` is `<repository>@sha256:<64 hex>`.
pub fn is_pinned_image(image: &str) -> bool {
    image
        .rsplit_once('@')
        .is_some_and(|(repository, digest)| !repository.is_empty() && is_sha256_digest(digest))
}

/// Whether `digest` is `sha256:<64 lowercase hex>`.
pub fn is_sha256_digest(digest: &str) -> bool {
    digest.strip_prefix("sha256:").is_some_and(|hex_part| {
        hex_part.len() == 64
            && hex_part
                .bytes()
                .all(|byte| matches!(byte, b'0'..=b'9' | b'a'..=b'f'))
    })
}

fn check_settable_name(name: &str) -> std::result::Result<(), String> {
    if name.is_empty() || name.contains('=') || name.contains('\0') {
        return Err(format!("'{name}' is not a valid environment variable name"));
    }
    if is_loader_env(name) {
        return Err(format!(
            "{name} changes how code loads and can only have a fixed value"
        ));
    }
    if is_enforcer_env(name) {
        return Err(format!(
            "{name} is set by the enforcer from the signed release and can't be provided or configured"
        ));
    }
    Ok(())
}

/// Names the enforcer fills itself: the vault secrets list and binding values.
/// A control plane that could set them would pick which vault keys load or
/// where a binding points.
fn is_enforcer_env(name: &str) -> bool {
    matches!(name, "ALIEN_SECRETS" | "WORKLOAD_SECRETS")
        || name
            .strip_prefix("ALIEN_")
            .is_some_and(|rest| rest.len() > "_BINDING".len() && rest.ends_with("_BINDING"))
}

/// CPU quantity in millicores: `2`, `0.5` or `500m`.
pub fn parse_cpu_millis(quantity: &str) -> std::result::Result<u64, String> {
    let invalid = || format!("'{quantity}' is not a CPU quantity");
    if let Some(millis) = quantity.strip_suffix('m') {
        return millis.parse().map_err(|_| invalid());
    }
    let (whole, fraction) = quantity.split_once('.').unwrap_or((quantity, ""));
    if fraction.len() > 3 || (whole.is_empty() && fraction.is_empty()) {
        return Err(invalid());
    }
    let whole: u64 = if whole.is_empty() {
        0
    } else {
        whole.parse().map_err(|_| invalid())?
    };
    let fraction: u64 = if fraction.is_empty() {
        0
    } else {
        format!("{fraction:0<3}").parse().map_err(|_| invalid())?
    };
    whole
        .checked_mul(1000)
        .and_then(|millis| millis.checked_add(fraction))
        .ok_or_else(invalid)
}

/// Memory quantity in bytes: a number with an optional `Ki`/`Mi`/`Gi`/`Ti`
/// or `K`/`M`/`G`/`T` suffix.
pub fn parse_memory_bytes(quantity: &str) -> std::result::Result<u64, String> {
    let invalid = || format!("'{quantity}' is not a memory quantity");
    const UNITS: &[(&str, u64)] = &[
        ("Ki", 1 << 10),
        ("Mi", 1 << 20),
        ("Gi", 1 << 30),
        ("Ti", 1 << 40),
        ("K", 1_000),
        ("M", 1_000_000),
        ("G", 1_000_000_000),
        ("T", 1_000_000_000_000),
    ];
    let (number, multiplier) = UNITS
        .iter()
        .find_map(|(suffix, multiplier)| {
            quantity
                .strip_suffix(suffix)
                .map(|number| (number, *multiplier))
        })
        .unwrap_or((quantity, 1));
    let number: u64 = number.parse().map_err(|_| invalid())?;
    number.checked_mul(multiplier).ok_or_else(invalid)
}

fn body_refused(reason: String) -> AlienError<ErrorData> {
    AlienError::new(ErrorData::BodyRefused {
        kind: Kind::Release.as_str().to_string(),
        reason,
    })
}

fn workload_refused(workload: &str, reason: impl Into<String>) -> AlienError<ErrorData> {
    AlienError::new(ErrorData::WorkloadRefused {
        workload: workload.to_string(),
        reason: reason.into(),
    })
}