Harden OCI registry authentication

[Christof Marti (chrmarti)]

Summary

Harden OCI Feature and Template authentication against registry-controlled Bearer realms that could trigger SSRF or forward registry credentials to an attacker-selected endpoint.

This builds on the work in #1276 while narrowing the change to the authentication boundary and adding a registry-scoped compatibility escape hatch for legitimate external token services.

Session Context

Key decisions from the development session:

• Keep registry parsing unchanged: Localhost, private-IP, single-label, IPv6, and custom-port registries are legitimate. The vulnerability is addressed at the secondary token-request boundary instead of adding a broad registry URL policy.
• Opt-in hardening: Legacy OCI authentication behavior remains the default. --oci-auth-hardening enables realm restrictions, the requested-registry credential-origin gate, and token redirect refusal.
• Bind compatibility exceptions to both hosts: --allow-cross-origin-auth-host <registry-host>=<auth-host> is repeatable. A bare auth-host allowlist would let any workspace-selected registry invoke that host as a confused deputy.
• Keep built-ins minimal: Docker Hub and GitLab.com are the verified public cross-origin flows. GHCR, Quay, GCR, public ECR, and normal ACR flows are same-origin and use the default policy.
• Trust the full mapped exchange: Exact trusted mappings may receive anonymous token requests, Basic credentials, and refresh/identity tokens. The exact HTTPS authority pair is the trust boundary.
• Fail closed on redirects when enabled: With --oci-auth-hardening, token requests do not follow redirects. Normal registry requests retain existing redirect behavior, and the final response URL is used to validate the challenge origin.
• Preserve localhost compatibility: Exact-authority http://localhost token realms remain supported for local Feature development; remote HTTP realms remain rejected.

Changes

• Add --oci-auth-hardening as the explicit opt-in for behavior-changing authentication protections.
• When enabled, validate bearer realms before credential lookup or token endpoint I/O.
• Permit exact-authority HTTPS realms and exact-authority localhost HTTP realms.
• Add built-in Docker Hub and GitLab.com registry-to-auth-host mappings.
• Add repeatable --allow-cross-origin-auth-host <registry-host>=<auth-host> mappings for enterprise registries.
• Forward registry credentials, including refresh/identity tokens, across explicitly trusted origin mappings.
• When enabled, disable redirects for token acquisition and handle redirect refusal as an authentication failure.
• Encode service and scope with URL.searchParams.
• Rebuild anonymous fallback requests without credential headers or refresh-token bodies.
• Add focused authentication policy and HTTP behavior tests.

Validation

• 41 focused OCI authentication tests pass.
• yarn type-check
• yarn lint
• yarn package
• Packaged CLI help exposes the new global option.

Fixes github/codespaces#24328.

[Copilot]

Pull request overview

Hardens OCI registry Bearer-token authentication by validating registry-provided realm URLs, constraining cross-origin auth host usage, disabling token-request redirects, and ensuring service/scope are encoded to prevent SSRF and credential forwarding.

Changes:

• Add realm admission + credential-forwarding policy with built-in and user-configured registry→auth-host mappings.
• Disable redirects for token endpoint requests and rebuild anonymous fallback requests to avoid replaying credentials.
• Add focused tests for realm policy, redirect refusal, and query encoding; wire the new test into CI.

Show a summary per file

File	Description
src/spec-configuration/httpOCIRegistry.ts	Implements realm validation, cross-origin auth-host policy, credential-forwarding rules, redirect suppression for token requests, and safe URL parameter encoding.
src/spec-utils/httpRequest.ts	Adds a no-redirect request helper and returns responseUrl to support validating challenges against the final registry response URL.
src/spec-node/devContainersSpecCLI.ts	Introduces the repeatable --allow-cross-origin-auth-host <registry>=<auth> global option and propagates configuration via env.
src/test/httpOCIRegistry.test.ts	Adds unit/integration-style tests for realm admission, credential forwarding, redirect refusal, and query encoding behavior.
.github/workflows/dev-containers.yml	Adds the new test to the CI matrix and excludes it from the “run all except above” batch to avoid duplicate execution.

Review details

Tip

Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Suppressed comments (1)

src/spec-utils/httpRequest.ts:121

• requestResolveHeadersInternal treats any URL with hostname 'localhost' as plain HTTP, even when the URL scheme is https:. That silently downgrades https://localhost to an http request, which can break requests and can undermine scheme-based security decisions (including for token realms). Consider basing the transport strictly on the parsed protocol (and, if needed, handle localhost TLS separately).

		const plainHTTP = parsed.protocol === 'http:' || parsed.hostname === 'localhost';
		if (plainHTTP) {
			output.write('Sending as plain HTTP request', LogLevel.Warning);
		}

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Lite

[Christof Marti (chrmarti)]

Companion VS Code Dev Containers integration: microsoft/vscode-remote-containers#1235

[Christof Marti (chrmarti)]

Follow-up 7b8e496 removes the internal environment-variable bridge. The option now propagates explicitly as typed command/resolver/request state across OCI paths. It also sets yargs nargs: 1 so repeated global mappings cannot consume the command positional, with packaged CLI and request-path regression coverage.

[Christof Marti (chrmarti)]

Updated trusted host-pair semantics in 87adb63: an exact HTTPS registry-to-auth-host mapping now authorizes both Basic and refresh/identity-token exchange. Added a real cross-authority Docker identitytoken POST regression test; all 41 focused tests, type-check, and lint pass.

[Copilot]

Review details

Suppressed comments (1)

src/spec-node/devContainersSpecCLI.ts:74

• This global escape hatch is not propagated by the features test command. That handler drops the parsed value before FeaturesTestCommandInput reaches generateDockerParams, even though test scenarios launch dev containers and can resolve OCI Feature dependencies or inspect a custom base image. As a result, the option is accepted but has no effect for that OCI-consuming command. Thread it through featuresCLI/test.ts and testCommandImpl.ts into createDockerParams.

			global: true,

• Files reviewed: 20/20 changed files
• Comments generated: 1
• Review effort level: Balanced

[Christof Marti (chrmarti)]

Updated in 7c650d5: behavior-changing OCI authentication protections are now opt-in through --oci-auth-hardening. Legacy cross-origin realm and redirect behavior remains the default; focused tests cover both modes.

[Christof Marti (chrmarti)]

Updated in 3ba63a5: add shadow diagnostics for auth lookups that hardening would block, registry redirects that would prevent forwarding requested-registry credentials, and auth-server redirects. Diagnostics are logged and surfaced in CLI results.

[Christof Marti (chrmarti)]

Prepared version 0.89.0 and added the August 2026 changelog entry in 422a92e.

[Christof Marti (chrmarti)]

Refined the registry redirect diagnostic in 987bbc7 so cross-origin content/blob redirects are ignored; it now reports only redirected 401/403 challenges that would change credential forwarding.