Skip to content

Report blocked OCI auth lookup kinds and reasons - #1361

Merged
Christof Marti (chrmarti) merged 4 commits into
mainfrom
chrmarti/oci-auth-diagnostic-details
Nov 20, 2026
Merged

Christof Marti (chrmarti) merged 4 commits into
mainfrom
chrmarti/oci-auth-diagnostic-details

Conversation

@chrmarti

@chrmarti Christof Marti (chrmarti) commented Nov 20, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Adds detail to the OCI auth hardening shadow diagnostics, so consumers can measure the compatibility impact of turning on --oci-auth-hardening by default:

  • authLookupBlockedKinds: the lookups that hit a token realm hardening would block: image, feature or template.
  • authLookupBlockedReasons: why that realm would be blocked: httpRealm, differentPort, parentDomain or differentHost.
  • devcontainer up now also includes ociAuthDiagnostics in its error result, not only on success.

Also prepares 0.91.0: version bump and changelog, including #1304.

Also includes the CI fix from #1362 (Linux test jobs on Ubuntu 24.04) so this PR's checks can pass. That commit becomes a no-op once #1362 merges.

Session Context

Key decisions from the development session:

  • Categories, not hosts: The diagnostics report categories instead of registry or realm hosts, so consumers can forward them as telemetry without exposing private registry names.
  • Lookup kind matters: When an image's registry lookup fails, the CLI falls back to docker pull, so the image still works. Feature and Template lookups fail outright. The impact of hardening therefore depends on the kind.
  • Reasons map to possible relaxations: Checked in order httpRealm, differentPort, parentDomain, differentHost.
    • differentPort: same hostname, different port (for example, a self-hosted GitLab registry on port 5050 with its token endpoint on 443).
    • parentDomain: for example, registry registry.gitlab.example with token endpoint gitlab.example.
    • Those two are candidates for allowing by default. httpRealm won't be allowed, and differentHost needs an explicit --allow-cross-origin-auth-host mapping.
  • parentDomain is a heuristic: It's a suffix match on a dot boundary without a public suffix list. It's only used for diagnostics, never for a trust decision.
  • Required ociAuthLookupKind: It's a required field on CommonParams (and 'feature' on ContainerFeatureInternalParams), so the compiler flags any new place that builds these parameters without saying what it looks up.
  • Failed up runs: doProvision creates the diagnostics object and passes it in through ProvisionOptions, so the error result can include it. For example, a Feature that fails to download still reports why.
  • No behavior change: Authentication behavior is unchanged, with or without --oci-auth-hardening.

Changes

  • OCIAuthDiagnostics gets authLookupBlockedKinds and authLookupBlockedReasons: sorted, unique lists.
  • requestEnsureAuthenticated records the kind and reason, and logs once per new kind or reason.
  • Image, Feature and Template lookups set ociAuthLookupKind where their parameters are built.
  • Failed up results include ociAuthDiagnostics.
  • Tests: reason classification, accumulation of kinds and reasons, updated diagnostics assertions, and the up error result.

Validation

  • src/test/httpOCIRegistry.test.ts: 54 passing.
  • End to end: up with a Feature from a local registry, which challenges with a token realm on a different port, fails and returns "authLookupBlockedKinds":["feature"],"authLookupBlockedReasons":["differentPort"] in its error result.

Record whether a token realm that OCI auth hardening would block was hit
by an image, Feature or Template lookup, and why it would be blocked
(httpRealm, differentPort, parentDomain or differentHost). Include the
diagnostics in failed `up` results too.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The test helper’s broad return type causes existing generateFeaturesConfig calls to fail TypeScript checking and must be narrowed to preserve the 'feature' literal.

1 open issue
What changed in this PR

This PR expands OCI authentication diagnostics to help consumers assess the compatibility impact of enabling auth hardening by default, without changing authentication behavior. It also prepares release 0.91.0.

Changes:

  • Record sorted, unique lookup kinds and blocking reasons across Image, Feature, and Template requests.
  • Include OCI authentication diagnostics in failed devcontainer up results.
  • Extend diagnostic tests and update release metadata, including the --docker-arg changelog entry from #1304.
File Description
src/​test/​testUtils.ts Set the default test lookup kind to Feature.
src/​test/​httpOCIRegistry.test.ts Test reason classification and diagnostic accumulation.
src/​test/​cli.up.test.ts Assert diagnostics appear in failed up results.
src/​spec-node/​utils.ts Mark image registry lookups.
src/​spec-node/​upgradeCommand.ts Mark Feature upgrade lookups.
src/​spec-node/​templatesCLI/​publish.ts Mark Template publishing lookups.
src/​spec-node/​templatesCLI/​metadata.ts Mark Template metadata lookups.
src/​spec-node/​templatesCLI/​apply.ts Mark Template download lookups.
src/​spec-node/​featureUtils.ts Mark Feature configuration lookups.
src/​spec-node/​featuresCLI/​resolveDependencies.ts Mark Feature dependency lookups.
src/​spec-node/​featuresCLI/​publish.ts Mark Feature publishing lookups.
src/​spec-node/​featuresCLI/​info.ts Mark Feature information lookups.
src/​spec-node/​devContainersSpecCLI.ts Preserve diagnostics on provisioning errors and classify outdated checks.
src/​spec-node/​devContainers.ts Accept and reuse provisioning diagnostics.
src/​spec-node/​containerFeatures.ts Mark Feature lookups during image extension.
src/​spec-configuration/​httpOCIRegistry.ts Classify blocked realms and accumulate diagnostic categories.
src/​spec-configuration/​containerFeaturesConfiguration.ts Require the Feature lookup kind.
src/​spec-configuration/​containerCollectionsOCI.ts Require a lookup kind in shared OCI parameters.
src/​spec-common/​ociAuth.ts Define and initialize diagnostic kinds and reasons.
package.json Bump the version to 0.91.0.
CHANGELOG.md Document diagnostics and global Docker argument support.

Review effort: Balanced

Comment thread src/test/testUtils.ts Resolved
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
ubuntu-latest moved to Ubuntu 26.04, where Compose 5.1 builds need Bake
filesystem entitlements (#1320), the Docker-in-Docker Feature's daemon does
not start, Podman builds cannot write to /tmp and Docker 29.0.0 has no
package.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@chrmarti
Christof Marti (chrmarti) marked this pull request as ready for review November 20, 2026 14:51
@chrmarti
Christof Marti (chrmarti) requested a review from a team as a code owner November 20, 2026 14:51
@chrmarti
Christof Marti (chrmarti) merged commit 0d38c68 into main Nov 20, 2026
51 checks passed
@chrmarti
Christof Marti (chrmarti) deleted the chrmarti/oci-auth-diagnostic-details branch November 20, 2026 18:26
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.

3 participants