feat: isolate canonical known-host source validation

[xnoto]

Summary

Add the owner-approved source-side diagnostic to distinguish an absent canonical known-host entry from a delivery problem. The new check-known-host-source workflow has credentialless synthetic tests on PRs and a separately confirmed, main-only manual source job. The diagnostic itself runs no OpenTofu/state operation, does not contact Hero, and does not write GitHub secrets.

Four new files: a Python-stdlib helper, synthetic tests, workflow, and operator guide. No encrypted source, Terraform resource, recipient mapping, shared workflow, or Hero workflow changes.

Fixes: N/A — owner-approved investigation of the consumer preflight's missing-host-entry result.

Type of change

• Bug fix
• Feature / enhancement
• Documentation
• Infrastructure (OpenTofu root or module)
• GitOps desired state (manifests, kustomize, charts, SOPS/KSOPS secrets)
• Container image
• CI / reusable workflow
• Refactor / cleanup
• Breaking change

Validation

• Required pull-request checks pass — pending synthetic-tests and existing OpenTofu test/plan.
• Generated or centrally distributed files were regenerated by their owning automation, not hand-edited — none changed; generated README remains untouched.

Synthetic tests use temporary generated keys and real Python streaming producers in place of SOPS; they never access KMS or real encrypted data. Coverage includes matching/hashed/missing entries, extraction failures, oversized/infinite streams, timeout termination, mode-restricted temporary files, cleanup, fixed-output assertions, invalid inputs, and workflow main/manual/credential guards.

Adversarial, infrastructure-security, DevOps integration, and QA reviews have no unresolved Critical/High findings. Review fixes replaced unbounded buffered extraction with bounded reads (1 MiB plus one overflow-detection byte), discarded SOPS stderr, and made temporary paths run/attempt-specific. No local tests or decryption ran; CI is the execution authority.

Impact and rollout

Owner/producer: tfroot-github maintainers own this thin orchestration around existing SOPS/OpenSSH tools and its sole manual-workflow consumer. No new package, service, image, or shared-workflow fork is introduced.

Compared path: canonical ssh_known_hosts -> existing HERO_HOST_CONFIG_SSH_KNOWN_HOSTS resource for hero-host-config -> its runner-local known_hosts file. Both diagnostics use OpenSSH ssh-keygen -F with the same supplied destination. A source match does not prove byte equality, ED25519 validity, host identity, or successful distribution.

Diagnostic selection: PRs run only synthetic tests in this new workflow. A new dispatch from main after separate authorization uses the existing production environment, arc-tf image, and SOPS KMS role. OIDC/KMS access is not proven until that dispatch. The helper extracts the field inside CI, discards tool diagnostics, prints only a fixed result category, and removes its temporary plaintext file. No artifacts/caches retain source material.

IMPORTANT MERGE GATE: the repository's existing OpenTofu workflow remains unchanged. PR creation still triggers its normal test/plan, and merging still triggers its normal main workflow, including its environment-scoped apply. Current main includes unrelated repository-deletion work whose latest apply failed. This PR is NOT authorization to retry or apply those changes. Review the outstanding infrastructure plan and actual environment protection before authorizing merge; environment declaration alone does not establish a required-reviewer gate. No merge or manual dispatch has been performed.

Stages: authored/branch-published and independently reviewed; CI pending. Merge and manual source diagnostic are separate confirmation gates. Consumer comparison and runtime resolution remain pending. No tfroot-libvirt cleanup is included.

Rollback: close before merge or remove the four new files through a reviewed PR. The diagnostic changes no remote secret or host state. Interruption cleanup is best-effort; a host crash cannot guarantee deletion, as documented.

Safety and secrets

• Contains no plaintext secrets, decrypted SOPS values, state files, kubeconfigs, tokens, or private endpoints.
• No local OpenTofu init/plan/apply/destroy/import/state operations were run or claimed — plans come from pull-request checks.
• Breaking or irreversible effects are described above with rollback notes.

AI-assisted implementation and independent reviews. The source check does not expose values, keys, fingerprints, hashes, or subprocess errors. Dispatch destinations can appear as ordinary workflow input metadata; no endpoint is committed.

[github-actions]

OpenTofu Test

OpenTofu test passed.

View the workflow run.

View run output

Terraform validate.......................................................Passed
Terraform validate with tflint...........................................Passed
Checkov..................................................................Passed
Terraform fmt............................................................Passed
Terraform docs...........................................................Passed
Detect hardcoded secrets.................................................Passed
check for case conflicts.................................................Passed
check for merge conflicts................................................Passed
check for broken symlinks............................(no files to check)Skipped
check vcs permalinks.....................................................Passed
detect destroyed symlinks................................................Passed
detect private key.......................................................Passed
fix end of files.........................................................Passed
mixed line ending........................................................Passed
trim trailing whitespace.................................................Passed
don't commit to branch..................................................Skipped
check for added large files..............................................Passed

[github-actions]

OpenTofu Plan

OpenTofu plan passed.

View the workflow run.

View run output

OpenTofu will perform the following actions:

  # github_workflow_repository_permissions.release_automation will be created
  + resource "github_workflow_repository_permissions" "release_automation" {
      + can_approve_pull_request_reviews = true
      + default_workflow_permissions     = "read"
      + id                               = (known after apply)
      + repository                       = "terraform-libvirt-domain"
    }

Plan: 1 to add, 0 to change, 0 to destroy.
OpenTofu will perform the following actions:

  # github_workflow_repository_permissions.release_automation will be created
  + resource "github_workflow_repository_permissions" "release_automation" {
      + can_approve_pull_request_reviews = true
      + default_workflow_permissions     = "read"
      + id                               = (known after apply)
      + repository                       = "terraform-libvirt-domain"
    }

Plan: 1 to add, 0 to change, 0 to destroy.

[xnoto]

CI completed successfully at head e1e1e97d7fda8ac1449e986bde0d46f0678ffd5b:

• Synthetic source-diagnostic tests: passed.
• OpenTofu test: passed.
• OpenTofu plan: passed.
• check-source and opentofu / apply: skipped on this PR, as intended.

No source diagnostic, real field extraction, host connection, or apply was dispatched by this change. Successful plan execution is not a claim of a no-op or a reviewed exact infrastructure delta. Merge remains on hold pending explicit owner approval covering the existing main-apply trigger and outstanding unrelated infrastructure scope. After any separately authorized merge, manually dispatch only check-known-host-source with the intended destination to obtain the source-side classification. The diagnostic itself does not run OpenTofu.