Changelog 2026-07-10 -- OpenTofu state file security posture (DOCFIX-175)

No live infrastructure touched -- no tofu binary has ever been run in any session that authored this repo clone, so no terraform.tfstate exists yet. This is a preventive fix, found while reviewing what's genuinely missing from the VR1 buildout ahead of Stage 1's own first real tofu apply (runbooks/dc-dc-phase0-vcloud-prep.md Step 10 -- DC1 planes + Office1 pool

• mesh links), not a live incident.

Correction made mid-delivery, worth recording: the first draft of this work assumed Stage 3 (dc-dc-phase2-tofu-dc-substrate.md) was the first real apply, based on that file's name suggesting it was "the OpenTofu stage." Reading the actual runbooks directly (not inferring from filenames) showed Stage 1's own Step 10 applies DC1's planes, Office1's storage pool, and the three mesh links -- exactly what's already uncommented in opentofu/main.tf today -- well before Stage 3 touches anything. Caught and fixed before committing, same "verify against the actual file, not the name" discipline this repo already uses everywhere else.

The gap

Nothing in this repo documented how OpenTofu's own state file is protected. No backend block is configured anywhere (versions.tf/main.tf are silent on it; every stage's own tofu init runs -backend=false), so state defaults to a local terraform.tfstate in whatever directory tofu is invoked from (the Office1 operator VM, per opentofu/README.md's own framing). Two real problems follow from that:

1. Plaintext secrets in state. var.maas_api_key is marked sensitive = true, but that flag only redacts the value from CLI/plan OUTPUT -- verified against HashiCorp's own current documentation (not assumed): "Terraform stores values with the sensitive argument in both state and plan files, and anyone who can access those files can access your sensitive values" (developer.hashicorp.com/terraform/language/ manage-sensitive-data, fetched 2026-07-10). This applies regardless of whether the value is consumed by a resource argument or, as here, only by a provider {} block -- the docs draw no such distinction. At Stage 1 time maas_api_key may still be a placeholder (MAAS doesn't exist for real until Stage 2 -- see Stage 1's own "Known gap" section), but the moment a REAL TF_VAR_maas_api_key is exported for any later plan/apply, it lands in state in the clear, with no protection beyond filesystem permissions -- and nothing documented what those permissions should be.
2. State was not gitignored. Harmless only by accident (no state file has ever existed in a repo clone), not by design -- a real gap that would have let a future git add -A commit a plaintext-credential-bearing file to history.

Neither problem was previously logged anywhere -- not the gap register, not opentofu/README.md, not .gitignore.

Fix

1. .gitignore: added opentofu/**/*.tfstate, *.tfstate.*, .terraform/, *.tfplan, *.auto.tfvars*, and the standard Terraform override/crash-log patterns. .terraform.lock.hcl deliberately NOT excluded (provider-version pin; matches this repo's own exact-release-not- range discipline already established in versions.tf).
2. opentofu/variables.tf: maas_api_key's description now states the plaintext-in-state caveat inline and directs to TF_VAR_maas_api_key (never -var, which lands in shell history) -- consistent with, and reinforcing, dc-dc-phase0-vcloud-prep.md Step 7's own pre-existing "never commit maas_api_key" guidance for the input side; this delivery covers the output (state) side that guidance didn't.
3. opentofu/README.md: new "State file handling" section covering the risk and five concrete mitigations for VR1's rehearsal scope (never commit state, never pass secrets via -var, restrict file permissions, back up out-of-band per the existing ~/vault-init/-class secret discipline, and a flagged-not-decided note that local state has no locking -- a real Roosevelt/production gap, not solved here).
4. runbooks/dc-dc-phase0-vcloud-prep.md: Step 10 (the actual first real tofu apply in this whole repo) gained a "SECURE THE STATE FILE" callout immediately after it -- chmod 700/chmod 600, a git status check that the state file shows ignored not staged, out-of-band backup, and an explicit note that this is a standing check repeated after every subsequent stage's apply, not a one-time Stage 1 step.
5. runbooks/dc-dc-phase2-tofu-dc-substrate.md: Step 8 gained a short pointer back to Stage 1's callout (not a full duplicate) plus a note that Step 9 next is where this stage first needs a REAL MAAS credential to succeed.
6. docs/dc-dc-deployment-workflow.md: added gap-register item #18 (this gap, CLOSED) and #19 (a related, still-OPEN gap found in the same review pass: no teardown/rollback runbook exists for the VR1 OpenTofu layer itself -- tracked separately, not invented as a rushed addendum here).

What this deliberately does NOT do

Migrate to a remote backend (S3-compatible + lock table, Terraform Cloud, Consul, etc.) or add real state locking. Both are production-grade infrastructure decisions appropriate for Roosevelt planning, not something to invent unilaterally for a rehearsal repo that has never run tofu for real. Flagged explicitly in the README rather than silently deferred.

Verification

bash scripts/repo-lint.sh: 0 fail, 1 documented legacy warn. No script logic changed -- .gitignore, one .tf file (description-only edit, no resource/variable type change), one README, two runbooks (prose additions), one tracker doc. No test harness applies (nothing here is executable script logic); git diff --stat confirms no .sh/.py file in this delivery.

REVERT: git checkout HEAD~ -- .gitignore opentofu/variables.tf opentofu/README.md runbooks/dc-dc-phase0-vcloud-prep.md runbooks/dc-dc-phase2-tofu-dc-substrate.md docs/dc-dc-deployment-workflow.md (safe -- no live infrastructure depends on any of these; nothing here has ever been applied against real state).

Next actionable step

Gap #19 (VR1 teardown/rollback runbook) is a separate, tracked follow-up -- see its own changelog once delivered.