[rumpl]

What

com.docker.sandbox/docker-auth@1: registry authentication through opaque, run-scoped placeholders. Real login credentials and issued tokens remain outside the sandbox while Docker-compatible clients keep working unchanged.

Config is only a list of registries:

capabilities:
  - type: com.docker.sandbox/docker-auth@1
    config:
      registries: [docker.io, ghcr.io]

The contract is implementation-neutral and outcome-oriented: credential discovery, storage, token acquisition and renewal strategies are runtime choices. Authentication services are learned from verified registry challenges, not configured endpoints.

Spec layer

• Contract doc with per-requirement TCK anchors, JSON schema, strict Go validation (DNS grammar, Docker Hub alias dedup), whole-entry arity, composition/surface rules
• Spec package tests: validation, composition, surface, expansion, schema/validator agreement

TCK

Eight runtime checks share one guest probe and one suite-owned TLS service (registry, token issuer, CDN):

• host-resolution — admitted binding works; required+missing refuses; optional+missing skips and records
• request-scope — the real login appears only on the admitted HTTPS token exchange
• host-only — clients resolve usable placeholders, never the real login
• token-mediation — client-visible token fields are placeholders; failed exchanges fail closed
• bearer-scope — substitution confined to the admitted HTTPS registry API; unknown placeholders rejected
• redirect-confinement — signed download URLs stay host-side; client-visible locations remain usable
• lifetime — authentication available in install/startup hooks; run-local placeholders withdrawn when the run ends
• no-extra-access — no egress, socket or engine from the grant alone

Confinement is judged by exact-value comparison at the client interface and in the services' independent request traces — never by scanning probe output — so no output encoding can hide a leak. Every check has a mutation in the conforming fake, each verified to fail for its intended reason. config-valid is covered by descriptor-valid; source-private is waived following the git-identity@1/source-private precedent.

The adapter contract gains create --docker-auth-config <absolute-path>, a suite-owned transport for synthetic bindings, routes for the three logical test hosts, and the suite CA.

Validation

gofmt, vet, unit tests (both modules), race, markdownlint, anchor/waiver accounting, fixture validation, conforming-fake baseline and all mutations pass.

[Copilot]

🟡 Changes recommended

The sandbox authentication tests can reject conforming runtimes, misattribute setup traffic, and miss bearer-confinement and redirect network-policy violations.

5 open issues

• Accept transport refusal for fail-closed token exchange · New
• Test bearer confinement beyond the registry API · New
• Test CDN denial during redirect resolution · New
• Accept direct content or opaque redirect from signed URL · New
• Clear setup-sandbox trace before asserting no egress · New

What changed in this PR

Adds com.docker.sandbox/docker-auth@1 to the specification and conformance suite, defining registry authentication through run-scoped placeholders while keeping real credentials outside the sandbox.

Changes:

• Defines the capability contract, strict validation, JSON schema, and composition rules.
• Adds eight runtime conformance checks, synthetic HTTPS services, guest probes, and fake-adapter mutations.
• Extends adapter configuration and provides an example Kit and authoring guidance.

File	Description
tck/​sandbox/​testdata/​fixtures/​workload/​workload.dockerfile	Installs the authentication probe.
tck/​sandbox/​testdata/​fixtures/​workload/​kit-tck-docker-auth.py	Observes client credentials and HTTP exchanges.
tck/​sandbox/​testdata/​fixtures/​docker-auth/​docker-auth.yaml	Requests required registry authentication.
tck/​sandbox/​testdata/​fixtures/​docker-auth-optional/​docker-auth-optional.yaml	Requests optional registry authentication.
tck/​sandbox/​testdata/​fixtures/​docker-auth-network/​docker-auth-network.yaml	Grants network access to test services.
tck/​sandbox/​testdata/​fixtures/​docker-auth-hooks/​docker-auth-hooks.yaml	Exercises authentication during lifecycle hooks.
tck/​sandbox/​testdata/​fixtures/​docker-auth-absent/​docker-auth-absent.yaml	Provides a network-only baseline.
tck/​sandbox/​testdata/​fake-adapter	Dispatches authentication fixtures to the fake runtime.
tck/​sandbox/​testdata/​docker-auth-fake.py	Models credential mediation and failure mutations.
tck/​sandbox/​sandbox_test.go	Registers authentication mutations.
tck/​sandbox/​fixtures_test.go	Updates the expected fixture count.
tck/​sandbox/​docker_auth.go	Implements synthetic services and runtime checks.
tck/​sandbox/​coverage_test.go	Records requirement coverage and the privacy waiver.
tck/​sandbox/​checks.go	Adds authentication to capability-refusal checks.
tck/​adapter/​adapter.go	Transports suite-owned authentication configuration.
tck/​adapter/​adapter_test.go	Verifies literal configuration-path transport.
Taskfile.yaml	Includes the example in Kit builds.
spec/​validate.go	Integrates authentication validation.
spec/​types.go	Defines the capability identifier.
spec/​schema_test.go	Includes the capability in schema checks.
spec/​instance_key.go	Assigns whole-entry arity.
spec/​instance_key_test.go	Tests the capability’s arity.
spec/​groups.go	Registers the known capability.
spec/​docker_auth.go	Defines configuration and registry validation.
spec/​docker_auth_test.go	Tests validation, composition, expansion, and schema agreement.
spec/​capabilities.go	Registers the typed configuration.
spec/​capabilities_test.go	Tests strict parameterized configuration decoding.
skills/​create-kit-v3/​SKILL.md	Adds authentication authoring guidance.
schema/​kit.schema.json	Connects the capability to its configuration schema.
schema/​capabilities/​com.docker.sandbox/​docker-auth@1.schema.json	Defines registry-list constraints.
examples/​docker-auth/​docker-auth.yaml	Demonstrates authentication with separate network grants.
docs/​spec/​SPEC-v3.md	Lists the capability and its arity.
docs/​spec/​conformance.md	Documents adapter bindings, routing, and probe requirements.
docs/​spec/​capabilities/​com.docker.sandbox/​docker-auth@1.md	Defines credential confinement and runtime obligations.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The conformance checks can pass despite credential leaks, out-of-scope credential substitution, or expired authorization reuse because their observations and probes do not adequately exercise those cases.

3 open issues

• Expired bearer authorization is never tested · New
• Token observation ignores leaked response fields and headers · New
• Off-scope URL probes omit the required challenge state · New

5 resolved since last review

• Clear setup-sandbox trace before asserting no egress
• Accept direct content or opaque redirect from signed URL
• Test CDN denial during redirect resolution
• Test bearer confinement beyond the registry API
• Accept transport refusal for fail-closed token exchange

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Missing HTTP-status validation, fragile scenario selection, and concurrent token-allocation races undermine conformance results, while upload-state credential leaks remain untested.

4 open issues

• Test credential confinement for upload state and redirects · New
• Allocate token values and expiries atomically · New
• Avoid relying on guest-added query parameters for token scenarios · New
• Require successful HTTP status in positive token probes · New

3 resolved since last review

• Off-scope URL probes omit the required challenge state
• Token observation ignores leaked response fields and headers
• Expired bearer authorization is never tested

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Critical gaps in hook-observation and cross-field confidentiality checks allow runtimes that expose real credentials to pass the suite.

6 open issues

• Compare returned credentials against all protected values · New
• Check hook observations for credential and token disclosure · New
• Separate stale-token rejection from expiry authorization checks · New
• Reject authenticated content after optional credentials are skipped · New
• Use fresh contexts and persistent issuer failures in expiry probes · New
• Reject real-credential use in the no-grant baseline · New

4 resolved since last review

• Require successful HTTP status in positive token probes
• Avoid relying on guest-added query parameters for token scenarios
• Allocate token values and expiries atomically
• Test credential confinement for upload state and redirects

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Active issues leave structured error responses insufficiently checked for credential leaks and can reject valid runtime behavior due to token-freshness timing and eager authorization failures.

3 open issues

• Accept eager authorization refusal in the issuer-error scenario · New
• Use recursive leak detection for structured error responses · New
• Check token freshness when the registry authorizes the request · New

6 resolved since last review

• Check hook observations for credential and token disclosure
• Compare returned credentials against all protected values
• Reject real-credential use in the no-grant baseline
• Use fresh contexts and persistent issuer failures in expiry probes
• Reject authenticated content after optional credentials are skipped
• Separate stale-token rejection from expiry authorization checks

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Critical authentication-trace gaps can hide create-time credential leakage and let post-expiry replays pass without token renewal.

3 open issues

• Preserve credential traces during optional sandbox creation · New
• Tie authorization evidence to the post-expiry replay · New
• Match the denied HTTP method in the assertion · New

3 resolved since last review

• Check token freshness when the registry authorizes the request
• Use recursive leak detection for structured error responses
• Accept eager authorization refusal in the issuer-error scenario

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The probes reject valid host-mediated authentication and can falsely pass expired-token replays or network-policy bypasses during credential substitution.

2 open issues

• Accept host-mediated registry success without a challenge · New
• Test authenticated requests when egress is denied · New

3 resolved since last review

• Tie authorization evidence to the post-expiry replay
• Preserve credential traces during optional sandbox creation
• Match the denied HTTP method in the assertion

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The token endpoint lacks a JSON Content-Type, risking rejection by compliant runtimes, and the positive probes can incorrectly accept truncated HTTP responses.

2 open issues

• Set the token response Content-Type to application/json · New
• Reject truncated responses when EOF precedes Content-Length · New

3 resolved since last review

• Decode Docker auth entries when checking protected credentials
• Grant registry network access to isolate the missing-binding control
• Handle truncated HTTP response bodies without aborting probes

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The fixture fails valid Docker identity-token credentials, and the normative specification omits the Docker Hub alias equivalence and duplicate restriction enforced by validation.

2 open issues

• Support Docker identity-token credentials and exchange flows · New
• Document Docker Hub aliases and duplicate restriction · New

2 resolved since last review

• Reject truncated responses when EOF precedes Content-Length
• Set the token response Content-Type to application/json

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

A critical credential-detection gap lets POST-body identity tokens leak off-scope without failing request-scope or withdrawn-credential checks, which inspect only Authorization headers.

1 open issue

• Request-scope checks miss credentials sent in POST bodies · New

2 resolved since last review

• Support Docker identity-token credentials and exchange flows
• Document Docker Hub aliases and duplicate restriction

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The suite lacks an unrequested-registry binding and an overbroad-binding mutation, leaving a critical gap in detecting unauthorized credential access in host-resolution and host-only modes.

1 open issue

• Test that docker-auth grants reject unrequested registry bindings · New

1 resolved since last review

• Request-scope checks miss credentials sent in POST bodies

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The credential-reuse assertions can mistake permitted background authentication for placeholder substitution, causing nondeterministic conformance failures unless negative-probe traffic is distinguished from background activity.

1 open issue

• Exclude background authentication when checking credential reuse · New

1 resolved since last review

• Test that docker-auth grants reject unrequested registry bindings

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Critical gaps in response-header checks allow credential-bearing URLs and Basic/Bearer credentials to leak while confinement and confidentiality checks still pass.

2 open issues

• Confidentiality checks miss credentials in Basic and Bearer headers · New
• Redirect probe ignores credential leaks in Content-Location · New

1 resolved since last review

• Exclude background authentication when checking credential reuse

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The new credential-interception security boundary needs security-owner review and real-runtime validation of credential confinement and run-scoped withdrawal, which the fake-adapter tests cannot establish.

No open issues 🎉

2 resolved since last review

• Redirect probe ignores credential leaks in Content-Location
• Confidentiality checks miss credentials in Basic and Bearer headers

_{Review effort: Balanced}