[jhjaggars]

Summary

Both browser login flows (OIDC Authorization Code + PKCE and the edge/mTLS browser flow) bind their callback listener to an ephemeral port on 127.0.0.1. When the CLI runs inside a container — for example the hypershell installer's wrapper — the wrapper cannot know a randomly chosen port in advance, so it cannot publish the port to the host and the browser can never reach the callback. This PR adds two environment variables that make browser login work in that setting, with defaults unchanged.

Related Issue

Fixes #5066

Changes

• New crates/openshell-cli/src/callback.rs module with a shared bind_callback_listener() helper used by both browser login flows. It honors:
  • OPENSHELL_CALLBACK_PORT — pin the callback listener to a fixed TCP port (validated integer from 1 to 65535) so a container wrapper can publish -p 127.0.0.1:<port>:<port> before login starts.
  • OPENSHELL_CALLBACK_BIND_ADDRESS — override the listener bind address (validated IP address, IPv4 or IPv6; e.g. 0.0.0.0 for pasta/slirp4netns user-mode container networking, ::1 for IPv6-only hosts).
• oidc_browser_auth_flow (crates/openshell-cli/src/oidc_auth.rs) and browser_auth_flow (crates/openshell-cli/src/auth.rs) now bind through the shared helper; the port used in the redirect URI / callback_port URL parameter is still derived from the bound listener.
• Clear errors: an invalid port or address value, or a fixed port that is already in use, fails the login command with a message naming the variable and the remediation, instead of falling back silently.
• IPv6 callback routing (b676200, addressing review feedback): the browser-facing callback target derives from the bound address — wildcard binds map to the matching loopback (0.0.0.0 → 127.0.0.1, :: → [::1]), and IPv6 addresses render bracketed (http://[::1]:<port>/callback). The edge flow passes a strictly loopback-validated callback_host parameter to the gateway connect page (crates/openshell-server/src/auth/http.rs), which brackets IPv6 in the fetch URL and CSP connect-src, falls back to 127.0.0.1 for anything malformed or non-loopback (so the embedded edge token can never be directed to an external host), and preserves the host across the waiting-page refresh. The bundled Keycloak realm (scripts/keycloak-realm.json) now also allows http://[::1]:* redirects for the CLI client.
• Docs: new "Browser Login Callbacks" section in docs/how-it-works/gateways/authentication.mdx with the env-var table, container example, IPv6 behavior, and security notes.

Design choices

• Default unchanged. With both variables unset, the listener binds 127.0.0.1:0 exactly as before — no behavior change for host users.
• Bind address is a separate, explicit control. 0.0.0.0 is never implied by setting a fixed port. Binding 0.0.0.0 on a host machine would expose the short-lived callback server to the local network, so widening the bind address requires the explicit OPENSHELL_CALLBACK_BIND_ADDRESS=0.0.0.0, which only a container wrapper that also publishes the port to host loopback (-p 127.0.0.1:<port>:<port>) should set. The port is never exposed beyond host loopback.
• The callback URL derives from the bound address, so the callback matches the listener. IPv4 binds (including the default and 0.0.0.0 in a container, where the wrapper publishes the port to host loopback) use http://127.0.0.1:<port>/callback; IPv6 binds use the bracketed RFC 8252 form http://[::1]:<port>/callback. The bundled Keycloak realm allows all three loopback redirect prefixes (127.0.0.1, localhost, [::1]). IPv6 callback binds are fully supported for OIDC login.
• Known limitation — IPv6 edge login. The gateway connect page enforces a CSP that must allow the callback target, and Chrome does not currently support IPv6 literals in CSP connect-src source expressions, so an IPv6-bound CLI cannot complete edge login in Chrome (the page's POST is blocked by CSP and it reports it could not reach the CLI). This is a browser limitation, documented in the auth reference; the connect page keeps the IPv4 loopback source in its policy so it never degrades to empty. IPv6 edge login is out of scope here; all IPv4 paths, including the container use case, are unaffected.
• Why a fixed port rather than --network=host: --network=host works on Linux but not with a podman machine VM on macOS, so the fixed published port is the portable approach.

How the hypershell installer will use it

The wrapper will set OPENSHELL_CALLBACK_PORT=<fixed> and OPENSHELL_CALLBACK_BIND_ADDRESS=0.0.0.0 for the CLI inside the container and run the container with -p 127.0.0.1:<port>:<port>, exposing the callback only on host loopback. That installer change is intentionally out of scope here and waits for this to ship in a release.

Testing

• mise run pre-commit passes (the only failure is a pre-existing openshell-supervisor-process clippy lint that fails identically on main; verified via git stash)
• Unit tests added/updated
• E2E tests added/updated (if applicable)

Unit tests cover the shared helper and both flows:

• callback.rs: default ephemeral loopback bind; fixed port; fixed port already in use (clear error naming OPENSHELL_CALLBACK_PORT); valid/invalid port values (0, negative, 65536, non-numeric, whitespace); wildcard 0.0.0.0 bind; fixed port + wildcard combined; IPv6 ::1 and :: binds; invalid bind addresses (hostname, ip:port, garbage); callback host/target derivation table; callback reachability probe (connecting to the advertised [::1] target succeeds while 127.0.0.1 is refused on a ::1 bind)
• oidc_auth.rs: default bind produces http://127.0.0.1:<ephemeral>/callback; fixed port + 0.0.0.0 bind keeps the redirect URI on 127.0.0.1 with the fixed port; ::1 and :: binds produce http://[::1]:<port>/callback; invalid port value fails
• auth.rs: default bind advertises the ephemeral port in the /auth/connect URL; fixed port + 0.0.0.0 bind advertises the fixed port; ::1 bind advertises callback_host=::1; invalid port value fails
• openshell-server/src/auth/http.rs: sanitize_callback_host accepts only loopback IP literals (IPv4 and IPv6; hostnames, non-loopback IPs, brackets, and garbage fall back to 127.0.0.1); connect page targets 127.0.0.1 by default and bracketed [::1] when provided; waiting page preserves callback_host across refresh

Verification run on top of current main: cargo test -p openshell-cli -p openshell-server all green (405 + 2522 lib tests plus integration targets, including 33 callback/flow tests), cargo clippy -p openshell-cli -p openshell-server --all-targets -- -D warnings clean, cargo fmt --check clean, markdownlint clean.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable) — not needed; user-facing behavior is documented in docs/how-it-works/gateways/authentication.mdx

[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.

[jhjaggars]

Thanks for reviewing! Two maintainer actions are needed to unblock CI on this fork PR:

1. Issue acceptance: the linked feature request feat(cli): fixed callback port for browser login inside containers #5066 needs triage and state:accepted for the PR Issue Acceptance check to pass.
2. Mirror: Branch Checks / Helm Lint are waiting for /ok to test a9426dcb3 to mirror this PR and run the Rust/doc checks.

The Publish required CI gate statuses failure is a transient API blip (empty JSON response while checks were still pending — the same evaluation passed on the previous push); it re-runs automatically when Branch Checks completes. Local verification on top of current main (9f1cdb4): cargo test -p openshell-cli all green (399 lib + integration tests, including 17 new tests for the callback binding), cargo clippy --workspace --all-targets -- -D warnings clean, cargo fmt --check clean, markdownlint clean.

[TaylorMutch]

Reviewed locally at a9426dc. The shared helper preserves existing defaults and authentication checks. I recommend addressing the IPv6 callback mismatch noted inline before merging. Validation: cargo test -p openshell-cli --lib callback passed 23 tests; cargo test -p openshell-cli --lib browser_flow passed 6 tests. A separate connection probe using the exact binding helper confirmed the IPv6 mismatch. Full container/IdP login was not exercised.

[TaylorMutch]

/ok to test a9426dc

[jhjaggars]

Good catch — the PR description was accidentally overwritten with unrelated content from a local temp-file collision; it's now restored with Fixes #5066 and the b676200 changes. The PR Issue Acceptance check passes again.

Still needing a maintainer /ok to test b67620015 to run Branch Checks/Helm Lint on the new commit.

[TaylorMutch]

Reviewed the update at b676200. The earlier IPv6 listener/redirect mismatch is addressed, and the IPv4 fixed-port/container path looks reasonable. One remaining IPv6 edge-login limitation is noted inline. IPv6 edge login can be out of scope for this PR if acknowledged explicitly and the documentation/PR description reflects that limitation; fixing it here is not required on that basis. The linked issue #5066 is now state:accepted, and the PR description has been corrected. Validation: local Chrome CSP reproduction with an IPv4 control; full container/IdP login was not exercised and Rust tests did not complete locally.

[TaylorMutch]

/ok to test b676200

[TaylorMutch]

/ok to test 2fee68f

[TaylorMutch]

Final review at 2fee68f: looks good for the documented scope. The IPv4 fixed-port/container login path preserves the existing defaults and authentication checks, and IPv6 callback routing is supported for OIDC. The remaining Chrome CSP limitation for IPv6 edge login is explicitly acknowledged and documented as out of scope, which is acceptable for this PR. No new blocking findings. Local validation passed: 27 CLI callback tests, 9 browser-flow tests, and 21 gateway auth HTTP tests, including the updated CSP test. Full container/IdP login was not exercised. The linked issue #5066 is accepted. Merge remains conditional on required CI passing.