feat: add the module configuration and secrets contract
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
co-authored by
Claude Opus 5
Claude Opus 5
parent
fdaad58848
commit
baa689b2a7
+120
-4
@@ -82,6 +82,8 @@ No real values are shown here — configure per environment and never commit the
|
||||
| `GET /api/v1/module-ui/<module-id>/<version>` | Ekklesia | Publishes an installed module's validated `entrypoints.ui` artifact at a browser-loadable URL. No authentication; only the declared artifact, never another file. See [Module UI asset publication](#module-ui-asset-publication). |
|
||||
| `GET /api/v1/module-lifecycle` | Ekklesia | Which installed modules are enabled, what this process actually did with each, and whether a restart is pending. Requires `core.modules.lifecycle.manage` (baseline `restricted`). See [Module lifecycle](#module-lifecycle). |
|
||||
| `PUT /api/v1/module-lifecycle/<module-id>/enabled` | Ekklesia | Enable or disable one installed module. Takes effect at the next API start. Requires `core.modules.lifecycle.manage` and a trusted `Origin`. See [Module lifecycle](#module-lifecycle). |
|
||||
| `GET /api/v1/module-configuration/<module-id>` | Ekklesia | One module's declared configuration schema, its stored values, and whether a restart is pending. Never returns a secret value. Requires `core.modules.configuration.manage` (baseline `restricted`). See [Module configuration](#module-configuration). |
|
||||
| `PUT /api/v1/module-configuration/<module-id>` | Ekklesia | Replace one module's stored configuration. Takes effect at the next API start. Requires `core.modules.configuration.manage` and a trusted `Origin`. See [Module configuration](#module-configuration). |
|
||||
|
||||
Better Auth's handler is unreachable outside `/api/auth/*`; every other unmatched path returns a
|
||||
deterministic `404 {"code":"NOT_FOUND"}`.
|
||||
@@ -387,9 +389,12 @@ account.
|
||||
3. Construct the module database facade and the frozen `ModuleRuntimeServices` object from that same
|
||||
pool (see [Module database access](#module-database-access)).
|
||||
4. Construct the Core identity runtime, authorization store, and evaluator.
|
||||
5. Read the stored module enablement configuration and resolve, over that exact same discovered
|
||||
inventory, which modules are **eligible** to run (`resolveModuleEligibility`,
|
||||
`@ekklesia/core/modules` — see [Module lifecycle](#module-lifecycle)).
|
||||
5. Read the stored module enablement configuration and then the stored module configuration, and
|
||||
resolve, over that exact same discovered inventory, which modules are **eligible** to run and
|
||||
what each eligible module's frozen configuration snapshot is (`resolveModuleEligibility`,
|
||||
`@ekklesia/core/modules` — see [Module lifecycle](#module-lifecycle) and
|
||||
[Module configuration](#module-configuration)). The two reads are sequential rather than raced so
|
||||
a broken deployment reports the same error code every time.
|
||||
6. Start the module runtime from the eligible subset (`startDiscoveredModuleRuntime`) — modules are
|
||||
never rediscovered for this step — passing it the services object every module's `start`/`stop`
|
||||
hook receives.
|
||||
@@ -417,7 +422,8 @@ disabled, or blocked by a disabled required dependency, is never imported at all
|
||||
|
||||
Step 5 makes startup depend on a reachable, migrated database: if the enablement configuration
|
||||
cannot be read, `startApi` **refuses to start** with Core's sanitized `MODULE_LIFECYCLE_READ_FAILED`
|
||||
rather than starting every discovered module. The platform cannot know what an administrator
|
||||
(and `MODULE_CONFIGURATION_READ_FAILED` if the enablement read succeeded and the configuration read
|
||||
did not) rather than starting every discovered module. The platform cannot know what an administrator
|
||||
decided, and starting a module they disabled is worse than not starting. Nothing is created or
|
||||
repaired on that path.
|
||||
|
||||
@@ -548,6 +554,116 @@ pnpm modules:enable -- --module announcements
|
||||
It reads `DATABASE_URL`, runs the same manifest-only discovery the API does (so it refuses a module
|
||||
this deployment cannot see), writes the decision, and starts nothing. Restart the API to apply it.
|
||||
|
||||
## Module configuration
|
||||
|
||||
```text
|
||||
GET /api/v1/module-configuration/<module-id>
|
||||
PUT /api/v1/module-configuration/<module-id> { "values": { "slideSeconds": 12 } }
|
||||
```
|
||||
|
||||
What one installed module declares it needs configured, what an operator has stored, and whether the
|
||||
running process is still using it
|
||||
([ADR 0029](../architecture/decisions/0029-module-configuration-and-secrets.md)).
|
||||
|
||||
A **sibling** of `/api/v1/modules/`, never a child, for the same reason `/api/v1/module-ui` and
|
||||
`/api/v1/module-lifecycle` are: `config` and `configuration` are legal module route segments, so a
|
||||
module could otherwise collide with the platform at `/api/v1/modules/<id>/config`.
|
||||
|
||||
```json
|
||||
{
|
||||
"moduleId": "announcements",
|
||||
"version": "1.0.0",
|
||||
"keys": [
|
||||
{ "key": "slideSeconds", "type": "integer", "required": false, "default": 7,
|
||||
"description": "How long each slide is shown.", "configured": false },
|
||||
{ "key": "bucket", "type": "string", "required": true, "value": "slides", "configured": true },
|
||||
{ "key": "storageCredential", "type": "secret", "required": true, "configured": true }
|
||||
],
|
||||
"unknownKeys": [],
|
||||
"restartRequired": false
|
||||
}
|
||||
```
|
||||
|
||||
### A secret's value is absent, not redacted
|
||||
|
||||
Note what the `storageCredential` entry above does **not** have: a `value` field. Not `null`, not
|
||||
`"***"` — absent. Ekklesia never persists secret material, so the store this route reads from
|
||||
contains none, and there is no code path that could serve one. `configured` answers the only question
|
||||
an operator needs from here: does the deployment supply it?
|
||||
|
||||
### The declared types
|
||||
|
||||
| type | notes |
|
||||
| --- | --- |
|
||||
| `string` | optional `minLength` / `maxLength` |
|
||||
| `integer` | optional `minimum` / `maximum`; submitted as a JSON number, never a string |
|
||||
| `boolean` | submitted as a JSON boolean |
|
||||
| `enum` | closed `values` list |
|
||||
| `url` | absolute `http:`/`https:` only |
|
||||
| `secret` | deployment-supplied; never stored, never returned, never defaulted |
|
||||
|
||||
No nesting, no arrays, no regular expressions. This is a validation vocabulary, not a form-builder
|
||||
DSL; a module needing structured data owns a table for it.
|
||||
|
||||
### Writing is a whole-document replace, with closed validation
|
||||
|
||||
A key the module does not declare is `400 CONFIGURATION_KEY_UNDECLARED`. A wrong JSON type or a value
|
||||
failing the module's own declared constraints is `400 CONFIGURATION_VALUE_INVALID`. A `secret` key is
|
||||
`400 CONFIGURATION_SECRET_NOT_WRITABLE` — there is no supported way to submit secret material to this
|
||||
platform. Nothing is coerced: `{"slideSeconds": "7"}` is a `400`, not a silent `7`.
|
||||
|
||||
Constraint checking runs through **the same resolver startup uses**, over the exact document about to
|
||||
be stored, so the API and startup can never disagree about whether a value is valid.
|
||||
|
||||
An *incomplete* document is accepted deliberately — an operator may save partial work, and the module
|
||||
is reported `blocked · configuration_missing` until they finish. An *invalid* one never is.
|
||||
|
||||
A key omitted from the submission is deleted. Stored keys the module's current manifest no longer
|
||||
declares are **retained and ignored**, and listed as `unknownKeys`, so a downgrade or a rename does
|
||||
not destroy an operator's value.
|
||||
|
||||
### Changes take effect at the next start
|
||||
|
||||
Modules receive a configuration snapshot resolved once at startup, so a `PUT` changes nothing about
|
||||
the running process and the response reports `restartRequired` rather than pretending otherwise.
|
||||
Nothing is hot-reloaded. A setting that genuinely must change live is the module's own domain state,
|
||||
stored in the module's own tables and exposed through its own route — not platform configuration.
|
||||
|
||||
### Missing or invalid configuration blocks the module
|
||||
|
||||
An enabled module whose required configuration cannot be satisfied is never imported. It appears in
|
||||
`GET /api/v1/module-lifecycle` as `blocked` with a structured reason naming the offending **key**:
|
||||
|
||||
```json
|
||||
{ "runtime": { "state": "blocked", "reason": "configuration_missing", "configurationKey": "bucket" } }
|
||||
```
|
||||
|
||||
`configuration_missing` (set a value), `configuration_invalid` (correct the value), and
|
||||
`secret_missing` (set it in the deployment environment) are separate reasons because each has a
|
||||
different fix. A blocked module blocks its required dependents exactly like a disabled one does.
|
||||
|
||||
### Secrets come from the deployment
|
||||
|
||||
A module declares a `secret` key; the host maps it to a deployment-supplied value. In an Ekklesia
|
||||
deployment that mapping is an environment variable:
|
||||
|
||||
```text
|
||||
EKKLESIA_MODULE_SECRET__<MODULE_ID>__<KEY>
|
||||
EKKLESIA_MODULE_SECRET__ANNOUNCEMENTS__STORAGE_CREDENTIAL
|
||||
```
|
||||
|
||||
The module never sees that name — it calls `config.getSecret("storageCredential")` — which is what
|
||||
lets a future standalone host supply the same declared secret from somewhere else entirely.
|
||||
|
||||
### Authority
|
||||
|
||||
Both verbs require `core.modules.configuration.manage` (baseline `restricted`), deliberately separate
|
||||
from `core.modules.lifecycle.manage`: deciding whether a module runs and deciding how it behaves are
|
||||
different authorities. Mutations additionally require an exact trusted `Origin` and a bounded body.
|
||||
|
||||
No response carries a filesystem path, package name, manifest path, caught error, stack, or secret
|
||||
value.
|
||||
|
||||
## Module HTTP routes
|
||||
|
||||
An installed module's routes (declared via `http.route(...)` in its `register` hook — see
|
||||
|
||||
@@ -111,6 +111,7 @@ list:
|
||||
| `core.modules.ui.read` | `authenticated` | List the installed module UIs a browser host may mount. |
|
||||
| `core.dashboard.navigation.manage` | `restricted` | Organize the Dashboard: create, rename, order, and delete navigation groups. |
|
||||
| `core.modules.lifecycle.manage` | `restricted` | Read and change which installed modules are enabled. |
|
||||
| `core.modules.configuration.manage` | `restricted` | Read and change an installed module's own configuration values. |
|
||||
|
||||
Every Core permission is a **platform** permission and can never be declared, gated, or influenced by
|
||||
a module — `core.*` is a reserved namespace (see below). `core.modules.lifecycle.manage` gates both
|
||||
@@ -121,6 +122,14 @@ milder version of the write, because the lifecycle view is the only place a *dis
|
||||
`core.modules.ui.read` deliberately covers only what is mountable. Holding it confers no authority
|
||||
inside any module.
|
||||
|
||||
`core.modules.configuration.manage` is deliberately **separate from** the lifecycle permission
|
||||
([ADR 0029](../architecture/decisions/0029-module-configuration-and-secrets.md)): deciding whether a
|
||||
module runs and deciding how it behaves are different authorities, and someone trusted to tune a
|
||||
module's settings need not be trusted to take modules offline. It gates reading as well as writing,
|
||||
because the read returns every stored value — endpoints, bucket names, and whatever else an operator
|
||||
configured. It never exposes secret material: a secret is deployment-supplied, never persisted, and
|
||||
never returned by any route, so holding this permission confers no ability to read a credential.
|
||||
|
||||
Enablement never changes how a permission is enforced. A **disabled** module's permissions stay
|
||||
registered and grantable — composition spans the whole discovered inventory, not the eligible subset
|
||||
— so a grant survives an enable/disable cycle and can be issued ahead of enabling a module. Nothing
|
||||
@@ -223,7 +232,7 @@ generic explicit-grant HTTP API, enforcement middleware, and now its own mounted
|
||||
`pnpm doctor`'s `modules.permissions` check composes the platform permission registry from the
|
||||
same already-discovered module list `modules.discovery`/`modules.dependencies` already produced —
|
||||
it never re-discovers modules itself. A successful composition reports a pass with a safe
|
||||
declaration count (for example `4 permissions registered` with zero installed modules, since Core's
|
||||
declaration count (for example `5 permissions registered` with zero installed modules, since Core's
|
||||
own declarations are always present); zero installed modules still composes successfully. If module
|
||||
discovery itself failed, the check is skipped, matching the existing schema/migration checks'
|
||||
pattern; if discovery succeeded but composition failed, schema and migration checks still run
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -174,6 +174,25 @@ demonstrably keeps serving, and is applied only by the next start; and a disable
|
||||
are still discovered, because deployed schema ownership is not runtime enabled state. See
|
||||
[ADR 0028](../architecture/decisions/0028-module-operational-lifecycle.md).
|
||||
|
||||
A sixth dedicated suite (`core/tests/module-configuration-store.integration.ts`, included in the same
|
||||
`pnpm test:migrations:integration` run) proves the module configuration store against real
|
||||
PostgreSQL: that migration `0005` really creates `ekklesia_core_module_configuration` with the
|
||||
composite `(module_id, key)` primary key, the declared CHECK constraints, and **no column that could
|
||||
hold secret material**; that a replace is transactional, whole-document, and scoped to one module so
|
||||
another module's rows are untouched; that stored values survive a completely new connection; that an
|
||||
oversized value is refused by the application *and* by the database; that a store error never carries
|
||||
the offending value; and — the security-relevant one — that a module id or key is only ever data in a
|
||||
parameterized column, so an injection attempt is a validation error and the table still exists
|
||||
afterwards.
|
||||
|
||||
The API suite additionally proves the configuration boundary end to end: a secret's value never
|
||||
appears in any response (including when a row for that key is planted directly in storage), a
|
||||
declared-but-undeclared key, a wrong JSON type, a constraint violation, and a `secret` key each fail
|
||||
with a distinct sanitized code and store nothing, a reserved property name such as `__proto__` is
|
||||
rejected without touching `Object.prototype`, and a module blocked by its own configuration is absent
|
||||
from the mountable UI inventory exactly like a disabled one. See
|
||||
[ADR 0029](../architecture/decisions/0029-module-configuration-and-secrets.md).
|
||||
|
||||
### Which kind of timing proof lives where
|
||||
|
||||
Pass 4 introduced several deadlines, and their tests deliberately differ in kind:
|
||||
|
||||
Reference in New Issue
Block a user