feat(oci): support OCI auth hardening from reference v0.89.0

Bump the pinned reference CLI to v0.89.0 and implement the observable
surface it added (PR devcontainers/cli#1278):

- `--oci-auth-hardening` and `--allow-cross-origin-auth-host` as global
  flags, with the same validation the oracle applies: the allow list
  requires hardening, and each entry is a '<registry-host>=<auth-host>'
  pair of bare authorities.
- `ociAuthDiagnostics` in the `up`, `build` and `read-configuration`
  output, reporting what hardening would change.
- Bearer realms pinned to the registry authority or a trusted auth host
  (including the built-in Docker Hub and GitLab mappings), and token
  endpoints refused a redirect, when hardening is on.
- `scheme` on the feature ref in `read-configuration` output, and the
  generated feature Dockerfiles defaulting the base-image ARG to
  `scratch` rather than `placeholder`.

The policy is built once per invocation and carried on the command
context, so every OCI client of a command shares its settings and feeds
the same diagnostics. `exec` parses its own flags and therefore applies
the validation itself; `features test` re-invokes this binary and
forwards the flags to the `up` it spawns.

The hardening is enforced in a transport above oras-go, which already
refuses to forward credentials to a cross-origin challenge. That makes
hardening-off stricter here than upstream; the divergence is documented
and the diagnostics still report what hardening would change.

TestOracleFlagCoverage only inspected per-command options, so the two
new global flags went unnoticed; it now checks the oracle's global
options as well, and TestFlagInventoryParity pins them to the root
command.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: aledbf

.github/workflows/go-cli.yml

@@ -109,7 +109,7 @@ jobs:
       - uses: actions/upload-artifact@v7
         if: always()
         with:
-          name: parity-contract-network-v0.88.0
+          name: parity-contract-network-v0.89.0
           path: artifacts/
           if-no-files-found: error
       - uses: actions/upload-artifact@v7
@@ -222,7 +222,7 @@ jobs:
       - uses: actions/upload-artifact@v7
         if: always() && steps.plan.outputs.run == 'true'
         with:
-          name: parity-runtime-v0.88.0-shard-${{ matrix.shard }}
+          name: parity-runtime-v0.89.0-shard-${{ matrix.shard }}
           path: artifacts/
           if-no-files-found: error
       # daily only: covdata slice for the cross-lane merge (distinct name per shard).

README.md

@@ -121,7 +121,7 @@ GitHub Releases are not supported targets. “Compatible” means compatibility
 this scope; it does not mean that every platform or historical upstream behavior is
 implemented.
 
-A pinned official TypeScript CLI (`reference/`, currently v0.88.0) is the behavioral
+A pinned official TypeScript CLI (`reference/`, currently v0.89.0) is the behavioral
 oracle. Roughly 200 cases run commands through both CLIs and compare exit status,
 normalized output, and relevant container or registry state. See the
 [parity matrix](docs/parity/parity-matrix.yaml) and

docs/DIVERGENCES.md

@@ -1,7 +1,7 @@
 # Divergences, decisions & accepted limitations
 
 This CLI is validated for behavioral parity with the reference TypeScript
-`@devcontainers/cli` (pinned at **v0.88.0**, see [`parity/`](parity/)). Where it
+`@devcontainers/cli` (pinned at **v0.89.0**, see [`parity/`](parity/)). Where it
 deliberately differs, the difference is recorded here — this is the durable record of
 *intentional* departures from the oracle, not a backlog. User-facing additions are
 documented in [`go-only-features.md`](go-only-features.md).
@@ -32,6 +32,16 @@ touches a compared surface, reflected in the parity matrix.
 - **`config.build.cacheFrom`** is honored (wired to `--cache-from` after the flag's
   values) — matching `singleContainer.ts`. Upstream defines the field; this is a parity
   fix, noted here because it was previously a dead field.
+- **OCI auth hardening is enforced through `oras-go`, which is stricter by default.**
+  `--oci-auth-hardening` and `--allow-cross-origin-auth-host` behave as documented
+  upstream (bearer realms pinned to the registry authority or a trusted auth host,
+  token endpoints may not redirect), and `ociAuthDiagnostics` reports the same three
+  flags in `up`/`build`/`read-configuration`. The difference is what happens
+  **without** the flag: the reference CLI still forwards registry credentials to a
+  challenge that arrives from another origin, while `oras-go` never does
+  (GHSA-vh4v-2xq2-g5cg). Hardening off is therefore already safe here; the
+  diagnostics still report what hardening *would* change, so the flag remains a
+  faithful compatibility probe.
 - **`BUILDKIT_INLINE_CACHE=1`** is omitted when `--cache-to` is an inline exporter
   (`/type\s*=\s*inline/i`), matching TS `isBuildxCacheToInline` — a parity fix over the
   earlier unconditional build-arg.

docs/parity/cli-flags-inventory.yaml

@@ -21,6 +21,20 @@ parser_configuration:
   strict: true
   demand_command: true
 
+# ─────────────────────────────────────────────────────────────────────────────
+# Global flags (yargs `.option(..., { global: true })`: accepted by every command)
+# ─────────────────────────────────────────────────────────────────────────────
+global_flags:
+  oci-auth-hardening:
+    type: boolean
+    default: false
+    description: "Restrict OCI bearer authentication realms, registry credential forwarding, and token redirects."
+  allow-cross-origin-auth-host:
+    type: string
+    array: true
+    description: "Allow an OCI registry to use a cross-origin HTTPS authentication host. Format: <registry-host>=<auth-host>. May be repeated."
+    notes: "Requires --oci-auth-hardening; each entry must be '<registry-host>=<auth-host>' of bare authorities."
+
 # ─────────────────────────────────────────────────────────────────────────────
 # Global validations (shared by multiple commands)
 # ─────────────────────────────────────────────────────────────────────────────
@@ -1140,17 +1154,17 @@ commands:
 # =============================================================================
 json_output_envelopes:
   success_with_container:  # up
-    fields: [outcome, containerId, remoteUser, remoteWorkspaceFolder, composeProjectName, configuration, mergedConfiguration]
+    fields: [outcome, containerId, remoteUser, remoteWorkspaceFolder, composeProjectName, configuration, mergedConfiguration, ociAuthDiagnostics]
   success_setup:  # set-up
     fields: [outcome, configuration, mergedConfiguration]
   success_build:  # build
-    fields: [outcome, imageName]
+    fields: [outcome, imageName, ociAuthDiagnostics]
   success_run_user_commands:  # run-user-commands
     fields: [outcome, result]
   error:  # all commands with outcome envelope
     fields: [outcome, message, description, containerId, disallowedFeatureId, didStopContainer, learnMoreUrl]
   read_configuration:  # read-configuration (NO outcome envelope)
-    fields: [configuration, workspace, featuresConfiguration, mergedConfiguration]
+    fields: [configuration, workspace, featuresConfiguration, mergedConfiguration, ociAuthDiagnostics]
 
 # =============================================================================
 # ENVIRONMENT VARIABLES READ

docs/parity/parity-matrix.yaml

@@ -9,6 +9,7 @@ meta:
   scope:
     languages: [ts, go]
     commands: [features-info, read-configuration, exec, run-user-commands, set-up, up, build]
+    global_flags: [oci-auth-hardening, allow-cross-origin-auth-host]
   lanes:
     contract:
       description: "Parsing, required args, enums, error formats, output shape"
@@ -491,6 +492,61 @@ initial_cases:
     class: format-validation
     current_status: match
 
+  - id: read-configuration.oci-auth-hardening-accepted
+    lane: contract
+    command: read-configuration
+    priority: p0
+    docker_required: false
+    ts_cmd: "--oci-auth-hardening read-configuration --workspace-folder src/test/configs/image"
+    asserts: [exit_code, stdout_normalized]
+    class: global-flags
+    current_status: match
+    notes: "0.89 global flag: accepted before the command name and the output carries the ociAuthDiagnostics envelope field (all false when no registry is contacted)."
+
+  - id: read-configuration.cross-origin-auth-host-requires-hardening
+    lane: contract
+    command: read-configuration
+    priority: p0
+    docker_required: false
+    ts_cmd: "--allow-cross-origin-auth-host registry.example=auth.example read-configuration --workspace-folder src/test/configs/image"
+    asserts: [exit_code, stderr_normalized]
+    class: global-flags
+    current_status: match
+    notes: "0.89 yargs .check(): --allow-cross-origin-auth-host requires --oci-auth-hardening."
+
+  - id: read-configuration.cross-origin-auth-host-invalid-pair
+    lane: contract
+    command: read-configuration
+    priority: p1
+    docker_required: false
+    ts_cmd: "--oci-auth-hardening --allow-cross-origin-auth-host bad read-configuration --workspace-folder src/test/configs/image"
+    asserts: [exit_code, stderr_normalized]
+    class: global-flags
+    current_status: match
+    notes: "0.89: each entry must be '<registry-host>=<auth-host>'."
+
+  - id: read-configuration.cross-origin-auth-host-invalid-authority
+    lane: contract
+    command: read-configuration
+    priority: p1
+    docker_required: false
+    ts_cmd: "--oci-auth-hardening --allow-cross-origin-auth-host a/b=c read-configuration --workspace-folder src/test/configs/image"
+    asserts: [exit_code, stderr_normalized]
+    class: global-flags
+    current_status: match
+    notes: "0.89: both sides of the mapping must be bare authorities."
+
+  - id: read-configuration.global-options-consume-one-argument
+    lane: contract
+    command: read-configuration
+    priority: p1
+    docker_required: false
+    ts_cmd: "--oci-auth-hardening --allow-cross-origin-auth-host registry.example=auth.example read-configuration --workspace-folder src/test/configs/image"
+    asserts: [exit_code, stdout_normalized]
+    class: global-flags
+    current_status: match
+    notes: "Mirrors the oracle's own 'Global options consume exactly one argument' test (src/test/cli.test.ts), asserted on read-configuration because yargs and cobra render --help differently: the repeatable flag must consume exactly one value and leave the subcommand intact."
+
   - id: read-configuration.terminal-columns-implies-rows
     lane: contract
     command: read-configuration

internal/cli/build.go

@@ -163,6 +163,8 @@ func runBuild(ctx context.Context, out Output, opts *buildOpts) error {
 		Format:  opts.logFormat,
 		Writer:  os.Stderr,
 	})
+	// Route the OCI auth diagnostic lines at this command's logger.
+	ociAuthPolicy(ctx).SetLogger(logger)
 
 	// Load config
 	loadResult, err := config.LoadDevContainerConfig(workspaceFolder, configPath, "")
@@ -243,8 +245,9 @@ func runBuild(ctx context.Context, out Output, opts *buildOpts) error {
 	}
 
 	return writeSuccessJSON(out, map[string]interface{}{
-		"outcome":   "success",
-		"imageName": imageNameResult,
+		"outcome":            "success",
+		"imageName":          imageNameResult,
+		"ociAuthDiagnostics": ociAuthDiagnostics(ctx),
 	})
 }
 

internal/cli/collection_commands.go

@@ -238,6 +238,7 @@ func realFeaturesTestCmd() *cobra.Command {
 				preserve,
 				quiet,
 				permitRandomization,
+				ociAuthGlobalArgs(cmd),
 			)
 			if exitCode != 0 {
 				return &coreerrors.ExitCodeError{Code: exitCode}
@@ -438,7 +439,7 @@ func publishCollection(ctx context.Context, targetFolder, registry, namespace, c
 		Format: "text",
 		Writer: os.Stderr,
 	})
-	reg := oci.NewClient(logger, osEnvMap())
+	reg := newOCIClient(ctx, logger)
 	return publishCollectionWith(ctx, OSOutput(), reg, targetFolder, registry, namespace, collectionType, logLevelStr)
 }
 

internal/cli/exec.go

@@ -62,6 +62,11 @@ func newExecCmd() *cobra.Command {
 			if err := cmd.ParseFlags(flagArgs); err != nil {
 				return err
 			}
+			// DisableFlagParsing skips the root's PersistentPreRunE validation, so
+			// the global OCI auth flags are validated here, once parsed.
+			if err := applyOCIAuthPolicy(cmd); err != nil {
+				return err
+			}
 
 			opts.workspaceFolder, _ = cmd.Flags().GetString("workspace-folder")
 			opts.configPath, _ = cmd.Flags().GetString("config")
@@ -433,6 +438,7 @@ func splitExecArgs(args []string) (flags []string, cmd []string) {
 		"--default-user-env-probe": true, "--user-data-folder": true,
 		"--terminal-columns": true, "--terminal-rows": true,
 		"--log-file": true, "--terminal-log-file": true,
+		"--" + flagAllowCrossOriginAuthHos: true,
 	}
 
 	i := 0

internal/cli/feature_install.go

@@ -79,8 +79,8 @@ type fetchFeatureResult struct {
 
 // fetchFeatureSets fetches features and returns them in install order. reg is the
 // registry seam; pass nil for the default OCI client.
-func fetchFeatureSets(logger log.Logger, reg oci.Registry, featuresCfg map[string]interface{}, featuresBasePath string, skipAutoMapping bool, lockfile *features.Lockfile) (*fetchFeatureResult, error) {
-	return fetchFeatureSetsWithOrder(logger, reg, featuresCfg, featuresBasePath, skipAutoMapping, lockfile, nil)
+func fetchFeatureSets(ctx context.Context, logger log.Logger, reg oci.Registry, featuresCfg map[string]interface{}, featuresBasePath string, skipAutoMapping bool, lockfile *features.Lockfile) (*fetchFeatureResult, error) {
+	return fetchFeatureSetsWithOrder(ctx, logger, reg, featuresCfg, featuresBasePath, skipAutoMapping, lockfile, nil)
 }
 
 // fetchFeatureSetsWithOrder resolves the feature dependency graph through the
@@ -89,7 +89,7 @@ func fetchFeatureSets(logger log.Logger, reg oci.Registry, featuresCfg map[strin
 // order. Each returned Set's content is staged under the returned TmpDir
 // at _dev_container_feature_<installOrderIndex>, matching the generated
 // Dockerfile's COPY paths.
-func fetchFeatureSetsWithOrder(logger log.Logger, reg oci.Registry, featuresCfg map[string]interface{}, featuresBasePath string, skipAutoMapping bool, lockfile *features.Lockfile, overrideOrder []string) (*fetchFeatureResult, error) {
+func fetchFeatureSetsWithOrder(ctx context.Context, logger log.Logger, reg oci.Registry, featuresCfg map[string]interface{}, featuresBasePath string, skipAutoMapping bool, lockfile *features.Lockfile, overrideOrder []string) (*fetchFeatureResult, error) {
 	if len(featuresCfg) == 0 {
 		return nil, nil
 	}
@@ -104,7 +104,7 @@ func fetchFeatureSetsWithOrder(logger log.Logger, reg oci.Registry, featuresCfg
 
 	ociClient := reg
 	if ociClient == nil {
-		ociClient = oci.NewClient(logger, osEnvMap())
+		ociClient = newOCIClient(ctx, logger)
 	}
 
 	tmpDir, err := os.MkdirTemp("", "devcontainer-features-")
@@ -396,6 +396,7 @@ func processInstallFeature(
 					"owner":    strings.SplitN(ref.Namespace, "/", 2)[0],
 					"path":     ref.Namespace + "/" + ref.ID,
 					"registry": ref.Registry,
+					"scheme":   ref.Scheme(),
 					"resource": ref.Resource,
 					"tag":      ref.Tag, "version": ref.Tag,
 				},
@@ -529,7 +530,7 @@ func extendImageWithFeatures(
 	if fbOpts != nil {
 		overrideOrder = fbOpts.OverrideFeatureInstallOrder
 	}
-	result, err := fetchFeatureSetsWithOrder(logger, nil, featuresCfg, featuresBasePath, skipAutoMap, lockfile, overrideOrder)
+	result, err := fetchFeatureSetsWithOrder(ctx, logger, nil, featuresCfg, featuresBasePath, skipAutoMap, lockfile, overrideOrder)
 	if err != nil {
 		return nil, err
 	}

internal/cli/feature_install_test.go

@@ -134,7 +134,7 @@ func TestFetchFeatureSets(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			baseDir := t.TempDir()
 			tt.setup(t, baseDir)
-			result, err := fetchFeatureSets(log.Null, nil, tt.entries, baseDir, false, nil)
+			result, err := fetchFeatureSets(t.Context(), log.Null, nil, tt.entries, baseDir, false, nil)
 			if result != nil && result.TmpDir != "" {
 				defer os.RemoveAll(result.TmpDir)
 			}