Files
Alphaeus Mote 39441eced9 feat(auth): record a generated first-start admin password and add reset-admin
An empty INITIAL_ADMIN_PASSWORD now means generate and record: the one-time
password goes to <data>/initial-admin-password.txt (Administrators, SYSTEM and
the server's own account only; mode 600 elsewhere) and the log only says where.
The file is removed once the password is changed or reset. reset-admin (alias
auth-reset) reads the standalone appsettings.json, so it reaches the same
database with the service running or stopped, takes --user/--password, turns
the account back on and is audited. The compose scripts stop generating the
password into .env.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-04 20:42:38 -05:00
..

secrets/

Generated secret material lives here and is git-ignored (only this README is committed).

Generate development secrets:

./scripts/New-LocalSecrets.ps1

This produces:

File Purpose
../.env Compose environment (initial admin password, NATS signing seed, …)
nats/operator.nk NATS operator seed — SECRET
nats/account.nk NATS application account seed — SECRET
nats/account-signing.nk Account signing seed used by the backend to issue user JWTs — SECRET
nats/sys-account.nk / nats/sys-user.nk System account/user seeds — SECRET
nats/resolver.conf Operator JWT + account preload mounted into the NATS container

How the NATS keys are generated

Keys are real Ed25519 NKeys generated via the backend's nats-auth CLI (dotnet run --project src/Backend -- nats-auth init), which uses the official NATS.NKeys/NATS.Jwt libraries — the same code path the backend uses at runtime to issue agent and browser user JWTs. If you prefer nsc, an equivalent manual flow is documented in the root README.

Required secrets (production)

  • INITIAL_ADMIN_PASSWORD — optional first-boot admin password; left empty, the backend generates one and records it in its data folder (initial-admin-password.txt, administrators only)
  • NATS_OPERATOR_SEED — operator identity (kept offline after setup)
  • NATS_ACCOUNT_SEED — application account identity
  • NATS_ACCOUNT_SIGNING_SEED — given to the backend for user JWT issuance
  • OIDC_CLIENT_SECRET — only when OIDC is enabled
  • GITEA_TOKEN — CI release/push automation
  • CONTAINER_REGISTRY_PASSWORD — if different from the Gitea token
  • CODE_SIGNING_CERT_PASSWORD — optional release signing

Never log or commit any of these. Rotate by re-running generation and restarting the affected services.