Publish sanitized current homelab architecture

docs/security.md

@@ -0,0 +1,67 @@
+# Security
+
+## Public/private boundary
+
+This public repository contains architectural patterns, sanitized examples, and high-level service placement. It is not used for production deployment.
+
+The private operational repository contains exact topology, runtime paths, deployment notes, and rollback artifacts. A separate encrypted repository stores environment files and other secrets.
+
+## Never publish
+
+- credentials, tokens, cookies, private keys, recovery codes, or session material
+- real `.env` files
+- internal or management addresses
+- MAC addresses, serial numbers, client IDs, or tunnel IDs
+- real domains, SSIDs, account names, or personal filesystem paths
+- physical locations or household records
+- raw controller exports, logs, database dumps, or backups
+- screenshots containing dashboards, account menus, or browser sessions
+
+## Secret workflow
+
+1. Generate or receive the secret outside chat and version control.
+2. Place it only in the runtime environment or secret manager.
+3. Sync recoverable copies into an encrypted secrets repository.
+4. Confirm Git stores ciphertext rather than plaintext.
+5. Scan staged files and outgoing history before push.
+6. If exposure occurs, rotate first, then clean current files and rewrite history.
+7. Re-clone and scan the rewritten remote before considering remediation complete.
+
+Removing a value from the latest commit does not remove it from Git history.
+
+## Repository controls
+
+The public repository uses two checks:
+
+- `scripts/check-public-safety.py` rejects infrastructure identifiers, private paths, key-like files, and common secret patterns.
+- Gitleaks scans complete Git history in CI.
+
+The scanner is deliberately conservative. Placeholder examples should use unmistakable values such as:
+
+```text
+CHANGE_ME_DATABASE_PASSWORD
+CHANGE_ME_API_TOKEN
+https://service.example.net
+/home/operator/application
+/mnt/storage/application-data
+```
+
+## Identity and ingress
+
+- Public application access passes through authenticated ingress.
+- SSO policy is applied before protected applications.
+- Administrative interfaces stay on private paths.
+- Tunnel credentials are isolated from application configuration.
+- Direct exposure is reserved for protocols that cannot traverse the authenticated HTTP path and is documented separately.
+
+## Workload isolation
+
+- Untrusted clients and lab systems cannot initiate general access to production lanes.
+- Databases are not published to the internet.
+- Containers receive only required networks and mounts.
+- Runtime control sockets are avoided or proxied with restricted permissions.
+- High-risk workloads use separate trust domains rather than relying on process isolation alone.
+
+## Reporting
+
+Do not open a public issue containing a suspected secret. Revoke it first and use a private contact channel for disclosure.