feat: add host-provided module object storage
`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:
co-authored by
Claude Opus 5
parent
527239f6de
commit
b9ca0d560d
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user