feat: add the module configuration and secrets contract
CI / verify (pull_request) Successful in 35s
CI / infrastructure-smoke (pull_request) Successful in 21s
CI / migration-smoke (pull_request) Successful in 46s

Modules had no way to be told anything. Announcements — the first real
product Ekklesia will absorb — has zero environment variables and compiles
a LAN IP address into its source, so this is the contract standing between
it and the module system.

- A module declares what it needs in its manifest, using six bounded types
  (string, integer, boolean, enum, url, secret) with no nesting and no
  regular expressions. Static declaration is what lets the platform validate
  configuration *before* deciding whether a module may start: an enabled
  module missing a required value is reported `blocked ·
  configuration_missing · <key>` rather than taking startup down from inside
  its own `start` hook, and Doctor reports the same while still importing no
  module code. That forces `manifestVersion: 5`, a hard cutover.
- Ordinary values persist in one Core table (migration 0005), one row per
  (module_id, key), stored as text until validated against the declaring
  module's current manifest. Nothing is coerced; an invalid stored value
  blocks the module rather than falling back to the default. A key the
  manifest no longer declares is retained and ignored.
- Secrets are never persisted. There is no encryption at rest in this
  repository, so a `secret` key is deployment-supplied and mapped in by the
  host under a name the module never sees. A secret declaration has no
  `default` field, the write API refuses secret material, and the HTTP view
  has no `value` field for one — absent by construction, not filtered.
- Modules receive a frozen `context.config` on the registration, runtime,
  and HTTP handler contexts: the same object identity, per module, beside
  `services` rather than inside it (services is deliberately one shared
  instance). No environment access, no database reference, no way to reach
  another module's values.
- Configuration decides eligibility through ADR 0028's existing resolver:
  three new blocked reasons, each with a distinct operator fix, propagating
  to required dependents through the same mechanism as a disabled module.
- Changes take effect at the next restart; both resources report
  restartRequired. New restricted permission
  `core.modules.configuration.manage`, separate from lifecycle, at the
  sibling prefix `/api/v1/module-configuration`.
- Migration participation stays independent of configuration validity.
  Endpoints and credentials for shared infrastructure stay platform
  concerns; a module declares which bucket it needs, not an S3 endpoint.

See ADR 0029.

Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
2026-08-22 21:44:43 -05:00
co-authored by Claude Opus 5
parent fdaad58848
commit baa689b2a7
76 changed files with 6650 additions and 131 deletions
+50
View File
@@ -195,6 +195,56 @@ enforced against that module's own declared permission, and a disabled module's
registered and grantable precisely so that an enable/disable cycle changes nothing about who holds
what.
### Ekklesia does not store module secrets, and does not pretend to
A module declares a `secret` configuration key; the **deployment** supplies its value, and Ekklesia
never persists it ([ADR 0029](../architecture/decisions/0029-module-configuration-and-secrets.md)).
This is a deliberate limit, not an oversight. **There is no encryption at rest in this repository and
no key management** — no cipher, no KMS, no keyring. Storing credentials in a PostgreSQL column
because one is easy to add would be worse than not offering the feature, and calling such a column a
"secret store" would be worse still.
What that buys, structurally rather than by discipline:
- a `secret` declaration has no `default` field, so a checked-in default credential is
unrepresentable;
- the resolver never reads a secret from storage, so a row planted directly in the database by
someone with database access is ignored rather than used;
- the HTTP view has no `value` field for a secret, so a secret is **absent from responses by
construction**, not filtered by a branch someone could later delete;
- the write API refuses a `secret` key outright (`CONFIGURATION_SECRET_NOT_WRITABLE`);
- Doctor prints keys and reasons, never values.
A module reaches its own secrets through `config.getSecret("key")` and nothing else. There is no
`getEnv`, no arbitrary variable lookup, and no cross-module accessor: the secret source is asked for a
module id **and** a key that module's own manifest declares, so a module cannot read `DATABASE_URL`,
the identity signing secret, or another module's credential.
**What this does not claim.** A module is still trusted code in the API process (see above), so a
malicious module could read `process.env` directly and obtain anything the process can. Scoped secret
delivery is a correctness and portability boundary, exactly like every other module-facing mechanism
here — not a sandbox. What it does guarantee is that Ekklesia itself never writes a credential to
disk, never serves one over HTTP, and never prints one in diagnostics.
### Module configuration is operator input, and is treated as such
Ordinary configuration values *are* persisted, and are validated against the declaring module's own
manifest before anything reads them. A stored value that does not satisfy its declaration blocks the
module rather than being coerced, truncated, or silently replaced by a default.
Configuration keys are **data, never SQL identifiers** — there is no dynamic SQL in this domain — and
are rejected unless they match a closed lower-camelCase grammar that also excludes reserved object
property names (`__proto__`, `constructor`, `prototype`, ...). Core additionally never indexes a plain
object with a module-supplied key; every lookup goes through a `Map`. Store errors never carry the
offending value, because an operator-entered value may be a credential that ended up in the wrong
field.
Reading or changing configuration requires `core.modules.configuration.manage` (baseline
`restricted`), separately from `core.modules.lifecycle.manage`. Mutations require an exact trusted
`Origin` and a bounded body, like every other Core mutation. Module UI receives no configuration at
all in this phase.
### Client-side permission checks are not a security boundary
A host may tell a module UI what permissions it believes the viewer holds