feat(driver-podman): add userns config

[giuseppe]

Summary

Add user namespace support to the Podman compute driver. The userns config option maps to Podman's namespace modes with parameterized value support (auto:size=65536, keep-id:uid=1000,gid=1000). When userns is configured, the driver extracts the supervisor binary to a host-side cache and bind-mounts it instead of using an OCI image volume, because the kernel does not support idmapped mounts on overlay.

The private mode supports explicit UID/GID mappings via uidmap and gidmap config arrays, giving operators full control over which container IDs map to which host IDs. This is needed when auto breaks host-owned bind-mounts (e.g. TLS files with mode 0600 become unreadable when container UID 0 maps to an unprivileged host UID).

A preparatory refactor commit extracts shared supervisor binary helpers (extraction, caching, ELF validation) from the Docker driver into openshell-core::driver_utils so both drivers reuse the same code with hardened integrity checks.

Related Issue

Fixes: #2554

Changes

Commit 1: refactor(driver): extract shared supervisor binary helpers into openshell-core

• Move extract_first_tar_entry, write_cache_binary_atomic, supervisor_cache_path,
  temp_extract_container_name, and validate_linux_elf_binary from Docker driver to
  openshell-core::driver_utils
• Add entry-type and empty-payload checks to extract_first_tar_entry
• Parameterize supervisor_cache_path by driver name (docker-supervisor vs podman-supervisor)

Commit 2: feat(driver-podman): add userns config with supervisor bind-mount fallback

• Add userns field to PodmanComputeConfig (TOML userns, CLI --userns, env
  OPENSHELL_PODMAN_USERNS)
• Split mode string on first : into Podman API nsmode + value fields
• Set idmappings.AutoUserNs = true when base mode is auto
• Validate mode at startup: auto/keep-id accept params, host/nomap reject them
• Extract supervisor binary to host cache and bind-mount when userns is active (all modes except host)
• Add copy_from_container API method to PodmanClient
• Update architecture docs, gateway config reference, and driver README

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

[mrunalp]

Potential Concerns

1. Resource leak on extraction failure — driver.rs:647-655
   Every other error path in this block calls cleanup_created() first. This one uses ?:
   let supervisor_bin_path = if self.config.userns.is_some() {
   Some(extract_supervisor_bin(&self.client, &self.config).await
   .map_err(ComputeDriverError::from)?,) // <- skips cleanup_created()
   } else { None };
   A failed extraction orphans the workspace volume and both per-sandbox secrets.

2. Introduces two clippy warnings → mise run lint fails. tasks/rust.toml:14 runs cargo clippy --workspace --all-targets -- -D warnings. Locally:

• clippy::too_many_arguments — build_container_spec_for_image is now 8/7 (container.rs:930)
• clippy::useless_conversion — the redundant .map_err(ComputeDriverError::from) at driver.rs:651

3. Duplicates the Docker driver's extraction code, minus its integrity check. openshell-driver-docker/src/lib.rs:3149-3415 already has extract_supervisor_bin_from_image, extract_supervisor_binary_bytes, extract_first_tar_entry, write_cache_binary_atomic, supervisor_cache_path, and a byte-identical temp_extract_container_name. The Docker version calls validate_linux_elf_binary both after write and on cache hit; the Podman copy trusts cache_path.is_file() blindly. Since this file becomes the sandbox's security-enforcement supervisor, a truncated, corrupt, or symlinked cache entry executes unchecked. These belong in openshell-core::driver_utils shared by both drivers.

4. userns values other than bare auto are likely broken. Podman's Namespace splits mode and value, so auto:size=65536 or keep-id:uid=1000 would be sent as an invalid nsmode and also skip AutoUserNs. userns = "host" silently disables userns isolation and ns:/path joins an arbitrary namespace — worth an allowlist plus a config-load error instead of an obscure Podman API failure at create time.

5. No tests for the new extraction path. The four added tests cover spec shape only. extract_first_tar_entry (which doesn't check entry type or non-empty payload — a symlinked /openshell-sandbox yields a 0-byte "binary"), supervisor_cache_path, and write_cache_binary_atomic are untested, though the Docker equivalents have tests at driver-docker/src/tests.rs:2199-2223 that could be lifted.

6. Stale architecture doc. architecture/compute-runtimes.md:173 still says Podman delivers the supervisor via "Read-only OCI image volume" — now conditional. Line 120 mentions image volumes too. AGENTS.md requires this in the same branch.

7. Process gaps. DCO check is failing — the contributor-assistant bot needs the sign-off comment on the PR, not just the trailer. The PR body is the unfilled template (no Summary, Related Issue, Testing, or checked boxes), and a feature needs a linked accepted issue per AGENTS.md. No pre-flight for --userns=auto, which needs a larger subuid range than the existing check_subuid_range warning covers.

Minor: extraction runs on the sandbox-create path rather than driver startup (first create per digest pays inspect + create + download + remove); the mid-file use openshell_core::driver_utils::SUPERVISOR_IMAGE_BINARY_PATH; at driver.rs:964 breaks the file's import convention; #[serde(rename = "AutoUserNs")] would be cleaner than #[allow(non_snake_case)].

[giuseppe]

I have read the DCO document and I hereby sign the DCO.

[giuseppe]

thanks! Comments addressed

[mrunalp]

• ## PR review: Request changes

Findings

1. [P2] Canonicalize namespace modes before serialization.
   Validation is case-insensitive and accepts nomap, but the container spec forwards the original value. Podman expects no-map, so nomap always fails; uppercase values such as AUTO also pass startup validation but fail creation. Normalize to Podman’s canonical values. PR code
   (

   OpenShell/crates/openshell-driver-podman/src/container.rs

   Lines 1219 to 1226 in 444fe35

   	userns: config.userns.as_deref().map(|raw| {
   	let (base, params) = raw
   	.split_once(':')
   	.map_or((raw, None), |(b, p)| (b, Some(p)));
   	UserNS {
   	nsmode: base.to_string(),
   	value: params.map(ToString::to_string),
   	}

   ), Podman contract
   (https://github.com/containers/podman/blob/f3829809246caaa533c1af29ecf27f613d3d2fd7/pkg/specgen/namespaces.go#L52-L65).

2. [P2] Reject or fully implement private.
   The config accepts private, but only auto receives idmappings. Podman requires at least one UID/GID mapping for a private user namespace, so every sandbox creation using this advertised mode fails. Either remove it from the allowlist or add mapping configuration. PR validation
   (

   OpenShell/crates/openshell-driver-podman/src/config.rs

   Lines 334 to 362 in 444fe35

   	/// Validate the optional `userns` mode against the supported allowlist.
   	///
   	/// Supported modes: `auto` (with optional params, e.g. `auto:size=65536`),
   	/// `host`, `keep-id` (with optional params), `private`, and `nomap`.
   	/// Modes that don't accept parameters (`host`, `private`, `nomap`) are
   	/// rejected when a colon-separated suffix is present.
   	pub fn validate_userns(&self) -> Result<(), crate::client::PodmanApiError> {
   	let Some(mode) = self.userns.as_deref() else {
   	return Ok(());
   	};
   	let (base, has_params) = mode
   	.split_once(':')
   	.map_or((mode, false), |(b, _)| (b, true));
   	match base.to_ascii_lowercase().as_str() {
   	"auto" | "keep-id" => Ok(()),
   	"host" | "private" | "nomap" => {
   	if has_params {
   	Err(crate::client::PodmanApiError::InvalidInput(format!(
   	"userns mode '{base}' does not accept parameters",
   	)))
   	} else {
   	Ok(())
   	}
   	}
   	_ => Err(crate::client::PodmanApiError::InvalidInput(format!(
   	"unsupported userns mode '{mode}'; \
   	supported modes: auto, host, keep-id, nomap, private",
   	))),
   	}

   ), Podman requirement
   (https://github.com/containers/podman/blob/f3829809246caaa533c1af29ecf27f613d3d2fd7/pkg/specgen/namespaces.go#L530-L543).

Required follow-ups

• Add a real Podman userns=auto sandbox E2E; unit tests only verify generated JSON and currently encode the incorrect nomap value.
• Update debug-openshell-cluster with userns/cache/bind-mount troubleshooting.

[mrunalp]

Two minor things left now:

• The E2E tests keep-id, not the issue’s primary auto/AutoUserNs path.
• PR description still incorrectly lists private as supported.

[mrunalp]

Needs rebase then we can kick off tests.

[mrunalp]

P2: clean up partially created TLS secrets (

OpenShell/crates/openshell-driver-podman/src/driver.rs

Lines 185 to 205 in cbbb604

	async fn create_tls_secrets(
	client: &PodmanClient,
	config: &PodmanComputeConfig,
	names: &[String; 3],
	) -> Result<(), ComputeDriverError> {
	let paths = [
	config.guest_tls_ca.as_deref(),
	config.guest_tls_cert.as_deref(),
	config.guest_tls_key.as_deref(),
	];
	for (name, path) in names.iter().zip(paths.iter()) {
	let Some(p) = path else { continue };
	let data = std::fs::read(p).map_err(|e| {
	ComputeDriverError::Message(format!("read TLS file '{}': {e}", p.display()))
	})?;
	client
	.create_secret(name, &data)
	.await
	.map_err(ComputeDriverError::from)?;
	}
	Ok(())

): if staging the second or third TLS file fails, earlier Podman secrets remain. The error path at
lines 809–817 does not remove them, and the server does not call driver deletion after failed creation. Clean up names before returning the error.

[mrunalp]

/ok to test 98e068e

[giuseppe]

I've added support also for userns: private in the last version to cover all the modes Podman supports