feat: add host-provided module object storage
CI / verify (pull_request) Successful in 36s
CI / infrastructure-smoke (pull_request) Successful in 13s
CI / migration-smoke (pull_request) Failing after 2m20s

`manifest.storage.buckets` has existed since manifest version 1 and meant
nothing — discovery validated it and no code read it. This turns it into a
real capability, which is what stands between Announcements and the module
system: that product currently fetches a hardcoded LAN S3 endpoint, parses
ListObjectsV2 XML by hand, and hands the browser direct object URLs.

- A module declares a logical bucket and receives a scoped facade at
  `context.storage` — list, head, get, put, delete. The contract names no
  provider: no endpoint, region, credential, or physical bucket is reachable
  from it, which is what lets the same module run under a future standalone
  host over its own or a shared S3-compatible service.
- Core's first provider speaks S3 through the AWS SDK. SeaweedFS is the
  deployment target (ADR 0004), never an API name. Probing the pinned image
  found `CreateBucket` reporting `BucketAlreadyExists` rather than AWS's
  `BucketAlreadyOwnedByYou`; treating only the AWS spelling as success would
  have failed every second boot. A live test pins it.
- Logical → physical mapping is deterministic and collision-safe: an
  installation prefix, the module and bucket ids joined by `--` (which cannot
  occur inside either identifier, so `a-b`+`c` and `a`+`b-c` cannot collide),
  and a digest over the full untruncated identity. Two modules declaring
  `assets` always get separate namespaces; neither can see the physical name.
- Declaring a bucket is now a requirement: with no provider configured the
  module is `blocked · storage_unavailable` through ADR 0028's existing
  resolver, propagating to required dependents. An installation with no object
  storage stays a complete deployment.
- Binding availability is not provider health. Eligibility asks whether
  storage is configured, never whether it answered; bucket creation is lazy on
  first use so a storage outage cannot stop the platform booting; a running
  module whose store blinks stays running and retries. Nothing deletes a
  bucket.
- Credentials are deployment-supplied, never persisted, never routed through
  module configuration, and never visible to modules, module UI, diagnostics,
  or API responses. Provider errors translate to a closed code set carrying no
  endpoint, bucket, request id, or XML.
- Retires ADR 0029's transitional `bucket` configuration key. No manifest
  version change. The template declares no bucket, so it still runs without S3.

See ADR 0030.

Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
2026-08-23 08:45:53 -05:00
co-authored by Claude Opus 5
parent 527239f6de
commit b9ca0d560d
55 changed files with 4420 additions and 74 deletions
+38
View File
@@ -245,6 +245,44 @@ Reading or changing configuration requires `core.modules.configuration.manage` (
`Origin` and a bounded body, like every other Core mutation. Module UI receives no configuration at
all in this phase.
### Object storage is scoped by binding, and modules never hold credentials
A module declares a logical bucket; the host resolves it to a physical bucket on an S3-compatible
service and hands the module a facade scoped to exactly that
([ADR 0030](../architecture/decisions/0030-host-provided-module-object-storage.md)).
What that gives, structurally rather than by discipline:
- **No credential reaches a module.** The endpoint, region, access key, and secret key live in the
host's validated configuration and reach Core's provider only. `ModuleStorage` has no accessor that
could return any of them, and none appears in any error, diagnostic, or API response.
- **No module can open another module's bucket.** The facade closes over exactly the bindings that
module's manifest declared. Knowing another module's bucket name, module id, or physical bucket
name buys nothing, because none of those is an input to anything — an undeclared name is simply not
a key in the map.
- **No module chooses a physical bucket or an endpoint.** Both come from host configuration and the
deterministic binding, never from module input, so a module cannot aim the platform's S3 client at
a server of its choosing.
- **Two modules declaring the same logical name are isolated.** Physical names are derived from
module id *and* bucket id with a separator that cannot occur inside either, plus a digest over the
full identity — so `assets` in two modules is two namespaces, not one.
- **Object keys cannot escape a bucket**, because the bucket never comes from the key.
- **Nothing deletes a bucket.** There is no such operation to call, so disabling or removing a module
cannot take data with it.
- **Provider errors are translated, never forwarded.** No endpoint, request id, bucket name, or XML
body survives into a `ModuleStorageError` a module might log or return.
Endpoints must be absolute `http`/`https`, must not embed credentials, and must use `https` in
production — the same standard the database transport holds. Credentials are never persisted in
PostgreSQL and never routed through module configuration, which has no encryption at rest to offer
them (ADR 0029).
**What this does not claim.** A module is still trusted code in the API process, so a malicious module
could read `process.env` directly and obtain the provider credentials that way. Scoped storage is a
correctness and portability boundary like every other module-facing mechanism here — not a sandbox.
What it does guarantee is that Ekklesia never hands a module another module's data, never gives module
UI or a browser a credential, and never prints one in diagnostics.
### Client-side permission checks are not a security boundary
A host may tell a module UI what permissions it believes the viewer holds