ekklesiaandClaude Opus 5
7ff063b87a
ADR 0030 left exactly one way to get an image to a browser: read the
object into the module's process and write it back out of a module HTTP
route. Every byte of every asset travelled storage -> Ekklesia -> browser.
For the slideshow this platform exists to replace that means Ekklesia in
the path of every image on every display, permanently, for bytes that
never change — and it would make Ekklesia responsible for re-implementing
byte ranges, without which video seeking cannot work at all.
A module can now ask a logical bucket for a temporary browser URL:
const { url, expiresAt } = await assets.createReadUrl("slides/welcome.png");
The contract names intent, not mechanism. There is no signing, expiry
format, endpoint, or bucket in it — a host with no S3 anywhere could
satisfy the same method, which is what keeps a future single-module
standalone host able to implement it. The URL is opaque to module code and
a bearer capability to whoever holds it, so a module authorizes the
request in its own route before asking: storage bounds reach, never
identity. Lifetimes run one minute to six hours, fifteen by default, and
out-of-range values are refused rather than clamped, so "expires forever"
is unreachable. Logical keys stay canonical state; URLs are generated on
demand and never persisted or logged.
The provider endpoint and the browser delivery origin are separated
because measurement showed they cannot be collapsed: an S3-compatible
signature covers the request Host, so a URL signed for one origin and
rewritten to another is rejected. The browser-facing origin is therefore a
signing input (S3_DELIVERY_ENDPOINT), defaulting to S3_ENDPOINT — so the
standard deployment configures nothing and delivery just works. The scheme
is not signed, so a reverse proxy may terminate TLS provided it passes the
original Host through; that is pinned by a test rather than described and
hoped for.
Read URLs are stable within a window of one third of their lifetime.
Signing is a pure function of the clock, so naive re-signing yields a new
URL per second — a guaranteed browser cache miss, and the reference client
keys its <img> by URL, so an unchanged image would be torn down and
re-downloaded continuously. Quantizing the signing timestamp makes
repeated calls byte-identical while leaving at least two-thirds of the
lifetime; Cache-Control is set at signing time to the guaranteed
remainder, because the pinned SeaweedFS image sends none of its own.
Verified against live SeaweedFS: byte ranges answered directly with 206
and a correct Content-Range, so no range proxy is needed in Core; signing
is local (200 URLs in 66ms), so no batch API is needed; unsigned requests
for the same object are refused, so delivery never depends on a public
bucket; tampered signatures, swapped keys, and swapped buckets all
rejected. Signed write and delete URLs are deliberately not built.
Co-Authored-By: Claude Opus 5 <[email protected]>
Architecture decision records
ADRs capture durable choices that affect more than one package or phase.
- Filenames use a four-digit sequence followed by a short kebab-case title.
- Status is
Proposed,Accepted,Superseded, orRejected. - Accepted ADRs are immutable except for status and cross-reference corrections.
- A changed decision receives a new ADR that links to and supersedes the old one.
Index
- 0001: Four-layer platform boundary — Accepted
- 0002: pnpm workspace and strict TypeScript — Accepted
- 0003: Development infrastructure — Accepted
- 0004: Replace unmaintained MinIO baseline — Accepted
- 0005: Static module manifests and atomic discovery — Superseded
- 0006: Versioned capabilities and compiled module runtime — Accepted
- 0007: Module-owned Drizzle schemas and table isolation — Accepted
- 0008: Module-owned migration contracts and offline validation — Accepted
- 0009: Transactional module migration execution — Accepted
- 0010: Core identity architecture and Better Auth adoption — Accepted
- 0011: Identity HTTP transport and public enrollment policy — Accepted
- 0012: Production-equivalent identity origin/CSRF protection under test — Accepted
- 0013: Core authorization, permission registry, and platform-owner bootstrap — Accepted
- 0014: Module permission declarations and platform permission registry — Accepted
- 0015: Static module HTTP routing and production runtime lifecycle — Accepted
- 0016: Module database access — Accepted
- 0017: Public request perimeter hardening — client address, signup gating, body limits, timeouts — Accepted
- 0018: Identity session resolution, canonical public origins, and PostgreSQL transport policy — Accepted
- 0019: Durable authorization history and grant management — Accepted
- 0020: Module runtime and migration execution hardening — Accepted
- 0021: Modules as independently hostable products — Accepted
- 0022: Module UI authoring model and host contract — Accepted
- 0023: Module UI build pipeline — Accepted
- 0024: Browser-safe module UI SDK and the generic host loader — Accepted
- 0025: Trusted module UI asset publication — Accepted
- 0026: The minimal Ekklesia module UI host — Accepted
- 0027: Dashboard navigation is presentation configuration, and modules stay flat — Accepted
- 0028: Module operational lifecycle — enablement, eligibility, and what "running" means — Accepted
- 0029: Module configuration is manifest-declared, host-resolved, and secret-free at rest — Accepted
- 0030: Modules declare logical buckets; hosts provide object storage — Accepted
- 0031: Browsers fetch objects directly, through opaque temporary read URLs — Accepted