Move federation identity + remaining secrets from .env to DB (hosting-model decision needed)

[TemujinCalidius]

Split out of #59 so that issue can close on its shipped, safe surface. This is the deferred, breaking half its audit always flagged.

What's left env-only (deliberately)

Bucket	Vars
Federation identity	SITE_URL, FEDI_HANDLE, FEDI_DOMAIN — baked into the ActivityPub actor id, WebFinger, signature keyId, RSS. Changing them post-install rewrites your identity.
Root secrets / infra	ADMIN_SECRET, DATABASE_URL, SMTP_* / DAYONE_EMAIL, TRUSTED_PROXY, SETUP_TOKEN

Everything user-facing and safe to move web-side is done (theme/layout/accent/sidebar, profile incl. avatar/banner, contact + podcast, gallery categories, analytics site-id and encrypted API key, crosspost creds, VAPID keys, and session/token TTLs).

Why it's not just "another slice"

Moving identity to the DB is a breaking change to how an instance is stood up and migrated, and it interacts with:

• Actor-id immutability (an existing instance can't safely change SITE_URL/handle without re-keying / breaking followers — see ensureActorKeys() silently mints a NEW federation keypair when the ActorKeys row is missing #310).
• Where the source of truth lives if we ever offer managed hosting (the hosting-model decision this issue keeps pointing at).
• The setup wizard already writes these to .env.local safely (fix(setup): don't brick an install when setup fails; ask for + validate SITE_URL (#59) #301) — the question is whether a running instance should be able to rewrite them, and how to migrate existing .env installs.

Suggested shape (for later)

Decide the hosting model first, then: a DB overlay for the identity/secret values with the wizard writing DB instead of .env.local, an explicit "change your domain" migration flow (re-key + refetch), and secrets encrypted via secret-box (as VAPID/analytics/crosspost already are). Not before the model decision.

Blocks the full "configure everything from the web" vision; not required for #59's shipped scope.

[TemujinCalidius]

Working through this properly — the "secrets" half is nearly empty

Auditing what's actually left, bucket by bucket, most of it turns out to be already done, structurally immovable, or a bad idea. That reframes the decision.

Root secrets

Var	Verdict
ADMIN_SECRET	Cannot move. secret-box.ts derives its AES-256-GCM key from it — it's what encrypts every other secret in the DB. Storing it in the thing it encrypts is circular.
DATABASE_URL	Cannot move. You need it to read the database.
SETUP_TOKEN	Already done. setup-token.ts generates and stores it as a SiteSetting when the env var is absent; env is only a short-circuit. No work left.
TRUSTED_PROXY	Shouldn't move (argued below).
SMTP_* + DAYONE_EMAIL	The only genuine candidate.

So of five, two are impossible by construction, one already shipped, one is a judgement call, and one is real work.

Why TRUSTED_PROXY should stay env-only. It's read per-request in client-ip.ts and decides whether X-Forwarded-For is trusted for rate limiting — the exact fix #109 landed after that header proved spoofable. It's not a preference, it's an assertion about your network topology that only whoever deployed the box can make. Making it web-editable means an admin-panel compromise can switch off the spoofing defence sitewide. Deployment facts belong in deployment config.

Why SMTP_* / DAYONE_EMAIL is a genuine candidate. It's one self-contained integration (Day One crossposting, crosspost.ts:311-325) with a password in it — structurally identical to the Bluesky/Threads credentials and the Tinylytics API key, which already live encrypted in the DB with env fallback. It's the pattern, applied once more.

Federation identity

SITE_URL / FEDI_HANDLE / FEDI_DOMAIN are a different question entirely, and the hard one. They're baked into the ActivityPub actor id, WebFinger, signature keyId, and every RSS/permalink. Making them editable at runtime isn't a config change, it's an identity migration: existing followers hold your old actor id and public key, so changing them without a re-key and refetch silently breaks federation — the same class of failure #310 guards against. The setup wizard already writes them safely once (#301); the open question is only whether a running instance should rewrite them.

---

The three ways to close this

A — Declare env the source of truth. Identity and root secrets stay in .env.local; the wizard writes them once at install. SMTP_* stays too. Close this as intentional. Zero risk, and honest about what a self-hosted app is. Cost: the "configure everything from the web" story keeps one asterisk.

B — Ship the safe subset, close the rest. ⭐ Recommended. Move SMTP_* + DAYONE_EMAIL into encrypted DB settings with env fallback, exactly as the crosspost credentials already work. Then close this issue: identity stays env-only by decision, with the reasoning recorded, rather than lingering as an open question. Small, non-breaking, and it finishes the pattern instead of leaving one integration inconsistent.

C — Full DB-backed identity. Everything web-editable, plus an explicit "change your domain" flow: re-key the actor, notify/refetch followers, handle the interim where both ids are in the wild. This is a genuine feature with a real failure mode, worth doing only if config must live per-instance in the database — i.e. driven by a hosting model, not by tidiness. It should be its own issue with its own design, not the tail of this one.

My read: B. It removes the last inconsistency in the secrets story for a day's work, and converts the identity question from "deferred" into "decided" — which is worth more than leaving it open indefinitely. If a hosting model later demands C, that's a new issue with a clear starting point.

[TemujinCalidius]

Decision: C — full DB-backed identity.

Samuel's call. Recording it here with the design, so this issue becomes the umbrella for the work rather than an open question.

I'd flagged B as lower-risk; C is the decision, so here is what it actually takes. It is a real feature with a real failure mode, and the sequencing below is what keeps it from breaking federation.

What the surface actually looks like

Measured on dev, not estimated:

	Count
siteConfig.url references	32 across 18 files
Direct process.env.SITE_URL / FEDI_DOMAIN / FEDI_HANDLE reads	31
siteConfig.fediAddress	10

The direct env reads cover the entire ActivityPub surface — .well-known/webfinger, ap/inbox, ap/outbox, ap/followers, ap/following, http-signatures.ts, federation.ts — plus micropub, XML-RPC, the feeds and OAuth. Several are module-level captures (const siteUrl = siteConfig.url in federation.ts:7), evaluated at import, so a runtime value wouldn't be seen at all without touching each one.

That's the crux: you can't overlay a value that ~50 sites read directly from the environment at import time. Everything else depends on fixing that first.

Phasing

Phase 0 — centralise the reads. One accessor (src/lib/identity.ts), still env-backed, no behaviour change. Replace all 63 direct reads and every module-level capture. Pure refactor, fully testable, and the prerequisite for every later phase. This is the concrete next step and is safe to land on its own.

Phase 1 — DB overlay, read-only. The accessor prefers identity.* SiteSetting rows over env; nothing writes them yet. Identical behaviour when unset. Needs a cache (identity is read on hot paths like signature verification) with explicit invalidation on change.

Phase 2 — the change-domain flow. The actual feature, and the dangerous part. ActivityPub has no rename: remote servers cache your actor by id, and your followers hold the old one. The mechanism is alsoKnownAs on the new actor plus a Move activity to followers — which is best-effort: not every server honours it, so some followers will be lost. That has to be stated in the UI, not buried. Also interacts with #310 (a changed identity must not look like a lost keypair), and the old id should stay resolvable as long as possible.

Phase 3 — admin UI + wizard writes DB instead of .env.local, plus a migration path for existing .env installs.

Staying env-only regardless

ADMIN_SECRET (it derives the key that encrypts every DB secret — circular) and DATABASE_URL (needed to read the DB at all). SETUP_TOKEN is already DB-backed. TRUSTED_PROXY stays env — it's a per-request spoofing defence asserting network topology, and web-editing it lets an admin-panel compromise disable the protection #109 added.

SMTP_* / DAYONE_EMAIL still worth moving to encrypted settings; it's independent of the above and can land any time.

Sequencing note

Phase 0 is a ~63-site refactor through the federation-critical path, where a wrong value fails silently — posts stop verifying on remote servers with nothing in the logs. It should not be rushed into the tail of a session with v1.19.0 about to be cut. Starting it fresh, after the release, on its own branch.

[TemujinCalidius]

Phase 0 landed on dev in #337 (tracked as #333).

Federation identity now resolves through a single accessor — 63 direct reads and module-level captures removed, site.config.ts derives from it too, so there's exactly one derivation. That's the prerequisite cleared: a module-level const evaluated at import could never see a runtime value, so no overlay was possible before this.

It also fixed a live bug on the way — WebFinger had its own identity derivation, which made any instance with SITE_URL but no FEDI_DOMAIN silently undiscoverable. Details on #333.

Next: Phase 1 — the DB overlay (identity.* SiteSetting rows preferred over env, read-only, no UI), which needs a cache with explicit invalidation since identity is read on hot paths like signature verification. Then Phase 2, the change-domain Move/alsoKnownAs flow — the risky one.

[TemujinCalidius]

Phase 1 landed (#338) — and Samuel's point reshapes Phase 2

Phase 1 is on dev: identity resolves runtime override → environment → default, loaded once at boot and awaited before anything serves. Read path only — nothing writes identity.* yet, so behaviour is unchanged on every existing instance. The overlay lives in a server-only identity-store.ts because identity.ts is reachable from client bundles via site.config.ts, and that separation is what keeps getIdentity() synchronous for its ~60 call sites.

Phase 2 needs rethinking, and the reason is decisive

Samuel raised the constraint that changes the shape of this:

if you are running a fedihome instance and get a new domain, you lose the old domain and can't point your old followers to the new anymore, which would break that, resulting in you losing followers anyway.

That's right, and it means Phase 2 was framed wrongly. I'd described it as a "change your domain" flow — an operation an instance performs on itself. It can't be, because of how the protocol verifies a move:

1. The new account carries alsoKnownAs naming the old actor.
2. The old account publishes Move and sets movedTo.
3. Every remote server fetches both ends and only moves the follow if they agree.

Step 3 requires the old domain to still be serving. A Move published from a domain you no longer control cannot be verified, so nothing moves. Which means the operation isn't "rename this instance" — it's a migration between two live instances, and the old one has to outlive the switch by a good margin.

So Phase 2 becomes two separable things:

• Outbound migration support — alsoKnownAs + movedTo on our actor, and publishing Move to followers. Belongs here.
• Inbound Move handling — split out to Follow accounts across a server move: handle incoming Move activities #339, because it's not about changing our own domain at all: today, when an account you follow migrates, FediHome ignores the Move and you silently stop hearing from them. That affects every instance right now.

Worth stating the current asymmetry plainly: a FediHome instance can presently be migrated from, migrated to, or follow someone else's migration — none of the three.

Documented in the meantime

docs/fediverse-setup.md gained a Changing Your Domain section in #338, since the guidance is actionable today even without the code: treat your domain as permanent; if you must move, stand up the new instance alongside the old, publish the move, and leave the old server running for weeks before decommissioning. It also records the detail that makes this sharper than it first appears — post URLs are stored absolutely, so a database restore onto a new domain carries the old host in every historical post.