fix(inference): authenticate pin-route revocation with its policy

[yanyunl1991]

Summary

Revoking a superseded HTTPS Pin Runtime route has to authenticate the running adapter, and
the control-plane challenge proof binds the route-source policy that adapter was started
with. The revoke path never supplied one, so it proved against the loopback default while
every sandbox-facing adapter runs on the OpenShell bridge range. The superseded route stayed
registered with its raw upstream credentials resident. This PR records the policy when the
adapter is started or reused and reads it back at revocation.

Closes #7878.

Reproduction

Run on our DGX Spark aarch64 test host (GB10 GPU) — the reporter's platform is aarch64, so
the repro was not moved to x86_64:

# 1. OpenClaw sandbox onboarded on nvidia-prod
# 2. create a compatible-endpoint on a DNS-backed HTTPS endpoint
nemoclaw <sandbox> inference set --provider compatible-endpoint \
  --endpoint-url https://<dns-host-a>/v1 --model <model> \
  --credential-env COMPATIBLE_API_KEY --inference-api openai-completions
# 3. update the endpoint URL to a different DNS-backed HTTPS endpoint
nemoclaw <sandbox> inference set --provider compatible-endpoint \
  --endpoint-url https://<dns-host-b>/v1 --model <model> \
  --credential-env COMPATIBLE_API_KEY --inference-api openai-completions

Environment

• Test machine: our DGX Spark aarch64 test host (GB10 GPU)
• Ubuntu, aarch64, Node v22.22.2, OpenShell 0.0.85
• NemoClaw main 4dcb89ea1d89c0e46fc24a880b9f7cfdd8241efc
• Sandbox: OpenClaw, onboarded on nvidia-prod, switched to compatible-endpoint

Observed on main (before fix)

The update exits 0 and only warns:

  Setting OpenShell inference route: compatible-endpoint / <model>
  Warning: the new inference route is committed, but superseded HTTPS Pin Runtime route
  '94606712…' could not be revoked: Cannot authenticate the live HTTPS Pin Runtime adapter
  for revocation.. The raw upstream endpoint was not restored; uninstall NemoClaw to stop
  the adapter and purge its in-memory credentials if this persists.
  Inference route synced for '<sandbox>': inference/<model>

Host recovery state shows the superseded route is still registered:

before update  routes: ['94606712…']
after  update  routes: ['94606712…', '01806a14…']

The adapter's own log records both registrations and no revocation — the probe never
reached the control plane:

{"event":"adapter_ready","allowedSourceCidrs":"172.18.0.0/16","routeCount":0}
{"event":"route_registered","routeId":"94606712…","routeCount":1}
{"event":"route_registered","routeId":"01806a14…","routeCount":2}

Probing the live adapter directly isolates the cause — same token, only the policy differs:

probe WITHOUT expectedSourceCidrs (what revoke does)  -> false
probe WITH the adapter's actual 172.18.0.0/16         -> true

Observed on fix/... (after fix)

  Setting OpenShell inference route: compatible-endpoint / <model>
  Context window for '<model>': 131072 tokens
  Inference route synced for '<sandbox>': inference/<model>          <- no warning

allowedSourceCidrs: ['172.18.0.0/16']
after update  routes: ['01806a14…']                                  <- superseded route gone

The adapter log now shows the revocation reaching the control plane, which never appeared
before:

{"event":"route_registered","routeId":"94606712…","routeCount":2}
{"event":"route_revoked","routeId":"01806a14…","routeCount":1}
{"event":"route_registered","routeId":"01806a14…","routeCount":2}
{"event":"route_revoked","routeId":"94606712…","routeCount":1}

The upgrade path was exercised on the same host: this adapter had been started by the
unfixed build (allowedSourceCidrs: None). The first inference set on the fixed build
recorded the policy, and the next switch revoked cleanly — no adapter restart and no
NemoClaw uninstall.

Analysis

probeAdapterControlHealth builds the challenge proof over the route-source policy:

const expectedSources = buildAllowedRouteSourceMatcher(
  options.expectedSourceCidrs ?? ["127.0.0.1/32"],
);
const expectedProof = controlChallengeProof(
  options.controlToken, nonce, expectedIdentity, routeSourcePolicyDigest(expectedSources.cidrs),
);

Three callers reach it. waitForAdapterHealth takes the policy as a required parameter and
findReusableAdapterControlToken receives it from its caller — both are on the registration
path, which is why registering routes always worked. revokeRouteLocked passed neither, so
it fell back to 127.0.0.1/32 while ensureHttpsPinRuntimeAdapterRoute starts every adapter
with the discovered openshell-docker IPAM subnets. The digests differ, the proof does not
match, authenticatedLiveAdapter is false, and because the PID is an adapter process the
path throws Cannot authenticate the live HTTPS Pin Runtime adapter for revocation.

inference-set.ts catches that, warns, and continues — the new route is committed, the old
route stays in adapter memory with its upstream credential, and the only remedy offered is
uninstalling NemoClaw. destroy.ts calls the same revoke helper and prints the same class of
warning, so the failure was not specific to the update path.

Fix

Record the route-source policy the adapter is actually running under in host recovery state,
and use that recorded value at revocation.

• ensureAdapterProcessLocked writes it alongside the pid at spawn — that is the policy the
  child was launched with.
• persistRouteState writes it on every successful registration, which also covers the
  adapter-reuse path where no spawn happens but findReusableAdapterControlToken has just
  proven the live adapter answers under that policy.
• removeRouteState carries it forward; dropping one route does not change the policy the
  adapter is running under.
• revokeRouteLocked reads it back and passes it to the probe.

Why not re-derive it at revocation. Calling discoverOpenShellBridgeSourceCidrs() in the
revoke path is a smaller diff and looks equivalent, but it re-derives the value it then uses
to authenticate: discovery returns whatever the bridge looks like now, so a recreated or
renumbered openshell-docker network produces a policy the running adapter never used and
the same leak returns. That leaves a subset of the reported class unfixed. The recorded value
is the fact; discovery is an inference about it.

Failure path. When no policy is recorded — an adapter started before this change — the
revoke path fails closed: it does not probe, does not delete the route, and does not drop the
route record, so the caller keeps warning and nothing is silently lost. Falling back to the
default or to re-discovery would authenticate the adapter against a value this process just
made up. The error names the recovery step, and the next route registration records the
policy, so an existing adapter heals without a restart (verified above).

Whole-class review. All three probeAdapterControlHealth call sites now carry a real
policy. Both consumers of revokeHttpsPinRuntimeAdapterRoute — inference-set.ts (endpoint
update) and sandbox/destroy.ts (last-reference teardown) — are fixed by the change inside
revokeRouteLocked; neither needed its own edit. Nothing widens what the adapter accepts:
the proof still binds the policy digest, the token check is unchanged, and the adapter's own
source-CIDR enforcement is untouched.

Tests (https-pin-runtime-revoke-source-policy.test.ts, split out so the existing suite
stays inside the test-file size budget): revocation probes with the recorded policy and
deletes the route; a live adapter with no recorded policy fails closed without probing,
deleting, or dropping state; an absent adapter with no recorded policy still clears its stale
record (regression lock on today's behaviour); a recorded policy that no longer matches still
reports the original authentication failure; and five malformed-record shapes (absent, empty,
non-array, non-string entries, blank entries) are all rejected rather than partially trusted.

Changes

• src/lib/inference/https-pin-runtime-adapter.ts: record the route-source policy at spawn and on registration, carry it across route removal, and authenticate revocation with it
• src/lib/inference/https-pin-runtime-revoke-source-policy.test.ts: new focused suite for the revocation policy contract
• src/lib/inference/https-pin-runtime-adapter.test.ts: thread the new dependency through the existing revoke cases
• docs/inference/custom-endpoint-security.mdx: document the recorded policy, why it is not re-derived, and the recovery step for an adapter started before it existed

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)

Verification

• npx prek run --all-files passes
• npm test passes (touched files at minimum)
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• make 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)

AI Disclosure

• AI-assisted — tool: Claude Code

Signed-off-by: Yanyun Liao yanyunl@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved HTTPS endpoint route revocation by authenticating against the source policy recorded when the adapter started.
  • Revocation now fails safely when the required policy is missing, invalid, or no longer matches.
  • Added cleanup handling for stale adapter state while preserving routes and credentials when deletion fails.
  • Added clearer recovery guidance: rerun endpoint configuration to enable clean revocation after policy changes.

• Documentation

  • Documented HTTPS adapter revocation behavior, source-policy handling, and recovery steps.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 226a3ba9-989e-44ed-862f-93ebbd2e3648

📥 Commits

Reviewing files that changed from the base of the PR and between 567d1b0 and 221a0b9.

📒 Files selected for processing (2)

• docs/inference/custom-endpoint-security.mdx
• src/lib/inference/https-pin-runtime-revoke-source-policy.test.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/lib/inference/https-pin-runtime-revoke-source-policy.test.ts

---

📝 Walkthrough

Walkthrough

The HTTPS Pin Runtime adapter now persists its actual allowed-source CIDR policy and uses it during route revocation authentication. Revocation fails closed when policy data is missing or mismatched. Tests and endpoint security documentation cover the updated behavior.

Changes

HTTPS Pin Runtime revocation

Layer / File(s)	Summary
Persist the adapter source policy src/lib/inference/https-pin-runtime-adapter.ts	Validated allowed-source CIDRs are persisted with route and adapter state during registration and adapter spawn.
Authenticate revocation with recorded policy src/lib/inference/https-pin-runtime-adapter.ts, src/lib/inference/https-pin-runtime-adapter.test.ts	Revocation reads the recorded policy and passes it to health probing. Missing or mismatched policies prevent route deletion while preserving state.
Validate and document revocation behavior src/lib/inference/https-pin-runtime-revoke-source-policy.test.ts, docs/inference/custom-endpoint-security.mdx	Tests cover successful revocation, fail-closed behavior, stale-state cleanup, malformed policies, and canonicalization. Documentation describes the updated revocation rules.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Suggested reviewers: cjagwani, cv, sandl99

Sequence Diagram(s)

sequenceDiagram
  participant EndpointUpdate
  participant revokeRouteLocked
  participant AdapterState
  participant ControlHealthProbe
  participant RouteRegistry
  EndpointUpdate->>revokeRouteLocked: revoke superseded route
  revokeRouteLocked->>AdapterState: read recorded source CIDRs
  revokeRouteLocked->>ControlHealthProbe: authenticate with token and CIDR policy
  ControlHealthProbe-->>revokeRouteLocked: authenticated adapter proof
  revokeRouteLocked->>RouteRegistry: delete authenticated route

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the inference revocation authentication fix, which is the primary change.
Linked Issues check	✅ Passed	The changes record route-source policies and use them for revocation, addressing stale routes and in-memory credentials in issue #7878.
Out of Scope Changes check	✅ Passed	The implementation, tests, and documentation changes directly support the linked issue and stated pull request objectives.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/https-pin-revoke-source-policy-7878

---

_{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 in commit 1d5ebb7 in the fix/https-pin-revoke... branch remains at 96%, unchanged from commit 43eb929 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 1d5ebb7 in the fix/https-pin-revoke... branch remains at 81%, unchanged from commit e824843 in the main branch.

Show a code coverage summary of the most impacted files.

File	main e824843	fix/https-pin-revoke... 1d5ebb7	+/-
src/lib/onboard/env.ts	100%	100%	0%
src/lib/onboard...reate-launch.ts	100%	100%	0%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/inferen...time-adapter.ts	62%	64%	+2%

---

_{Updated August 01, 2026 11:32 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7889.docs.buildwithfern.com/nemoclaw

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

3 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• ubuntu-repo-cloud-openclaw: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• ubuntu-policy-custom-missing-presets-negative: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• hermes-inference-switch: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

Second-opinion E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: inference-routing, network-policy

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[cjagwani]

Approved exact head ac46b7dff6f49d5a239077652fea621f6d5f3842.

Security review: PASS across credential handling, authentication/authorization, injection, file/state handling, network policy/SSRF boundaries, TOCTOU behavior, cryptography, dependencies, and fail-closed errors. The adapter-wide source-CIDR policy is recorded only after authenticated spawn/reuse, canonicalized with the existing matcher on read, and bound into the revocation challenge. Missing, malformed, or mismatched provenance never deletes the credential-bearing route; an absent adapter still clears stale state.

All 54 exact-head checks are green, including CodeQL, self-hosted sandbox/gateway coverage, image builds, macOS E2E, and the protected E2E gate. DCO and the Verified commit pass; no unresolved major/critical findings remain. Stale-base-only failure is waived because GitHub reports MERGEABLE/conflict-free.