Jinemi/thermograph
4
0
Fork 0
Code Issues 2 Pull requests 3 Projects Releases Packages Wiki Activity Actions
thermograph/.claude/skills/key-gaps/SKILL.md

3.3 KiB
Raw Blame History

name description
key-gaps Audit which secret keys are missing, partially configured, or drifting across Thermograph environments (prod, beta, dev) — comparing the live /etc/thermograph.env on each box and/or the SOPS vault files (deploy/secrets/*.yaml). Use when asked about "key gaps", "missing keys/secrets", "what's not set", cross-environment secret drift, or as a pre-deploy / pre-cutover safety check. Reads key NAMES only, never values.

Key-gap audit

Reports, per environment and across them, where secret keys are missing or inconsistent — with special weight on the failure modes that bite silently here.

Run the deterministic script; don't eyeball it:

python3 .claude/skills/key-gaps/key_gaps.py <env>=<source> [<env>=<source> ...]

<source> is either a SOPS file (deploy/secrets/prod.yaml) or a key-list file (one KEY per line, or KEY=/KEY: lines). Keys are readable in a SOPS file even encrypted, so no age key or decryption is needed. Exit status is non-zero if any CRITICAL or required gap is found (so it also works as a CI/pre-deploy gate).

Audit the SOPS vault (offline, no SSH)

python3 .claude/skills/key-gaps/key_gaps.py \
  prod=deploy/secrets/prod.yaml beta=deploy/secrets/beta.yaml

Audit the LIVE boxes (read-only, key names only)

Gather the key names over SSH (never the values), then audit. Hosts/keys per INFRA.md:

K=~/.ssh/thermograph_agent_ed25519
# sudo: /etc/thermograph.env is root-owned (0640). On prod `agent` can read it
# directly too, but sudo works uniformly on both boxes.
ssh -i $K agent@169.58.46.181 'sudo grep -oE "^[A-Z_]+=" /etc/thermograph.env' > /tmp/prod.keys  # prod
ssh -i $K agent@75.119.132.91  'sudo grep -oE "^[A-Z_]+=" /etc/thermograph.env' > /tmp/beta.keys  # beta
python3 .claude/skills/key-gaps/key_gaps.py prod=/tmp/prod.keys beta=/tmp/beta.keys

Verify a SOPS cutover matches live

Before flipping a host onto the vault, confirm the rendered set equals the live set — mix the two source types for the same box:

python3 .claude/skills/key-gaps/key_gaps.py live=/tmp/prod.keys vault=deploy/secrets/prod.yaml

The Cross-environment drift section should report none for tracked keys.

Reading the output

  • CRITICAL — a required, self-generating secret is missing (THERMOGRAPH_AUTH_SECRET, THERMOGRAPH_VAPID_PRIVATE_KEY/_PUBLIC_KEY). Missing here is the worst case: the app silently mints a new value on boot, invalidating every login session and push subscription. Fix before deploying.
  • MISSING — a required secret is absent (POSTGRES_PASSWORD, THERMOGRAPH_METRICS_TOKEN, REGISTRY_TOKEN).
  • Feature GAP — a feature is partially configured (e.g. discord-account-linking has the app id but not the client secret), so it's silently broken. A fully-unset feature is "off", not a gap.
  • drift — a tracked key is in some environments but not others; often intentional, but worth a glance.

Keeping it current

The secret manifest (which keys are required / self-generating / grouped into features) lives at the top of key_gaps.py in REQUIRED, OPTIONAL_SELF_GEN, FEATURE_GROUPS, and STANDALONE_OPTIONAL. When a new THERMOGRAPH_* credential is added to deploy/thermograph.env.example / deploy/secrets/, add it there too.