Module keys 

Runtime API key store (paid-path plan S1, gap G3).

Keys live in a SQLite database in the data dir (keys.db), not in a flat file loaded once at startup: a key can be issued, rotated, and revoked while the server runs, by writing to the store — the admin subcommand (codetopo-server keys …) does exactly that, and the server’s next verification sees the change with no restart.

A secret is never stored. The row carries a per-key random salt and SHA-256(salt ‖ secret); verification recomputes the hash of the presented secret and compares hashes with subtle::ConstantTimeEq, so the wire contract (Authorization: Bearer <key_id>:<secret>) and its constant-time property are unchanged — only the storage moved.

The legacy flat key_id:secret file is an import source, not a store: at startup, when the database holds no active key and the file exists, its entries are imported (hashed, plan SELF_HOSTED_PLAN). Existing single-host deployments therefore keep working untouched, and the file can be deleted once the import has happened. One value never imports: the documented example secret the README quickstart once printed (DOCUMENTED_EXAMPLE_SECRET) — it is public, so the import refuses any file still carrying it.

Keys are provisioned with a plan name (the paid tier’s plans arrive with the billing bridge; the store only records the string) and a lifecycle status: active or revoked. Only active keys verify.

Structs

KeyStore

The key store: one SQLite connection, serialised behind a mutex.

KeySummary

One key’s operator-visible state. Never carries a secret or a hash.

VerifiedKey

What a successful verification yields: the key’s identity and plan.

Constants

DEFAULT_PLAN

Plan a key is issued with when the admin names none: the hosted tier from the paid-path plan.

DOCUMENTED_EXAMPLE_SECRET

The secret the README quickstart printed as its example credential (demo-key:change-me) until the release-gate fix loop. It is public knowledge — anyone who has read the README knows it — so a keys file still carrying it would hand the server to the first caller who tries it. KeyStore::import_legacy_file refuses it by name (fleet release gate F-3).

SELF_HOSTED_PLAN

Plan recorded for keys that predate plans: the operator’s own keys (legacy flat-file import, KeyStore::parse), not a billed tenant’s.

STORE_FILE_NAME

File name of the key store inside the data dir.

Functions

default_keys_file

Convenience: where the legacy flat keys file lives by default.

parse_bearer

Splits Authorization: Bearer <key_id>:<secret> into its two parts.