chore(isolation): host-materialized provider facts (split from #436, blocked on quickstart#504) #456

Activity

1. wz-gsa commented on Oct 1, 2026

   

   wz-gsa

   on Oct 1, 2026

   ContributorAuthor

   More actions

   Prior art worth weighing before this is built — Docker's Sandbox Kit Spec v3 (docker/sandbox-kit-spec, Apache-2.0, experimental, final targeted Q4 2026) solves the exact problem this issue exists for, and solves it differently from how this issue is currently specified.

   Why it is relevant here

   This issue inherits #436's framing: a facts file advertising keyEnv, the NAME of the env var holding the credential, materialized somewhere a consumer can trust. The trust problem was the location of the file.

   Docker's credential@1 capability makes the location question mostly disappear, because the credential never enters the guest at all:

   MUST NOT place the real secret in the container when proxyManaged or OAuth sentinels are in play: where the Kit names a variable or file, the container sees sentinel values there, and the boundary (proxy) substitutes the real credential on outbound requests matching the inject rules or resourceHosts.

   MUST resolve the credential from the host-side store keyed by service. Host environment variables never auto-inject; a Kit cannot name where a secret lives, only what it needs.

   A declaration looks like this:

   - type: com.docker.sandbox/credential@1
     config:
       service: github
       phase: runtime
       apiKey:
         name: GH_TOKEN
         proxyManaged: true
         inject:
           - {domain: api.github.com, header: Authorization, format: "Bearer %s"}

   The container gets GH_TOKEN set to a sentinel, deliberately non-empty "so Kit content can detect wiring without seeing the secret". An inject-only credential (no name) gets no environment presence at all.

   Two further properties we have no equivalent for:

   • Phase-scoped with revocation. "an install-only credential is injectable only while install hooks run and is revoked before the workload's entrypoint starts".
   • Cross-validated against the network policy. inject[].domain "MUST appear in the network policy's allow list for every declared phase" — because "an inject domain outside the allow list would be a credential mapped onto a connection that can never occur."

   What this would change about this issue

   If that model is adopted, keyEnv stops being a trust-sensitive field. Today an agent that rewrites the facts file redirects a consumer to a different env var and harvests whatever is there — which is why #436's version had to be removed. Under the sentinel model there is nothing in the guest to harvest, so the facts file's integrity matters much less and the host-side :ro materialization this issue is blocked on becomes a smaller requirement rather than the whole security control.

   I am not proposing we adopt it. Three honest reasons to be cautious:

   1. It requires a credential-substituting egress proxy. acq has no such component, and building one is far larger than this issue.
   2. The spec is explicitly experimental and still moving.
   3. It is OCI/BuildKit-coupled in ways acq's backend-neutral design (sbx and msb) is not.

   But it is the structurally correct answer to the problem, and this issue should at least record that keyEnv-in-the-guest is a weaker design that was chosen for buildability, not because it is the right shape.

   One correction to my own earlier framing

   I initially read this as "acq is on a deprecated kit line that should migrate to v3." That was wrong, and measuring it inverted the conclusion:

   $ sbx kit validate <kit with schemaVersion "3">
   error: manifest: unsupported schemaVersion "3" (supported: [1 2])
   

   v3 is not a schemaVersion bump — it is a different artifact format (an OCI image carrying declarations in a vnd.docker.sandbox.kit.descriptor manifest annotation). sbx v0.46.0 rejects "3" outright. So there is no migration available today and nothing here is urgent on that basis. The separate, real risk — that nothing checks whether the grammar acq does emit is still accepted — is filed as GSA-TTS/agentic-coding-quickstart#529.

   Smaller borrowable detail

   Docker's lifecycle@1 files[] entries carry no user: field at all, with the rationale: "A path only root can own is an install hook's job — what install[].user is for." That is a cleaner statement of the rule #436 violated, and it is enforced by the grammar's shape rather than by review.

   ---

   AI-assisted (OpenCode), on operator instruction. Research summary — treat the quoted spec text as the authority, not my paraphrase.
2. mogul

   added a parent issue on Oct 5, 2026

   • Epic: harness-neutral USAi model catalog + per-harness emitters #357
3. mogul

   linked a pull request that will close this issuefeat(acq): project provider inputs read-only #608on Oct 22, 2026
4. mogul

   closed this as completedin agentic-coding-quickstart#608on Oct 23, 2026