net-kingdom/canon/standards/credential-management_v0.2.md

Credential Management Standard — net-kingdom

Version: 0.2 Status: current Supersedes: v0.1 (retired with NK-WP-0004)

---

1. Purpose

Define how service credentials are generated, stored, rotated, and recovered in the net-kingdom SSO/MFA platform. This standard governs operational security of all secrets used by the Authelia + LLDAP + KeyCape + privacyIDEA stack and its PostgreSQL backend.

---

2. Trust Hierarchy

age private key  ─────────────►  encrypts secrets.enc/ in git
      │
      └──► ops bundle (encrypted snapshot of all secrets)
                └──► stored offsite; decrypt with age key

break-glass passwords  ────────►  direct service access if cluster/auth is down
      │
      └──► stored in human's personal password manager

K8s Secrets  ──────────────────►  live credential store for running services
      │
      └──► created by create-secrets.sh scripts; sourced from secrets.enc/

KeePassXC is NOT in the operational path. If you choose to import the emergency bundle into KeePassXC for personal use, that is your business — it is not required or assumed by any tooling in this repo.

The age private key and SOPS/age-encrypted git files are the credential store. The ops bundle is the backup. The emergency bundle is the human's key ring.

---

3. Credential Lifecycle

Phase 0 — Bootstrap (run once, agent-driven)

make creds-agent-init

This single command runs the full bootstrap end-to-end:

1. Verifies prerequisites (age, kubectl, openssl, cluster)
2. Generates or verifies the age keypair at ~/.config/sops/age/keys.txt
3. Generates all service secrets via gen-secrets.sh
4. Encrypts them to secrets.enc/ with age and commits
5. Injects them into the cluster via creds-apply.sh
6. Verifies all K8s Secrets exist
7. Waits for privacyIDEA to be Ready, then runs enckey bootstrap + admin creation
8. Applies KeyCape secrets (requires pi-admin)
9. Creates the ops bundle (age-encrypted snapshot)
10. Delivers the emergency bundle to the terminal for human storage ← only human touchpoint
11. Shreds all plaintext and marks bootstrap_complete: true

The script resumes from where it left off if interrupted — each phase is tracked in creds-state.yaml.

Phase 1 — Normal operation

No human credential management is needed after bootstrap. All secrets live in:

• secrets.enc/ — encrypted in git (decrypt with age key)
• K8s Secrets — live cluster state (updated by creds-apply.sh)

Phase 2 — Rotation

make creds-rotate SECRET=<name>            # guided interactive mode
SECRET=<name> bash sso-mfa/bootstrap/creds-rotate.sh --non-interactive  # agent mode

Rotation is handled per-secret with appropriate atomicity guarantees. See Section 5 for details.

Phase 3 — Recovery

Use the emergency bundle stored in your personal password manager. See Section 4 — Emergency Bundle.

---

4. Emergency Bundle

Contents

Item	Purpose
age private key	Decrypt any secrets.enc/*.age file from git
privacyIDEA admin password	Direct access to privacyIDEA if cluster/auth is down
LLDAP admin password	Direct LDAP directory access
PostgreSQL root password	Direct database access
break-glass user password	Emergency login if Authelia/KeyCape is down
ops bundle location + decrypt command	Point-in-time snapshot of all secrets

Delivery

The emergency bundle is displayed once in the terminal at the end of make creds-agent-init. The operator must copy it into their personal password manager before pressing Enter to continue.

The confirmation gate is a deliberate security control — bootstrap does not complete until the human confirms receipt.

Re-delivery

If the emergency bundle is lost or stolen:

make creds-emergency-reprint

This reprints the bundle from the current age key and secrets. It does not rotate any secrets — if you suspect compromise, rotate the affected secrets separately with make creds-rotate.

Storage recommendations

Store the emergency bundle in one or more of:

• 1Password, Bitwarden, KeePassXC, or equivalent
• Encrypted offline storage
• Printed and physically secured (air-gapped scenarios)

The agent does not care which — it only cares that you confirm receipt.

Recovery procedure

1. Restore ~/.config/sops/age/keys.txt from the emergency bundle
2. Clone net-kingdom repo
3. Run: make creds-apply — re-injects all secrets from secrets.enc/
4. Use break-glass passwords for direct service access if needed

---

5. Secret Rotation

Rotatable secrets

Secret	Blast radius	Notes
PI_SECRET_KEY	Low — invalidates PI sessions	Safe to rotate anytime
PI_DB_PASSWORD	Medium — DB + pod	Atomic update required
LLDAP_JWT_SECRET	Low — invalidates LLDAP sessions	Safe to rotate anytime
LLDAP_LDAP_USER_PASS	High — 3-way coordinated	Authelia + KeyCape + LLDAP web UI
AUTHELIA_SESSION_SECRET	Low — invalidates sessions	Safe to rotate anytime
AUTHELIA_KEYCAPE_CLIENT_SECRET	Medium — 2-way atomic	Authelia + KeyCape together
KEYCAPE_RSA_KEY	High — invalidates all JWTs	Causes brief auth outage
BREAKGLASS_PASSWORD	Minimal	Rotate freely

Non-rotatable

Secret	Reason
PI_PEPPER	Rotating requires re-hashing all PI user passwords

Age key rotation

Rotating the age private key is a special case:

1. Generate a new age key
2. Re-encrypt all secrets.enc/ files with the new public key (make sops-rotate)
3. Commit
4. A new emergency bundle must be delivered before the old key is revoked (see Section 4)

---

6. Ops Bundle

The ops bundle is an age-encrypted tar archive of all plaintext secrets at a point in time. It is created automatically during bootstrap and can be refreshed with:

make creds-bundle

Store the bundle offsite (cloud, external drive, second location). Decrypt:

age -d -i ~/.config/sops/age/keys.txt ops-bundle-<date>.tar.age | tar xf -

---

7. Prohibited Patterns

The following are permanently prohibited:

1. Committing secrets/ (plaintext) to git — the pre-commit hook blocks this; do not bypass with --no-verify

2. Storing secrets in KeePassXC as the primary credential store — KeePassXC is for optional personal backup of the emergency bundle only

3. Skipping the emergency_bundle_delivered confirmation gate — even in non-interactive or automated runs, the agent MUST NOT mark bootstrap complete until the human confirms receipt. This gate exists to ensure break-glass access is always available.

4. Hardcoding secrets in manifests or ConfigMaps — all service secrets must flow through K8s Secrets created by create-secrets.sh scripts

5. Storing the age private key in the repo — the key lives outside the repo at ~/.config/sops/age/keys.txt

---

Appendix A — KeePassXC Group Structure (optional)

If you choose to import the emergency bundle into KeePassXC, a suggested group structure for the break-glass passwords is:

net-kingdom/
  Break-glass/
    privacyIDEA admin    username=pi-admin        password=<PI_ADMIN_PASSWORD>
    LLDAP admin          username=admin           password=<LLDAP_LDAP_USER_PASS>
    PostgreSQL root      username=postgres        password=<PG_ROOT_PASSWORD>
    break-glass user     username=break-glass     password=<BREAKGLASS_PASSWORD>
  age key               (attach keys.txt as binary attachment)
  ops bundle decrypt    (store path + decrypt command as a note)

This is entirely optional — the agent does not read from or write to KeePassXC.