Skip to content

security: establish trusted authority controller - #20

Merged
stacknil merged 8 commits into
mainfrom
stacknil/authority-controller-v1
Sep 16, 2026
Merged

stacknil merged 8 commits into
mainfrom
stacknil/authority-controller-v1

Conversation

@stacknil

@stacknil stacknil commented Sep 15, 2026 •

Copy link
Copy Markdown
Owner

Problem

The frozen commit-intrinsic worker defines P_v(H), but assumes that a trusted Python process has already imported the reviewed control code. This PR establishes the missing trusted bootstrap/controller boundary immediately above that worker.

Invariant

Authority evaluation is reachable only after an absolute CPython 3.12.3 Linux x86_64 interpreter enters with -I -S -B, an exact fixed environment, trusted control-root imports, fixed repository identity, exact refs/pull/<n>/head == H, the fixed v1 bundle identity, and non-overlapping verifier-owned roots.

Infrastructure, runtime, acquisition, worker-infrastructure, orchestration, or cleanup failures produce INFRASTRUCTURE_REFUSAL with no authority result.

Design decision

  • A minimal POSIX bootstrap clears loader/shell variables, starts /usr/bin/env -i, and invokes an absolute trusted Python path.
  • The Python controller validates the launch contract, binds repository ID 1130304545, owner ID 219124580, the canonical HTTPS remote, epoch v1, and bundle digest 6f25ebb773ce1453e8de623bca5aaecc936f1f188288f8df20aedeadb3bf4612.
  • The fixed PATH is /usr/bin:/bin; lookup must select /usr/bin/git before the frozen acquisition module runs.
  • Trusted modules come only from the reviewed control checkout. Acquired/materialized H remains data and never enters sys.path.
  • The controller emits one bounded canonical JSON envelope and no free-form diagnostic text.

Threat/failure model

The future trust root is the GitHub-hosted runner plus an immutable reviewed workflow SHA and these reviewed bootstrap/controller files. This code does not claim to neutralize loader or shell-startup influence that occurred before its own process began.

It defends after that boundary against hostile Python/home/XDG/pip/Repo Sentinel/virtualenv/path state, fake Python/Git, shadow stdlib and startup hooks, caller-selected repository/policy/control inputs, ref movement, target-code execution, raw diagnostic injection, and stale success after cleanup failure.

Rejected alternatives

  1. Inherit and denylist the parent environment. Rejected because it cannot establish a complete process contract.
  2. Discover Python or Git from caller PATH. Rejected because local executables can shadow trusted tools.
  3. Import controls from target H. Rejected because evaluated repository content must remain data.
  4. Allow caller-selected policy paths/digests. Rejected because authority policy must be externally fixed.
  5. Publish semantic failure for infrastructure refusal. Rejected because future publication must publish nothing without authority.

Compatibility

No workflow, GitHub App, OIDC, signer, Commit Status, branch/ruleset, acquisition, reader, materializer, worker, scanner, baseline, policy bundle, or report-schema behavior changes.

Validation

Completed on the submitted implementation:

  • focused controller suite on Windows: 17 tests, 1 expected POSIX skip;
  • focused controller suite on CPython 3.12.3 Linux x86_64: 17/17;
  • frozen acquisition/reader/materializer/base-relative worker/commit-worker/gate suites: 139 tests, 3 skips;
  • full repository suite: 163 tests, 4 platform skips;
  • pre-commit, Ruff check/format, POSIX shell syntax, taxonomy, README snapshot, pattern-library, and Markdown validation: pass;
  • 10/10 required mutation controls killed;
  • hostile environment, fake Git/Python, shadow stdlib/startup hooks, target-code non-execution, silent stderr, deterministic semantic fields, and cleanup override: pass;
  • trusted runtime: CPython 3.12.3, Linux x86_64, /usr/bin/python3.12;
  • trusted Git: /usr/bin/git, Git 2.43.0;
  • frozen-file scope diff and privacy/credential scan: clean.

Production-style HTTPS evidence:

  • a complete bootstrap -> controller -> HTTPS pull-head acquisition -> P_v(H) probe succeeded on reviewed head cd4b181c82774870267f72097405def2ea3abac6;
  • result: AUTHORITY_RESULT / SCANNER_FINDING, 262 total files, 252 scanned, 10 policy-excluded;
  • worker semantic digest: 83e4bf1e4594b593543993e497edeb39a7fcab77f753200396b6ae6278d12fbb;
  • report digest: 79091fad515a6d5399a63401a8f17f0ad0f6e2a6c9f5c45af7453463213fe200;
  • scratch cleanup completed with zero remaining entries;
  • the final submitted head 6cee46c37e3b4ac9e42dc1c499d16869fcc34e10 differs only by a test assertion; exact-head retries currently fail closed at acquisition because the local sanitized network path is intermittently resetting/stalling. No stale authority result is returned.

Exact-head configured CI:

  • taxonomy/front matter, Markdownlint, synthetic PASS/FAIL/redaction, and non-blocking baseline audit pass;
  • changed-file error gate reports 43 high-entropy findings in the new control code/documentation. The commit-intrinsic probe reproduces the same semantic SCANNER_FINDING;
  • the PR does not change the frozen base-relative baseline or evade the scanner by obscuring public constants. This remains an explicit review item.

Pending:

  • independent Business B review;
  • delayed final security review;
  • successful final-head HTTPS probe when the sanitized local network path is available.

Rollback

This PR activates no workflow and publishes no status. Rollback is deletion of the four added files. After future activation, rollback must select a previously reviewed controller/bootstrap SHA rather than code or policy from target H.

Explicit exclusions

This PR does not implement a GitHub App, OIDC verification, signer service, Commit Status publication, required-check activation, branch/ruleset changes, or a production pull_request_target workflow.

@stacknil
stacknil marked this pull request as ready for review September 16, 2026 04:49
@stacknil
stacknil merged commit ddaba6f into main Sep 16, 2026
6 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant