A secret reaches a process as a file (ADR 0086, closes issue 041) #35

2026-09-21T08:44:06Z

jschoubben commented

2026-09-21 08:44:06 +00:00

novox/hq ADR 0086. Merge first of four (mesh-controller → mesh-catalog → mesh-host → hq).

internal/envfile: a _FILE twin for every controller setting that carries a credential (broker AMQP, management, address), like the store connections already had.
The catalogue engine refuses ${secret:…} in a container's env outright, and a secret-carrying file named in env-file unless the container declares secrets-in-environment with a reason — a catalogue-level key, stripped before the host sees it.
secrets-owner: a module names who its secret files belong to, so a process that is not root can read the file the host wrote (the controller runs as 65534).
The controller's own root manifest reads its six credentials from mounted files. (The catalogue holds a second copy of this manifest; hq issue 072.)

Proven by the one-node genesis bed: genesis, controller rebuilt from source on the new shape, module run, and root secrets all green.

novox/hq ADR 0086. Merge first of four (mesh-controller → mesh-catalog → mesh-host → hq). - `internal/envfile`: a `_FILE` twin for every controller setting that carries a credential (broker AMQP, management, address), like the store connections already had. - The catalogue engine refuses `${secret:…}` in a container's `env` outright, and a secret-carrying file named in `env-file` unless the container declares `secrets-in-environment` with a reason — a catalogue-level key, stripped before the host sees it. - `secrets-owner`: a module names who its secret files belong to, so a process that is not root can read the file the host wrote (the controller runs as 65534). - The controller's own root manifest reads its six credentials from mounted files. (The catalogue holds a second copy of this manifest; hq issue 072.) Proven by the one-node genesis bed: genesis, controller rebuilt from source on the new shape, module run, and root secrets all green.

jschoubben added 3 commits 2026-09-21 08:44:06 +00:00

A secret reaches a process as a file (ADR 0086) 4531f2244f

The broker settings take a _FILE twin like the store connections; the
catalogue engine refuses a secret placeholder in a container's env and a
secret-carrying env-file unless the container says why with
secrets-in-environment, which stays in the catalogue and never reaches the
machine.

A module names who its secret files belong to (secrets-owner) 69bb0fcb67

The control plane runs as 65534 and crash-looped on permission denied the
first time its credentials were mounted as files the host wrote as root at
0600 — the env-file shape hid this because the daemon reads an env-file on
the host side. The composer now gives a module's secret files the owner the
manifest names.

The controller's own manifest reads its credentials from files too 67de216160

The mesh-controller repository carries the manifest the mesh builds the
controller from; the catalogue's copy is what genesis registers. The two must
say the same thing, and the first rebuild from source proved they did not.

jschoubben merged commit 153990348c into main

2026-09-21 09:59:02 +00:00

jschoubben deleted branch feat/secret-not-in-environment

2026-09-21 09:59:02 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: novox/mesh-controller#35