feat(service): add bearer authorization passthrough

[derekwaynecarr]

Summary

Allow an exposed sandbox service to opt into forwarding an application bearer
credential from the incoming HTTP or WebSocket request to the loopback service.
The default continues to strip Authorization, and the control-plane listener,
certificate, and authentication model remain unchanged in this iteration.

The motivating integration is an authenticated Codex App Server reached through
an OpenShell service URL. Codex validates the bearer capability during the
WebSocket handshake. OpenShell routes the request but does not authenticate the
application credential.

The Codex WebSocket transport is currently documented as experimental and
unsupported for production workloads. This feature remains application-neutral;
the Codex fixture is interoperability coverage, not a production-support claim.

Related Issue

#3851

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.

[derekwaynecarr]

/ok to test 1926927

[mrunalp]

Findings

1. Stable SDK source compatibility needs migration treatment. Rust callers constructing ServiceExposure must add a new field, and existing Go implementations of ServiceInterface no longer
   satisfy the changed method signature. These require notice and migration guidance under the project’s stability policy. See /tmp/openshell-pr3796-review/crates/openshell-sdk/src/
   types.rs:273, /tmp/openshell-pr3796-review/sdk/go/openshell/v1/service.go:33, and release policy (/tmp/openshell-pr3796-review/rfc/0014-release-stability/README.md:124).

2. The required accepted issue is not linked. This is a new feature and public API change, but the PR has no Related Issue section or closing issue reference. The template explicitly
   requires one. Its checklist syntax ([x ], [ x]) also does not render as checked. See PR template (/tmp/openshell-pr3796-review/.github/PULL_REQUEST_TEMPLATE.md:4).

3. The new E2E test has not run. GitHub reports OpenShell / E2E: test:e2e not applied; Branch Checks and Helm Lint remain pending despite the /ok to test comment. The bearer-forwarding E2E
   should execute before merge.

Implementation assessment

The design otherwise looks good:

• Omitted, legacy, and unknown stored values fail closed to strip.
• Passthrough accepts at most one valid Bearer value.
• Edge identity headers, proxy authorization, and authentication cookies remain stripped.
• HTTP and WebSocket paths share the validation.
• Persistence compatibility and mutation-replay fingerprints are covered.
• CLI, SDKs, documentation, architecture, and the relevant public skill were updated consistently.

[github-actions]

Label test:e2e applied, but pull-request/3796 does not exist yet. A maintainer needs to comment /ok to test 1926927da3d0638256195bc8018f47be8397aa56 to mirror this PR. Once the mirror exists, re-apply the label or re-run Branch E2E Checks from the Actions tab.

[drew]

/ok to test 1926927

[drew]

gator-agent

Follow-Up Needed

Thanks @mrunalp. I checked your points against the current head: the independent code review found no additional implementation blocker, but this feature still has no linked accepted issue, the stable Rust ServiceExposure struct and Go ServiceInterface change without migration guidance, and the new E2E has not run. I also confirmed that the PR checklist boxes do not render as checked.

Action required: @derekwaynecarr, please link the accepted issue in a Related Issue section and add the required SDK compatibility notice and migration guidance (or preserve source compatibility). Please also fix the checklist syntax while updating the PR body.

Gator applied test:e2e and posted the required /ok to test command, but the mirror is not available yet. Gator will re-check test dispatch after the author follow-up.

If the PR author or a maintainer does not respond within 48 business hours, this may be closed. Weekend hours do not count toward the TTL.

Gator metadata

• Validation: maintainer-authored work is normally auto-valid, but a trusted maintainer explicitly requires the accepted issue linkage for this new public feature.
• Docs: Fern sandbox-service documentation and architecture documentation are updated.
• Checks: Branch Checks and Helm Lint remain pending; the E2E workflow has not started.
• E2E: test:e2e applied; mirror/test dispatch still pending.
• Head SHA: 1926927da3d0638256195bc8018f47be8397aa56
• Base SHA: e63cfa118204e1322983ea1f01b4d1ef2401860a
• Merge base SHA: eef8bec0c96b384556d608f8d899a8a96f5d17a1
• Patch ID: d320cbd90bed4bd0f076c02b928c7e882cb780dd
• Gator payload: 10
• Review mode: initial
• Previous reviewed SHA: none
• Review budget exhausted: no
• Maintainer decision required: no
• Next state: gator:follow-up-needed
• Blocked reason: accepted_issue_and_sdk_migration_guidance_required

[derekwaynecarr]

/ok to test 3bc9828

[pimlock]

/ok to test 3bc9828

[pimlock]

/ok to test 3bc9828

FYI @derekwaynecarr I'm fixing you're not being able to trigger the copy bot, it will be working soon.

[derekwaynecarr]

/ok to test 2d694c3

[derekwaynecarr]

/ok to test af2240e

[freeqaz-openai]

from my clanker after looking at your change + designing around it in OCE:

Thanks, Derek. We are planning to use this path for dedicated Codex Agents in OpenClaw Enterprise.

Could we add an end-to-end WebSocket case for bearer passthrough before this lands? At af2240e, the new passthrough E2E checks HTTP requests, while the WebSocket test checks the constructed upstream request.

It would be useful to exercise a real upgrade through the exposed service, verify that the application accepts a valid bearer and exchanges frames, and verify that the application rejects a missing or incorrect bearer. A default-strip case would also confirm that a credential is not forwarded unless the service opts in. We will separately qualify OCE's TLS, authority and revision lifecycle around the route.

This is a coverage request for the intended WebSocket use case, not a claim that the current implementation is broken. We are testing against the current PR head locally as well.