feat: add the minimal operational module lifecycle
Ekklesia had no notion of a module being on or off: the accepted module set was exactly "whatever discovery found on disk", and `ModuleLifecycleStage` named nine states nothing produced or consumed. This replaces that vocabulary with two axes that real code produces — persistent, administrator-owned configuration (`enabled`/`disabled`) and per-boot runtime observation (`running`/`disabled`/`blocked`) — and wires them through startup. - One Core table (`ekklesia_core_module_state`, migration 0004) holding only `module_id` and `enabled`. A module with no record is enabled by default, so deploying a module is still sufficient to run it and discovery never needs an initialization write. A record for an undeployed module is retained and ignored, so redeploying restores the decision. - `resolveModuleEligibility` is pure: a disabled module transitively blocks every module that *requires* it (module and capability edges alike) with a structured reason naming the provider; optional dependencies never block; and a missing, incompatible, or cyclic dependency stays discovery's concern. - `startApi` starts only the eligible set and builds the UI publication registry from that same list, so routes, artifacts, browser inventory, and Dashboard navigation all follow one authoritative set. A disabled module is never imported, so there is no per-request enablement check anywhere. - Startup stays all-or-nothing, deliberately; there is consequently no `failed` runtime state. `pnpm modules:enable`/`modules:disable` is the out-of-band recovery path for a module that breaks startup. - Changes take effect at the next start, and the read model reports configuration, runtime, and `restartRequired` separately rather than claiming a module stopped when it has not. - Migration participation and permission composition still span the deployed and discovered inventories respectively, unchanged. - New restricted platform permission `core.modules.lifecycle.manage` gates both reading and changing enablement, at a sibling prefix (`/api/v1/module-lifecycle`) that cannot collide with the module route namespace. - `pnpm doctor` gains a `modules.lifecycle` check so "why is this module unavailable?" is answerable without reading logs. See ADR 0028. Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
co-authored by
Claude Opus 5
parent
db67cf7700
commit
7729c99e24
@@ -168,6 +168,33 @@ what a request may do. Reading navigation requires the same `core.modules.ui.rea
|
||||
inventory requires, so it discloses the same installed-module enumeration and nothing more; it
|
||||
carries no filesystem path, package root, or manifest internal.
|
||||
|
||||
### Disabling a module is an operational control, not a security boundary
|
||||
|
||||
A module can be turned off, and that decision survives restarts
|
||||
([ADR 0028](../architecture/decisions/0028-module-operational-lifecycle.md)): a disabled module is
|
||||
never imported, so its code never runs, it mounts no routes, registers no capabilities, and publishes
|
||||
no UI. That is a real and useful operational property — it is how an operator recovers from a module
|
||||
that misbehaves or breaks startup.
|
||||
|
||||
**It is not containment.** The module's compiled code is still on disk, still trusted, and still
|
||||
carries every authority listed above the moment anything starts it. Enablement is a row in
|
||||
`ekklesia_core_module_state`; it constrains the platform's own composition, not the module. Anyone
|
||||
who can put a module package on this filesystem, or who holds the database or operating-system access
|
||||
to change that row, decides what runs. Nothing about disabling a module sandboxes, isolates, or
|
||||
reduces the privileges of a module that *is* enabled.
|
||||
|
||||
Changing enablement requires `core.modules.lifecycle.manage` (baseline `restricted`) and — for the
|
||||
mutation — an exact trusted `Origin` and a bounded body. Reading is gated by the same permission
|
||||
because the lifecycle view is the only place a disabled module, a blocked module, and the
|
||||
required-dependency edges between them are visible; `core.modules.ui.read` deliberately exposes only
|
||||
the mountable set. Neither response carries a filesystem path, package name, manifest path,
|
||||
entrypoint, caught error, or stack — only module ids, capability ids, and fixed reason codes.
|
||||
|
||||
Holding the lifecycle permission grants no authority *inside* any module: every module route stays
|
||||
enforced against that module's own declared permission, and a disabled module's permissions remain
|
||||
registered and grantable precisely so that an enable/disable cycle changes nothing about who holds
|
||||
what.
|
||||
|
||||
### Client-side permission checks are not a security boundary
|
||||
|
||||
A host may tell a module UI what permissions it believes the viewer holds
|
||||
|
||||
Reference in New Issue
Block a user