Allow providing the master API key via MASTER_API_KEY env var #19

New issue

Closed

opened 2026-08-07 10:19:41 +00:00 by james.oates · 1 comment

james.oates commented

2026-08-07 10:19:41 +00:00

Owner

Problem

The master API key is only auto-generated on first boot (main.rs, when get_master_key() returns None) and printed once to stdout. There is no way to pre-define it — unlike ENCRYPTION_KEY, which the operator can supply via env.

This blocks automated / declarative deployment: you can't bake the master key into your deploy secrets ahead of time and have a fresh instance come up using it. You currently have to boot, scrape the key from the logs, and feed it back in — not viable for reproducible infra.

Fix

Read a MASTER_API_KEY env var at startup (unprefixed, matching ENCRYPTION_KEY/DATABASE_URL infra-config convention):

If set, it is the source of truth: seed it on first boot, or update the stored master key to match on later boots (declarative, like ENCRYPTION_KEY). Do not print it — the operator already has it.
If unset, keep current behaviour (auto-generate + print once on first boot).
Reject an obviously-weak provided value (min length guard).

Coordination with #18

Forward-compatible with hashing API keys at rest (#18): the env var always carries the raw key; when #18 lands, the ingestion path here hashes it before storing, exactly like a key created via the API. No change to the env contract.

Picking this up immediately — it unblocks automated ER deployment.

## Problem The master API key is **only** auto-generated on first boot (`main.rs`, when `get_master_key()` returns `None`) and printed once to stdout. There is no way to pre-define it — unlike `ENCRYPTION_KEY`, which the operator can supply via env. This blocks automated / declarative deployment: you can't bake the master key into your deploy secrets ahead of time and have a fresh instance come up using it. You currently have to boot, scrape the key from the logs, and feed it back in — not viable for reproducible infra. ## Fix Read a `MASTER_API_KEY` env var at startup (unprefixed, matching `ENCRYPTION_KEY`/`DATABASE_URL` infra-config convention): - If set, it is the source of truth: seed it on first boot, or update the stored master key to match on later boots (declarative, like `ENCRYPTION_KEY`). Do **not** print it — the operator already has it. - If unset, keep current behaviour (auto-generate + print once on first boot). - Reject an obviously-weak provided value (min length guard). ## Coordination with #18 Forward-compatible with hashing API keys at rest (#18): the env var always carries the **raw** key; when #18 lands, the ingestion path here hashes it before storing, exactly like a key created via the API. No change to the env contract. Picking this up immediately — it unblocks automated ER deployment.

james.oates referenced this issue from a commit

2026-08-07 10:32:48 +00:00

Allow pre-defining the master API key via MASTER_API_KEY (#19)

james.oates commented

2026-08-07 10:35:25 +00:00

Author

Owner

Resolved in 5a0008b.

MASTER_API_KEY (unprefixed, like ENCRYPTION_KEY) is read at startup and is authoritative when set:

fresh DB → seeded with the provided value;
already matches the stored key → no-op;
differs → the stored master key is rotated to the new value (the previous value stops working — logged as a warning, so it's a conscious, visible change);
unset → unchanged auto-generate-and-print-once behaviour.

A value under 16 chars is rejected at startup (loud failure beats a weak key in an automated deploy). The seed/generate/match/rotate decision is a pure decide_master_key function with a unit test per branch; the IO stays in main.

Secrets are never echoed (covers your follow-up on this): an env-provided master key is never printed — only an auto-generated one is (so you can capture it). While here, the encryption-key load paths now log which source they came from (env / file / persisted path) without the key material — they were previously silent.

Forward-compatible with #18: the env carries the raw key; the single equality check and the store write are each in one place for the hashing work to update.

Docs: MASTER_API_KEY added to the env table, plus a commented docker-compose.yml example. Tests: all five decision branches + a DB test proving a rotate makes the new value the master and invalidates the old one. Full suite green (168), clippy and fmt clean.

This unblocks pre-defining the key for automated ER deployment.

Resolved in 5a0008b. `MASTER_API_KEY` (unprefixed, like `ENCRYPTION_KEY`) is read at startup and is **authoritative** when set: - fresh DB → seeded with the provided value; - already matches the stored key → no-op; - differs → the stored master key is **rotated** to the new value (the previous value stops working — logged as a warning, so it's a conscious, visible change); - unset → unchanged auto-generate-and-print-once behaviour. A value under 16 chars is rejected at startup (loud failure beats a weak key in an automated deploy). The seed/generate/match/rotate decision is a pure `decide_master_key` function with a unit test per branch; the IO stays in `main`. **Secrets are never echoed** (covers your follow-up on this): an env-provided master key is never printed — only an auto-generated one is (so you can capture it). While here, the encryption-key load paths now log *which source* they came from (env / file / persisted path) without the key material — they were previously silent. Forward-compatible with #18: the env carries the raw key; the single equality check and the store write are each in one place for the hashing work to update. Docs: `MASTER_API_KEY` added to the env table, plus a commented `docker-compose.yml` example. Tests: all five decision branches + a DB test proving a rotate makes the new value the master and invalidates the old one. Full suite green (168), clippy and fmt clean. This unblocks pre-defining the key for automated ER deployment.

james.oates closed this issue

2026-08-07 10:37:47 +00:00

james.oates referenced this issue from a commit

2026-08-07 10:59:18 +00:00

Support MASTER_API_KEY_FILE for file-mounted secrets (follow-up to #19)

james.oates referenced this issue

2026-08-07 11:37:10 +00:00

[backlog, low priority] Source encryption key from OpenBao, unsealed/brokered via TPM #20