fix(openshell): require literal loopback for plaintext gRPC

[ericksoa]

Summary

Hardens the new direct gRPC client so plaintext transport is accepted only for literal loopback IP addresses. DNS hostnames such as localhost must use TLS because their resolution is not fixed by the endpoint string.

This is PR 3 of 26 in the OpenShell gRPC migration stack.

Changes

• Validate plaintext endpoints with Node's IP parser instead of a hostname or dotted-string heuristic.
• Accept IPv4 127.0.0.0/8 and IPv6 ::1 literals only.
• Reject localhost, non-loopback IPs, malformed dotted addresses, and non-HTTP(S) endpoint forms.
• Update the direct-client fixtures and focused endpoint-safety coverage.

Stack

• Stack index: refactor(openshell): establish sandbox control boundary #6790
• Depends on: feat(openshell): route session reads over pinned gRPC #6791
• Review this PR against base branch chore/openshell-grpc-protocol/ae to see only this slice.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification: this slice tightens an internal transport safety check before any product call site selects direct gRPC.
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: plaintext is restricted to literal kernel-recognized loopback addresses; hostnames and malformed or non-loopback addresses fail closed.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — focused direct gRPC client tests passed (21 tests), including IPv4 and IPv6 loopback acceptance; npm run typecheck:cli passed
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — targeted and changed-graph validation were used; required CI supplies the broad repository gates
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Aaron Erickson aerickson@nvidia.com

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: bc8fd75c-529a-49b4-a9f1-0260ec3c493b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/openshell-grpc-client/ae

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the chore/openshell-grpc... branch.

TypeScript / code-coverage/cli

The overall coverage in the feat/openshell-grpc-... branch remains at 79%, unchanged from the chore/openshell-grpc... branch.

Show a code coverage summary of the most impacted files.

File	chore/openshell-grpc... b85f5b2	feat/openshell-grpc-... 48748eb	+/-
src/lib/adapter...ocker/volume.ts	85%	70%	-15%
src/lib/security/redact.ts	99%	95%	-4%
src/lib/runner.ts	72%	75%	+3%
src/lib/adapter.../docker/pull.ts	79%	83%	+4%
src/lib/messagi...nes/template.ts	95%	100%	+5%
src/lib/messagi...onfig-parser.ts	83%	90%	+7%
src/lib/messagi...ate-resolver.ts	76%	88%	+12%
src/lib/messagi...ate-resolver.ts	56%	78%	+22%
src/lib/adapter...dbox-control.ts	0%	98%	+98%
src/lib/adapter...dbox-control.ts	0%	100%	+100%

---

_{Updated July 14, 2026 04:55 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Primary next action: No advisor follow-up required beyond maintainer review.
Findings: 0 blockers · 0 warnings · 0 optional suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (non-blocking second opinion): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 more warning, the same number of suggestions.

Nemotron is a non-blocking second opinion. Its prose, findings, and E2E guidance do not change the primary assessment above and remain in workflow artifacts only.

E2E guidance

Advisory only: coverage and selector recommendations are non-authoritative. E2E / PR Gate independently computes and dispatches trusted jobs without consuming this output.

Recommended coverage: None
Recommended selectors: None

1 optional coverage item · 1 optional selector · 0 new-test recommendations

• Optional coverage openshell-gateway-auth-contract — Selected from the trusted checked-in E2E coverage inventory.
• Optional selector openshell-gateway-auth-contract — Selected as a trusted checked-in E2E job.

Workflow run details

This is an automated, non-authoritative review. Findings are inputs to maintainer adjudication. Warnings and optional suggestions do not require a response or follow-up. A human maintainer makes the final merge decision.