Refactor secrets inventory into docs + machine-readable JSON

2026-04-21 11:24:45 +10:00
parent 451be4ab0d
commit 9f36dabcdc
9 changed files with 214 additions and 64 deletions
@@ -0,0 +1,52 @@
+# Security Secrets
+
+## Overview
+
+This page explains how secret material is organized in this repository and where to find both human-readable and machine-readable references.
+
+For machine-readable inventory metadata, use [`../secrets/inventory.json`](../secrets/inventory.json).
+
+## Scope and authority
+
+- Canonical example template: [`../secrets/.env.secrets.example`](../secrets/.env.secrets.example)
+- Runtime-loaded secret env file (local, non-committed): `../secrets/stack-secrets.env`
+- Docker secret files (local, non-committed): `../secrets/*.txt`
+
+Treat the example template as the canonical shape for expected environment variables.
+
+## Secret material types
+
+1. **Template variables in `.env.secrets.example`**
+   - Document expected variable names and usage expectations.
+2. **Local runtime env file (`stack-secrets.env`)**
+   - Holds local runtime secret values loaded during compose rendering.
+3. **Local Docker secret files (`*.txt`)**
+   - Hold password/token material consumed via `*_FILE` style configuration.
+4. **Externally managed secret inputs**
+   - Some values are managed outside shared templates and provided through file mounts or environment substitution.
+
+## Machine-readable inventory
+
+- Primary automation source: [`../secrets/inventory.json`](../secrets/inventory.json)
+- Human guidance source: this page
+
+Automation should parse `secrets/inventory.json` directly rather than scraping Markdown tables.
+
+## Setup and deployment prerequisites
+
+Before running compose operations, follow [`./deployment-prerequisites.md`](./deployment-prerequisites.md).
+
+## Commit safety rules
+
+Never commit:
+
+- `secrets/stack-secrets.env`
+- real `secrets/*.txt` secret files
+- real Terraform `.tfvars` files containing credentials
+- Terraform state files with sensitive runtime metadata
+
+## Related docs
+
+- [`./deployment-prerequisites.md`](./deployment-prerequisites.md)
+- [`./docker-environment.md`](./docker-environment.md)
+- [`./source-of-truth.md`](./source-of-truth.md)