novox/mesh-host
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

A secret can reach a container's environment, and sit inside a config file

Browse Source 
Two gaps found by writing the first real module's manifest rather than
by reasoning about one. Both are fields on existing shapes, so the
vocabulary is still nine.

**env-file on a container.** A declaration reaches a node over the
broker and `env` is plain text in it, so a password there is a password
the broker sees — the transitive trust refused everywhere else. A sealed
file arrives unreadable, the host writes it, the runtime reads it. It is
also simply how third-party software takes credentials: nothing shipping
in a container will read a path the mesh invented, and every one of them
reads its environment.

**secrets in a file's content.** A program wanting its token inside a
JSON document cannot be handed a file that is entirely a token, and the
mesh cannot compose the document because it discarded the value. So the
module supplies the document with `${secret:name}` in it, the mesh
delivers the value sealed, and the host is the only thing that ever
holds both.

Substitution is textual and the host learns no formats. Deliberate: a
mechanism that understood JSON would be asked to understand YAML next,
and then INI, which is how the arrangement this replaces became
something nobody could hold in their head. The module knows its own
format because it wrote the rest of the file. The sharp edge is stated
rather than left to be discovered — a value containing a quote is not
escaped for whatever surrounds it.

Refused in both directions, because both are somebody being wrong about
where a credential is: a placeholder with nothing to fill it would write
`${secret:x}` into a config file, and a secret the content never uses
means somebody believes a credential is in a file where it is not.

A file that carries one is 0600 unless the module said otherwise.
This commit is contained in:
jschoubben
2026-08-31 22:25:57 +02:00
parent f48e06473d
commit 8c248e3d7f
4 changed files with 207 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
internal/declaration/declaration.go
+74 -5
View File
@@ -12,6 +12,8 @@ import (
"fmt"
"io"
"reflect"
"regexp"
"slices"
"sort"
"strings"
)
@@ -118,6 +120,23 @@ type File struct {
// by looking rather than by knowing which field won.
Sealed string `json:"sealed,omitempty"`
// Secrets are sealed values put into Content where it says `${secret:name}`.
//
// **The one place a secret and a configuration meet, and it happens on the machine.** A
// program that wants its token inside a JSON document cannot be given a file that is entirely
// a token, and the mesh cannot compose the document itself — it discarded the value
// (novox/hq ADR 0024). So the module supplies the document with a hole in it, the mesh
// delivers the value sealed, and the host is the only thing that ever sees both.
//
// **Substitution is textual and the host learns no formats.** That is deliberate: a mechanism
// that understood JSON would be asked to understand YAML next, and then INI, which is how the
// arrangement this replaces became something nobody could hold in their head. The module knows
// its own format, because it wrote the rest of the file.
//
// The sharp edge, stated rather than discovered: a value containing a quote or a backslash
// will not be escaped for whatever syntax surrounds it.
Secrets map[string]string `json:"secrets,omitempty"`
// Bytes is content that is not text, base64-encoded — a wallpaper, a font, an icon.
//
// A third way of saying what is in a file, and the three are exclusive. It would have been
@@ -137,6 +156,22 @@ func (f *File) Identity() string { return f.ID }
func (f *File) Kind() Type { return TypeFile }
func (f *File) Target() string { return f.Path }
// placeholder is what Content says where a sealed value belongs: ${secret:name}.
var placeholder = regexp.MustCompile(`\$\{secret:([a-z0-9][a-z0-9-]*)\}`)
// SecretsUsed are the names Content asks for, in the order they first appear.
func (f *File) SecretsUsed() []string {
var used []string
seen := map[string]bool{}
for _, m := range placeholder.FindAllStringSubmatch(f.Content, -1) {
if !seen[m[1]] {
seen[m[1]] = true
used = append(used, m[1])
}
}
return used
}
func (f *File) validate(where string, _ bool) []string {
var problems []string
if f.Path == "" {
@@ -157,6 +192,29 @@ func (f *File) validate(where string, _ bool) []string {
strings.Join(said, " and ")+
" — otherwise nobody can tell by looking which one landed on the machine")
}
// A file whose content names a secret must be given exactly the secrets it names.
//
// **Both directions, and both are refusals rather than warnings.** A placeholder with nothing
// to fill it would write `${secret:x}` into a configuration file, which the program reads as
// a value and fails on somewhere unrelated. A secret nobody uses means whoever wrote this
// believes a credential is in a file where it is not.
if len(f.Secrets) > 0 && f.Content == "" {
problems = append(problems, where+
": secrets were given and there is no content to put them in")
}
used := f.SecretsUsed()
for _, name := range used {
if f.Secrets[name] == "" {
problems = append(problems, fmt.Sprintf(
"%s: the content asks for the secret %q and none was given", where, name))
}
}
for name := range f.Secrets {
if !slices.Contains(used, name) {
problems = append(problems, fmt.Sprintf(
"%s: the secret %q was given and the content never asks for it", where, name))
}
}
return append(problems, checkMode(where, f.Mode)...)
}
@@ -364,11 +422,22 @@ type Container struct {
Type Type `json:"type"`
Name string `json:"name"`
// Image is pinned by digest (novox/hq ADR 0006) — a tag moves and a digest does not.
Image string `json:"image"`
Env map[string]string `json:"env,omitempty"`
Ports []string `json:"ports,omitempty"`
Volumes []string `json:"volumes,omitempty"`
Args []string `json:"args,omitempty"`
Image string `json:"image"`
Env map[string]string `json:"env,omitempty"`
// EnvFile names files the runtime reads environment from, in order.
//
// **Because a secret may not travel in Env.** A declaration reaches a node over the broker,
// and `env` is plain text in it — so a password there is a password the broker sees, which is
// the transitive trust refused everywhere else (novox/hq ADR 0004). A sealed file reaches the
// machine unreadable, the host writes it, and the runtime reads it: the mesh never holds it
// and neither does anything between them.
//
// It is also simply how third-party software takes credentials. Nothing that ships in a
// container will read a path the mesh invented; every one of them reads its environment.
EnvFile []string `json:"env-file,omitempty"`
Ports []string `json:"ports,omitempty"`
Volumes []string `json:"volumes,omitempty"`
Args []string `json:"args,omitempty"`
// Names this container can reach, as `name:address`.
//
// **Because a container does not inherit the machine's names.** It gets its own `/etc/hosts`