feat: create the initial platform owner from an operator command
CI / verify (pull_request) Successful in 41s
CI / infrastructure-smoke (pull_request) Successful in 20s
CI / migration-smoke (pull_request) Successful in 1m18s

A fresh production installation deadlocked. ADR 0034 gave Ekklesia a login
page and ADR 0019 gave it a single-use platform-owner bootstrap, but that
bootstrap grants ownership to a user id that already exists and has no way
to bring one into being. Public signup is disabled by default and
production cannot enable it at all, so a newly deployed instance had a
login page, no account, and no supported way to create one — only hand-
written SQL or briefly opening public registration.

    pnpm identity:create-initial-owner -- --email [email protected]

creates the identity and grants it ownership, in the same shape as the
other operator commands: trusted local tooling, reachable only by someone
who already holds the database credentials, serving no HTTP route. No
/signup, /register, or /setup route is added, no bootstrap endpoint, and
no setup token; public signup stays disabled in every environment and a
test asserts a freshly bootstrapped deployment still refuses
/api/auth/sign-up/email.

The identity is created through Better Auth's own sign-up path, so
hashing, salting, normalization and the 8-128 bound are the identity
system's rather than a second implementation that could drift. Because the
server's instance refuses account creation, the command builds its own
in-process instance; nothing in apps/api imports it and the running
server's posture is untouched.

The sign-up result is verified rather than trusted. Better Auth returns a
fabricated success for an already-registered address — a user object whose
id was never persisted, database unchanged. That is correct enumeration
defence on a public endpoint and a trap here, so the identity is always
read back from the database and that read, not the response, is what the
grant uses.

An existing usable identity is adopted: ownership is granted and its
password left alone, reported as an adoption rather than a creation. This
is the recovery path for the one partial failure possible, since sign-up
commits on Better Auth's connection and the grant is a separate
transaction. A credential-less row is refused instead — making it an owner
would consume the single use on an identity nobody can authenticate as. A
password is never reset and an account is never taken over.

Whole invocations are serialized by an advisory lock on their own key, so
a race cannot leave a stray signable-in account behind; the grant's own
locked single-use transaction is unchanged. There is no --force or reset.

The password is prompted for invisibly or read from stdin, never from
argv (--password is refused with an explanation) and never from an
environment variable, so nothing about it becomes permanent deployment
configuration. The command needs DATABASE_URL and nothing else — verified
that sign-up needs no secret, base URL, or trusted origins, and that the
resulting account signs in through a separately configured server — so the
first owner can be created before TLS or DNS exist. It never migrates.

Proven end to end rather than at the database: a fresh installation is
bootstrapped, signed in through the real browser login transport with
signup disabled, its principal read, and used to open an owner-protected
resource that stays closed to anonymous callers.

Co-Authored-By: Claude Opus 5 <[email protected]>
This commit is contained in:
ekklesia
2026-08-23 22:32:53 -05:00
co-authored by Claude Opus 5
parent c131543abf
commit c8fa13dd6a
16 changed files with 1767 additions and 12 deletions
+38
View File
@@ -506,6 +506,44 @@ outstanding.
consuming the single-use platform-owner bootstrap. This repository does not provide that way
yet.
### The initial-owner command is trusted local tooling
A fresh installation needs a first administrator, and public registration is disabled everywhere and
prohibited in production. `pnpm identity:create-initial-owner` fills that gap
([ADR 0035](../architecture/decisions/0035-initial-platform-owner-bootstrap.md)). What makes it safe
is **where it can be invoked**, not a weaker policy:
- **It is not reachable from a browser.** No `/signup`, `/register`, or `/setup` route, no
unauthenticated bootstrap endpoint, no temporary setup route, and no setup token. It serves no HTTP
route and nothing in `apps/api` imports it. Its authority is already having the database
credentials.
- **Public signup stays disabled.** The command constructs its own in-process identity instance
rather than relaxing the server's posture. A test asserts that a freshly bootstrapped deployment
still refuses `POST /api/auth/sign-up/email`.
- **The password never lands anywhere durable.** Prompted invisibly or read from standard input;
`--password` is refused rather than ignored, because an argument is visible in shell history and in
the process list. No environment variable is read for it and none is in `.env.example`, so it
cannot become permanent deployment configuration. It is never printed, logged, or placed in an
error.
- **It writes no password hash of its own.** Hashing, salting, normalization, and the 8–128 bound are
the identity system's, applied through the same sign-up path a browser uses — so a CLI-created
account can never diverge from a browser-created one.
- **It cannot become a standing superuser factory.** Ownership bootstrap is permanently single-use
and this command consumes the same sentinel; there is no `--force`, reset, or override. A second
run creates no owner, changes no password, and creates no stray identity.
- **It never takes over an account.** An existing usable identity is adopted — granted ownership with
its password untouched — and reported as an adoption. A password reset is never performed. An
identity that has no password at all is refused rather than made an owner nobody can sign in as,
which would consume the single use and leave the installation unusable.
- **Races cannot mint two owners.** Whole invocations are serialized by an advisory lock, on top of
the grant's own locked, single-use transaction.
- **Errors stay sanitized.** No SQL, connection string, driver detail, Better Auth response body, or
cause reaches the operator's terminal — only a stable code and a message describing what is still
true of the installation.
It deliberately does not solve creating *additional* users or owners. That is user administration,
which does not exist yet.
### Rate limiting is per-process today
Better Auth's authentication rate limiter is **in-memory and per API process**. That is acceptable