ekklesiaandClaude Opus 5
6b6b77c105
Every PostgreSQL connection this repository opened was plaintext, in every environment: no connection site set `ssl` at all, so credentials, session tokens, and row data crossed the network in the clear and nothing in configuration, startup, or `pnpm doctor` said so. The public identity URL boundary was also looser than it appeared. `core/src/database/transport.ts` is now the one typed policy. It has exactly two modes: `verify-full` (TLS required, certificate chain verified, and server identity verified against the configured host — the production default) and `disable` (the development/test default, refused outright in production). There is deliberately no encryption-only `require` mode, no chain-only `verify-ca`, and no `rejectUnauthorized: false` escape hatch anywhere in the configuration surface; every loose or aliased spelling is rejected in both environments, so a typo never quietly becomes a weaker mode. Production has no plaintext exception at all, not even for a loopback database — a connection string cannot prove the database is process-local. Verification is certificate *and* hostname. The policy supplies an explicit `checkServerIdentity` pinned to the host parsed from DATABASE_URL, because the pinned driver sets TLS `servername` only for non-IP hosts and Node performs no identity check when it is unset — so `rejectUnauthorized: true` alone accepts a certificate from any host the trusted CA ever signed when connecting by IP. Both halves are proven against a real TLS-enabled PostgreSQL, including that the same connection without the pinned callback succeeds. Every CA, certificate, and key is generated at test runtime and deleted afterwards. A DATABASE_URL may no longer carry its own TLS parameters. The pinned driver merges parsed connection-string values over explicitly passed options, so a `?sslmode=disable` in the URL would silently replace the policy's verified `ssl` object; that now fails with a stable code, reported by both `pnpm doctor` and the migration CLIs rather than as "failed unexpectedly". One shared environment reader keeps `process.env` out of Core's reusable constructors, and every executable that opens a connection resolves the policy identically: the API (validated before any pool, Better Auth instance, module runtime, or listener exists), both migration commands, the bootstrap CLI, and Doctor's own connection. Doctor reports it as a blocking failure, never a warning, naming only the effective mode. Separately, the identity base URL and every trusted origin must now be exactly one canonical origin — the WHATWG origin serialization must equal the supplied string — so a path, trailing slash, credentials, explicit default port, or non-canonical case is rejected rather than normalized into something that no longer matches what a browser sends. Production's loopback rejection now classifies the address instead of comparing against three literals, covering `.localhost`, all of 127.0.0.0/8, 0.0.0.0, `::`, expanded and IPv4-mapped forms. This is a configuration-shape guarantee only: it does not resolve DNS or prove reachability, and TLS protects the connection, not the exposure. Co-Authored-By: Claude Opus 5 <[email protected]>
265 lines
16 KiB
Markdown
265 lines
16 KiB
Markdown
# Ekklesia
|
||
|
||
Ekklesia is an open, modular church technology platform for composing backend capabilities
|
||
into independently developed dashboards, websites, mobile apps, kiosks, displays, and other
|
||
surfaces.
|
||
|
||
## Current status
|
||
|
||
Phase 3 is complete, and Phase 4A (Core identity foundation), Phase 4B (identity HTTP transport),
|
||
Phase 4C (Core authorization), Phase 5A (module authorization integration), Phase 5B (module HTTP
|
||
transport), and Phase 5C (module database access) have landed. Phase 5D (public request perimeter
|
||
hardening against an independent security audit) is in progress; pass 1 of 5 has landed — see
|
||
below. **Phase 5D is not complete, and Phase 6 (Surface work) remains blocked until every audit
|
||
finding is resolved and a final re-audit passes.** The repository includes
|
||
public module contracts, independently versioned capabilities, static module manifests,
|
||
deterministic automatic discovery, compiled server loading, a staged capability registry,
|
||
dependency-ordered lifecycle with rollback, module-owned Drizzle table contracts, deterministic
|
||
schema aggregation, and a cloneable backend-only module template. Migration artifacts have
|
||
module-owned Drizzle contracts, deterministic offline discovery, explicit destructive-change
|
||
declarations, and exact checksums. Core provides read-only applied-history planning and a locked,
|
||
whole-batch transactional PostgreSQL runner with exact external destructive approval matching. A
|
||
hermetic live PostgreSQL suite proves history, rollback, statement breakpoints, advisory-lock
|
||
concurrency and release, exact destructive approvals, and sanitization against the production
|
||
adapter. A Core-owned `pnpm doctor` dashboard combines the existing static discovery and read-only
|
||
migration-planning services into one concise readiness report.
|
||
|
||
Phase 4A added Core-owned identity foundations: a Core-owned Better Auth database schema
|
||
(`ekklesia_core_user`, `ekklesia_core_session`, `ekklesia_core_account`,
|
||
`ekklesia_core_verification`), a first-class Core-owned migration source that coexists with
|
||
module-owned migrations under the exact same migration system, minimal opaque-identity contracts
|
||
in `@ekklesia/contracts`, and an explicit Better Auth construction boundary in Core. See
|
||
[Identity](docs/development/identity.md) and
|
||
[ADR 0010](docs/architecture/decisions/0010-core-identity-and-better-auth-adoption.md).
|
||
|
||
Phase 4B adds identity HTTP transport: a minimal Hono-based `apps/api` composition root
|
||
(`pnpm api:start`) mounts Better Auth at `/api/auth/*` and exposes `GET /api/v1/principal` behind
|
||
Core's own Fetch-compatible identity runtime — Core still does not depend on Hono, and modules
|
||
still cannot reach any of this. Public email/password registration is the intended eventual
|
||
product policy — every account receives identical lowest-privilege baseline status and signup
|
||
order never grants elevation — but is now **disabled by default, and cannot be enabled in
|
||
production at all** until durable abuse controls exist (Phase 5D pass 1, below). See
|
||
[API](docs/development/api.md) and
|
||
[ADR 0011](docs/architecture/decisions/0011-identity-http-transport-and-public-enrollment.md).
|
||
**No email verification, password recovery, or Dashboard exists yet** — that, along with
|
||
production approval-provider composition, jobs, physical storage provisioning, surfaces, and
|
||
feature modules, remains later vertical slices. Public registration is not yet ready for a real
|
||
public launch.
|
||
|
||
Phase 4C adds Core's authorization foundation on top of identity: a schema, evaluator, and store
|
||
for platform owners, explicit grants, and relationship-derived grants; a smallest-possible
|
||
immutable permission registry; an explicit, single-use, concurrency-safe platform-owner bootstrap
|
||
command (`pnpm authorization:bootstrap-owner`, never HTTP-exposed, never inferred from signup
|
||
order); and, in `apps/api`, reusable Hono authorization enforcement plus a narrowly scoped
|
||
`/api/v1/grants` HTTP API for managing *explicit* grants only, requiring an exact trusted `Origin`
|
||
on every mutation. Roles/groups/teams/tenants, an owner-management HTTP endpoint, and service
|
||
accounts/API tokens remain later work. See [Authorization](docs/development/authorization.md) and
|
||
[ADR 0013](docs/architecture/decisions/0013-core-authorization-and-owner-bootstrap.md).
|
||
|
||
Phase 5A wires module-declared permissions into that same authorization system: a version-3 module
|
||
manifest declares permissions as complete `{id, baseline, description}` declarations (never a bare
|
||
string), and `apps/api` discovers every installed module and composes one immutable platform
|
||
permission registry — Core's own declarations plus every module's — before constructing its
|
||
database pool, Better Auth instance, or HTTP server. A module's declared permission is then
|
||
enforceable and grantable through the exact same `requirePermission` middleware and
|
||
`/api/v1/grants` HTTP API Core's own permissions already use, with `core.*` reserved and never
|
||
claimable by a module. `pnpm doctor` and `pnpm modules:validate` both validate permission
|
||
composition. Installing, removing, or editing a module currently requires an API restart; removing
|
||
one makes its permission unavailable to new checks and new grants without deleting or revoking any
|
||
historical grant or audit row. See
|
||
[Authorization](docs/development/authorization.md#module-permission-composition),
|
||
[Module development](docs/module-development/README.md), and
|
||
[ADR 0014](docs/architecture/decisions/0014-module-permission-declarations-and-platform-registry.md).
|
||
|
||
Phase 5B mounts a module's own HTTP routes in production. A module registers framework-neutral
|
||
Fetch (`Request`/`Response`) route handlers during its existing `register` hook; Core collects them
|
||
into an immutable snapshot alongside its capabilities, and `apps/api` discovers modules exactly
|
||
once, starts the module runtime from that same discovered inventory, and mounts its published
|
||
routes under `/api/v1/modules/<module-id>` — after every module has registered and started
|
||
successfully, so no request can reach a module before startup completes. Every route is enforced
|
||
through the identical `requirePermission` middleware and composed permission registry Core's own
|
||
routes use (a module can never supply its own baseline), state-changing methods require a trusted
|
||
`Origin`, and a handler failure or non-`Response` return becomes a fixed, sanitized `500` — never a
|
||
raw error, stack, path, or permission id. Relationship-derived grant creation remains later work.
|
||
See [API](docs/development/api.md#module-http-routes),
|
||
[Module development](docs/module-development/README.md#http-routes), and
|
||
[ADR 0014](docs/architecture/decisions/0014-module-permission-declarations-and-platform-registry.md#deferred).
|
||
|
||
Phase 5C gives a module's own lifecycle hooks and HTTP handlers typed access to their own
|
||
PostgreSQL tables. `context.services.database` — a restricted, typed `ModuleDatabase` view over
|
||
Drizzle's `select`/`selectDistinct`/`selectDistinctOn`/`insert`/`update`/`delete`/`execute`/
|
||
`transaction`, never a raw `pg` client, pool, or connection string — is available to `start`,
|
||
`stop`, and every authorized route handler, and reuses the one PostgreSQL pool `apps/api` already
|
||
owns; registration remains declarative and database-free. Modules continue to own and import their
|
||
own Drizzle schemas and generated migrations, applied explicitly and never automatically at
|
||
startup. See [API](docs/development/api.md#module-database-access),
|
||
[Module development](docs/module-development/README.md#database-access), and
|
||
[ADR 0016](docs/architecture/decisions/0016-module-database-access.md).
|
||
|
||
Phase 5D pass 1 of 5 hardens the public request perimeter against an independent security audit
|
||
of the Phase 5C checkpoint, without adding a Surface, a product module, or any new capability.
|
||
Better Auth's authentication rate limiter now resolves client identity from a server-owned
|
||
client-address boundary (`core/src/identity/client-address.ts`, wired in at the Node/API transport
|
||
boundary) — direct mode trusts only the real socket peer by default, and an explicit trusted-proxy
|
||
mode is required before any forwarded header is ever consulted, closing a rotating-header
|
||
rate-limit bypass. Public sign-up is now **disabled by default, and a production configuration that
|
||
tries to enable it fails closed** (`PUBLIC_SIGNUP_UNSUPPORTED_IN_PRODUCTION`, reported by `pnpm
|
||
doctor` as a blocking failure) — the durable abuse-control prerequisites do not exist yet, so only
|
||
development/test composition may enable it. Every public body-consuming route — Better Auth,
|
||
Core's grant-mutation endpoint, and every module route (via a new, required `maxBodyBytes` field on
|
||
the executable route contract) — now has an explicit, platform-enforced byte ceiling with one
|
||
sanitized `413` contract. The Node HTTP server now has finite header/request timeouts, whose real
|
||
transport-level failures are observed and logged in sanitized form. See
|
||
[API](docs/development/api.md), [Module development](docs/module-development/README.md#http-routes),
|
||
and [ADR 0017](docs/architecture/decisions/0017-public-request-perimeter-hardening.md). **This pass
|
||
does not add distributed rate limiting, durable public-signup abuse control, or any deployment/TLS
|
||
guarantee, and it does not complete Phase 5D** — passes 2–5 (identity/database transport hardening,
|
||
authorization integrity, module/runtime/migration correctness, and deployment/supply-chain closure
|
||
plus a final independent re-audit) remain outstanding before Phase 6 (Surface work) may begin.
|
||
|
||
Phase 5D pass 2 of 5 corrects identity session resolution and enforces a database transport policy.
|
||
A request carrying no cookies, or only unrelated cookies, now performs **no** identity database
|
||
work at all; only a request presenting the configured session cookie that Better Auth resolved to
|
||
`null` is disambiguated, by a real read of the session relation and the exact columns the adapter
|
||
depends on (under `where false`, so no row is ever read) rather than the previous `select 1`. A
|
||
missing table, dropped column, revoked privilege, unreachable database, or query timeout therefore
|
||
produces a sanitized `503`, never a silent anonymous downgrade. The identity base URL and every
|
||
trusted origin must now be exactly one canonical origin, and production rejects the full
|
||
loopback/unspecified address space rather than three literal spellings. **Production PostgreSQL
|
||
connections now require TLS with certificate *and* hostname verification** — from the API, both
|
||
migration commands, the bootstrap CLI, and `pnpm doctor` alike — with no encryption-only mode, no
|
||
`rejectUnauthorized: false` escape hatch, no plaintext exception (not even for a loopback
|
||
database), and an explicit refusal of a `DATABASE_URL` that tries to carry its own TLS parameters,
|
||
which the pinned driver would otherwise let silently override the policy. See
|
||
[Identity](docs/development/identity.md), [API](docs/development/api.md#database-transport-tls), and
|
||
[ADR 0018](docs/architecture/decisions/0018-identity-session-resolution-and-database-transport.md).
|
||
**This pass adds no secret store, no certificate rotation, no client-certificate authentication, and
|
||
no distributed rate limiting; TLS protects the connection, not the exposure, so the network boundary
|
||
remains the deployment's own responsibility. Phase 5D is still not complete** — passes 3–5
|
||
(authorization integrity, module/runtime/migration correctness, and deployment/supply-chain closure
|
||
plus a final independent re-audit) remain outstanding.
|
||
|
||
## Quick start
|
||
|
||
Prerequisites: Node.js 24 LTS, pnpm 11.12, and Docker with Compose.
|
||
|
||
```bash
|
||
pnpm install --frozen-lockfile
|
||
cp .env.example .env # keep its NODE_ENV=development: see below
|
||
pnpm infrastructure:up
|
||
pnpm modules:validate
|
||
pnpm migrations:validate
|
||
pnpm identity:schema:validate
|
||
pnpm doctor
|
||
pnpm migrations:plan
|
||
pnpm test:migrations:integration
|
||
pnpm verify
|
||
```
|
||
|
||
`pnpm doctor` builds the workspace first, then reports the supported Node.js runtime, installed
|
||
modules and dependency order, schema and migration inventories, the effective PostgreSQL transport
|
||
(TLS) policy, optional read-only PostgreSQL planning, and the current object-storage integration
|
||
state. `.env.example` sets `NODE_ENV=development` deliberately: anything else, including an unset
|
||
value, is validated as production, and production requires certificate-verified PostgreSQL TLS and
|
||
rejects loopback/`http` identity origins — so the plaintext loopback database this repository's own
|
||
development infrastructure provides is only usable with it set.
|
||
|
||
Doctor never applies migrations, creates a history table, starts module servers, or performs
|
||
storage operations. Schema discovery does import
|
||
compiled schema-definition entrypoints; those entrypoints are contractually side-effect-free.
|
||
|
||
With no installed modules and no `DATABASE_URL`, the current repository produces a report shaped
|
||
like this:
|
||
|
||
```text
|
||
Ekklesia Doctor
|
||
|
||
Platform
|
||
✓ Runtime version supported
|
||
Active Node.js satisfies the declared supported range.
|
||
|
||
Modules
|
||
✓ Module discovery complete
|
||
0 modules installed
|
||
✓ Dependency graph valid
|
||
Dependency order is empty.
|
||
✓ Permission registry composed
|
||
1 permission registered
|
||
|
||
Data definitions
|
||
✓ Schemas validated
|
||
0 modules · 0 tables
|
||
✓ Migrations validated
|
||
2 migrations · checksums valid
|
||
core:0000_identity_core_tables · f8f2086ef06f
|
||
core:0001_authorization_core_tables · 830e1fbc26d0
|
||
|
||
PostgreSQL
|
||
✓ Database TLS verified
|
||
TLS required with certificate and hostname verification.
|
||
○ Connection check skipped
|
||
DATABASE_URL is not configured.
|
||
○ Migration plan skipped
|
||
A validated migration inventory and configured PostgreSQL connection are required.
|
||
|
||
Identity
|
||
○ Identity configuration skipped
|
||
Core identity schema defines 4 tables (ekklesia_core_account, ekklesia_core_session, ekklesia_core_user, ekklesia_core_verification).
|
||
Identity runtime configuration (signing key, base URL, trusted origins) is not set.
|
||
|
||
Object storage
|
||
○ Check unavailable
|
||
Core storage integration has not been implemented yet.
|
||
|
||
Result: READY WITH WARNINGS
|
||
```
|
||
|
||
Checks have stable pass, warning, failure, or skipped states. Warnings and skipped optional checks
|
||
produce `READY WITH WARNINGS` and exit zero; any failure produces `NOT READY` and exit one. The
|
||
dashboard is human-readable local guidance, not a replacement for automated CI evidence.
|
||
|
||
`pnpm migrations:plan` uses `DATABASE_URL` from the uncommitted `.env` and is read-only.
|
||
`pnpm migrations:apply` uses the same validated inventory but mutates PostgreSQL under Core's
|
||
advisory lock and one transaction. Review the plan before applying. Destructive migrations are
|
||
blocked by default and require an exact externally supplied approval; there is no force flag.
|
||
|
||
The runner has both deterministic unit coverage through a narrow database port and a separate live
|
||
PostgreSQL integration suite. The live command creates and destroys disposable Docker
|
||
infrastructure; it remains separate from the Docker-free `pnpm verify` gate.
|
||
|
||
`pnpm identity:schema:validate` regenerates Better Auth's canonical schema with the pinned local
|
||
CLI into a temporary location and structurally compares it against the checked-in
|
||
`core/src/identity/schema.ts`, then removes the temporary output. It requires no `DATABASE_URL`
|
||
and is part of `pnpm verify`. See [Identity](docs/development/identity.md) for the full upgrade
|
||
workflow.
|
||
|
||
`pnpm api:start` builds the workspace, then starts the identity HTTP transport
|
||
(`GET /api/v1/principal`, Better Auth mounted at `/api/auth/*`) against an already-migrated
|
||
`DATABASE_URL` — it never applies migrations itself. See [API](docs/development/api.md) for
|
||
required configuration, routes, and a full request/response transcript.
|
||
|
||
Run `pnpm infrastructure:smoke` for an isolated end-to-end PostgreSQL and authenticated S3 check.
|
||
|
||
The development services bind only to loopback:
|
||
|
||
- PostgreSQL: `127.0.0.1:5432`
|
||
- S3-compatible object storage: `127.0.0.1:8333`
|
||
|
||
The values in `.env.example` are development-only and must never be reused in a deployed
|
||
environment.
|
||
|
||
## Architecture
|
||
|
||
- [Platform architecture](docs/architecture/platform-architecture.md)
|
||
- [Repository boundaries](docs/architecture/repository-boundaries.md)
|
||
- [Repository workflow](docs/development/repository-workflow.md)
|
||
- [Testing](docs/development/testing.md)
|
||
- [Identity](docs/development/identity.md)
|
||
- [API](docs/development/api.md)
|
||
- [Authorization](docs/development/authorization.md)
|
||
- [Module development](docs/module-development/README.md)
|
||
- [Architecture decisions](docs/architecture/decisions/README.md)
|
||
|
||
No open-source license has been selected yet. A license should be added only after the project
|
||
owner makes that decision.
|