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]>
Add a single platform-owned request-body policy (hono/body-limit) with
small, named limits for Better Auth and Core's grant-mutation endpoint, and
a new required maxBodyBytes field on the executable module route contract so
every module route makes a conscious no-body-or-bounded-body choice, capped
at a platform ceiling. Every oversized request gets one sanitized 413
contract and never reaches business logic, authorization, or a handler.
Also configure finite Node header/request/keep-alive timeouts, including the
non-obvious connectionsCheckingInterval needed for them to take effect
promptly, so a slow-header or slow-body connection cannot hold a socket
indefinitely.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Add ADR 0016 recording the accepted module database access design (ModuleDatabase, the frozen
ModuleRuntimeServices boundary, one pool/one facade/one services-object identity, explicit
migrations, and the trust model), with narrow cross-reference corrections to ADR 0006 and ADR 0015
where their original text is now inaccurate. Sweep docs/development/api.md,
docs/development/authorization.md, docs/module-development/README.md, docs/development/testing.md,
and docs/development/identity.md for the new database boundary and remaining Phase 4C staleness;
correct the stale "Phase 4C is next" roadmap paragraph in platform-architecture.md and the matching
gap in README's current-status narrative. Extend the module template with a permissioned
GET /records route reading through context.services.database, using the canonical
createModuleTable helper, with matching template tests.
Phase 5B, pass 1: framework-neutral module HTTP route contracts and runtime
registration. Adds @ekklesia/contracts' module-http.ts (methods, canonical
path grammar, route definition/context/handler types, and validation)
and Core's module runtime staging/publication of a module's declared
routes alongside its capabilities, gated on the module's own manifest
permissions. Routes are collected into StartedModuleRuntime as an
immutable snapshot but are not yet mounted into apps/api; that is pass 2.
Co-Authored-By: Claude Sonnet 5 <[email protected]>
Establishes the one canonical PermissionDeclaration contract
(packages/contracts/src/authorization.ts) — id/baseline/description,
strict, unknown-property-rejecting — consumed by both Core's
authorization registry and module manifests, replacing Core's
previously separate interface.
Bumps the canonical module manifest to manifestVersion 3: permissions
become complete declarations instead of bare identifier strings, with
manifest-owned namespace and duplicate-id enforcement. Version 2 and
bare string-array permissions are rejected outright; there is no
compatibility adapter.
Adds composePlatformPermissionRegistry (core/src/modules/permissions.ts),
a pure, synchronous composer that builds one platform permission
registry from Core's own declarations plus every already-discovered
module's, in deterministic order, reusing createPermissionRegistry
and rejecting any module-contributed permission in the reserved
core.* namespace. core/src/authorization remains independent of
core/src/modules; only the module integration layer depends on
authorization.
Updates the module template, module-development docs, authorization
docs, and existing manifest fixtures for manifestVersion 3. Does not
wire the combined registry into apps/api — that is pass 2.
