feat: verify provider-authenticated call ingress before sandbox relay

[sandl99]

Problem Statement

Related: NVIDIA/NemoClaw#6207.
VoiceClaw referencces

• Prioritized VoiceClaw platform-issues spreadsheet
• Detailed VoiceClaw platform-issues document

VoiceClaw and OpenClaw voice-call need telephony providers to call back into a sandbox/plugin safely. Public ingress hosting is out of scope for OpenShell: an operator, reverse proxy, load balancer, or deployment layer can own the public HTTPS/WSS endpoint.

The OpenShell gap is narrower: once an inbound request reaches the service-routing boundary, OpenShell should be able to verify that it came from the declared provider before relaying it into the sandbox. Twilio/Plivo/Telnyx-style providers authenticate with provider signatures, HMACs, timestamps, and replay controls, not normal OpenShell user auth.

Without this, integrations either trust unauthenticated inbound traffic or rebuild provider verification in ad hoc host-side glue.

Who will use this

• VoiceClaw call flows.
• OpenClaw voice-call plugin.
• NemoClaw sandboxes running voice-enabled OpenClaw.
• Telephony integrations such as Twilio, Plivo, Telnyx, and Vonage.
• Operators and security teams who need audited inbound verification before sandbox relay.

Proposed Design

Add provider-authenticated inbound verification to existing OpenShell service routing.

Example policy shape:

services:
  - name: voice-call-webhook
    target:
      sandbox: voiceclaw
      port: 7880
      path: /voice/webhook
    inbound_auth:
      provider: twilio
      secret_ref: providers.twilio.auth_token
      methods: [POST]
      paths:
        - /voice/webhook/**
      max_body_bytes: 262144
      replay_window_seconds: 300
      rate_limit:
        requests: 60
        window_seconds: 60

OpenShell should:

• verify provider signatures or HMACs before sandbox relay
• support provider verifier profiles, starting with generic HMAC and Twilio-style request signing
• support timestamp and replay-window validation
• enforce method/path policy
• enforce body-size limits
• enforce rate limits
• resolve verification secrets through OpenShell secret refs, not sandbox-visible env vars
• preserve the raw request body for signature validation
• support trusted forwarded host/scheme headers so signatures based on the public URL can validate behind a reverse proxy
• relay only verified requests to the declared sandbox/plugin target
• strip or overwrite spoofable verification headers before forwarding
• emit OCSF logs for verified, denied, replayed, oversized, and rate-limited inbound requests

OpenClaw should still own provider event semantics. OpenShell should own only the authentication membrane and safe relay.

Alternatives Considered

• Make OpenShell host the public endpoint. Rejected for this issue; public ingress exposure is deployment-specific and out of scope.
• Put all verification in OpenClaw/VoiceClaw. This works, but it pushes provider secrets and unauthenticated traffic deeper into the stack and repeats the same verification logic per integration.
• Use normal OpenShell user auth. Telephony providers do not authenticate as OpenShell users; they use provider-specific signatures and replay controls.
• Allow unauthenticated service routing and trust network placement. This is too weak for call-control callbacks that can affect live calls.

Agent Investigation

• Reviewed NemoClaw #6207, which tracks VoiceClaw-related OpenShell networking follow-ons.
• Inspected local ../openclaw Voice Call code. Provider event semantics and telephony-specific parsing belong in OpenClaw, but the service-routing boundary is the right place for OpenShell to reject unauthenticated inbound requests before sandbox relay.
• Searched OpenShell issues for close duplicates using provider-authenticated ingress, HMAC service routing, and Twilio ingress; no exact umbrella issue was found.
• Confirmed this issue is intentionally separate from the governed realtime media membrane: this is about inbound request verification, not media transport egress.

Acceptance Criteria

• A service route can require provider-authenticated inbound verification.
• Invalid signatures are denied before sandbox relay.
• Replayed requests are denied.
• Oversized bodies are denied.
• Rate limits are enforced.
• Verified requests are relayed only to the declared sandbox/plugin target.
• Provider verification secrets are resolved at the OpenShell boundary and are never exposed to the sandbox.
• OCSF logs record allow/deny decisions without logging secrets or full request bodies.

Non-Goals

• OpenShell does not host the public internet endpoint.
• OpenShell does not implement Twilio/Plivo/Telnyx event semantics.
• OpenShell does not expose arbitrary inbound sandbox listeners.
• OpenShell does not replace OpenClaw voice-call.
• This is not generic unauthenticated ingress.

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request