Scoped credentials for outgoing HTTP — host‑held secrets, guest‑held names

[simongdavies]

Scoped credentials for outgoing HTTP — host-held secrets, guest-held names

Introduces a credential indirection for outgoing HTTP requests. The host
registers named credentials, each with a URL-scope, the header name to set,
a value prefix, and a resolver callback that produces the secret token.
The guest only ever sees the credential's opaque registered name and binds
it to an outgoing request via a new WIT call. At dispatch time the host
resolves the token, enforces the scope, and injects the header — all
after the guest has handed the request off. The secret never crosses
the guest boundary.

Security model

• Secrets never enter the guest address space. The guest cannot read,
  log, printf, or exfiltrate the credential value. The token only exists
  on the host side of the WASI HTTP dispatch path, between resolver
  invocation and request transmission.
• Opaque handle. The guest holds only the credential's registered name
  — a string the host chose. Knowing the name is not enough to use, fetch,
  or reconstruct the secret without the host-side registry.
• Scope-bound and gate-bound. Each credential carries a target URL
  prefix. At dispatch the host checks the request URL prefix-matches the
  credential's target before the existing allow_domain network
  gate — a mis-scoped credential is rejected up-front. Both checks must
  pass for the request to go out.
• Guest cannot override the host-injected header. After the host has
  decided which credential header to inject, any guest-set header with the
  same name (case-insensitive) is filtered out before the request is
  built. The guest cannot smuggle its own Authorization: past the host.
• No diagnostic leakage on resolver failure. If a resolver returns an
  error, only a fixed, host-redacted message ("credential resolver failed") is surfaced as the request error. The resolver's own
  diagnostic string is dropped before crossing the boundary — and
  hyperlight_sandbox does not log it either, so an Err returned
  from inside a resolver cannot accidentally write secret material into a
  host log. Resolver authors that need diagnostics should record them
  inside the resolver itself (via their own logger) before returning the
  Err; the ResolverFn rustdoc spells this out. The Python SDK takes
  this further: when a Python resolver raises, only the exception
  type name is forwarded — the message body is discarded (it may have
  been assembled from secret material).
• Secrets cannot leak via Debug / logs / panics. CredentialEntry
  has a hand-written Debug impl that renders the resolver as
  "<callback>". The closure (and anything it captures) never appears in
  log lines, panic backtraces, or dbg! output.
• Per-sandbox isolation. The registry is owned by an individual
  Sandbox<G> instance; there is no global table, no lazy_static, no
  shared OnceCell. Two sandboxes that happen to use the same credential
  id each see only their own resolver. Exercised by an integration test.
• No lock held across the resolver. The registry mutex is released
  before the resolver runs, so a slow resolver (e.g. one that does a real
  IMDS round-trip) cannot stall unrelated credentialed requests.

Flow

1. Host calls
   Sandbox::register_credential(id, CredentialEntry { target, header, prefix, resolver })
   before run(). Registrations are immutable for the lifetime of the
   sandbox; duplicate ids are rejected.
2. Guest builds a wasi:http/outgoing-request and calls the new WIT
   import hyperlight:sandbox/credentials.attach(request, "<credential-id>").
   The guest never sets the credential header itself.
3. Host outgoing-handler, at dispatch time:
   1. clones the credential entry out of the registry by id; the mutex is
      then dropped (→ guest-visible InternalError if the id has gone
      missing — defensive: attach validated it on the way in),
   2. enforces the scope: the request URL must prefix-match
      entry.target (→ guest-visible HTTPRequestDenied if not, before
      the network gate),
   3. invokes the resolver callback to obtain the token (→ host-redacted
      InternalError("credential resolver failed") on error — the
      resolver's diagnostic is dropped),
   4. filters any guest-set header matching the credential header
      (case-insensitive),
   5. injects <header>: <prefix><token> into the outgoing request,
   6. proceeds through the normal allow_domain network gate.

The guest observes only the outcome (success / HTTPRequestDenied /
InternalError). Steps 3.iii–v happen entirely host-side.

API surface

Rust (hyperlight_sandbox)

New credentials module:

pub type ResolverFn = Arc<dyn Fn() -> Result<String, String> + Send + Sync>;

pub struct CredentialEntry {
    pub target: String,    // URL-prefix scope
    pub header: String,    // e.g. "Authorization"
    pub prefix: String,    // e.g. "Bearer "
    pub resolver: ResolverFn,
}

impl CredentialEntry {
    /// Convenience for tests / short-lived static tokens.
    pub fn with_static_resolver(
        target: impl Into<String>,
        header: impl Into<String>,
        prefix: impl Into<String>,
        token:  impl Into<String>,
    ) -> Self;
}

pub type CredentialRegistry = Arc<Mutex<HashMap<String, CredentialEntry>>>;

• Sandbox::register_credential(id, entry) — host-only API; rejects
  duplicate ids; must be called before run().
• Guest::build now receives the CredentialRegistry so backends can
  wire it into their outgoing-handler implementation. The registry is
  plumbed only to the host-side dispatch path; it is not surfaced to the
  guest in any form.

WIT (hyperlight:sandbox/credentials)

interface credentials {
    use wasi:http/types@0.2.0.{outgoing-request};

    variant credential-error {
        unknown,
        scope-mismatch,
        resolver-failed(string),  // host-redacted, never the raw diagnostic
        already-attached,
    }

    attach: func(
        request:    borrow<outgoing-request>,
        credential: string,
    ) -> result<_, credential-error>;
}

This is the only credential-related surface the guest sees.
attach itself returns unknown / already-attached; scope-mismatch
and resolver-failed are produced at dispatch time as HTTP error codes
(HTTPRequestDenied / InternalError) since attach does not yet have
the request URL or run the resolver.

Python SDK (hyperlight_sandbox)

sandbox.register_credential(
    id: str,
    *,
    target: str,
    header: str = "Authorization",
    prefix: str = "Bearer ",
    resolver: Callable[[], str],   # invoked per request, must be fast + thread-safe
)

The Python callable is invoked synchronously from the WASI HTTP dispatch
path on every credentialed request. Exceptions are mapped to a redacted
host-side error containing only the exception type name — the message
body is dropped before crossing the boundary.

Guest Python helper (hyperlight.attach_credential, plus a credential=
kwarg on the existing http_get / http_post wrappers) handles the WIT
attach call for guest scripts.

Backend coverage

A backend is the guest execution engine that runs inside the sandbox
and dispatches outgoing HTTP. The credential injection is implemented in
the host-side WASI HTTP outgoing-handler that each backend uses.

Backend	Registry plumbed	attach honoured	Header injected
Wasm (Wasm)	yes	yes	yes
JavaScript	accepted, ignored (parameter prefixed _)	no	no

SDK coverage

An SDK is a language-side binding that exposes
Sandbox::register_credential (and the resolver shape) to host
application code. All SDKs target the Rust core API.

SDK	register_credential exposed	Resolver kind	Notes
Rust core (hyperlight_sandbox)	yes	ResolverFn callback + with_static_resolver helper	Native API; everything else binds to this.
Python	yes	Python Callable[[], str]	Exceptions are forwarded as the exception type name only — the message body is dropped before crossing the boundary.
.NET	no	—	No FFI binding yet — see Out of scope for the delegate-marshalling design considerations.

Build & CI

• .cargo/config.toml at the repo root sets WIT_WORLD for every
  workspace cargo invocation. Without it hyperlight_wasm_runtime
  (a transitive dep) falls back to the legacy flatbuffer ABI while our
  crate builds against the component-model ABI, producing the runtime
  error "Host function vector parameter missing length" on sandbox
  start. just recipes already exported it; this covers bare cargo and
  IDE invocations. A previous, redundant .cargo/config.toml under
  src/wasm_sandbox/ that shadowed the workspace one is also removed.
• CI: "Check WIT artifact is in sync with .wit source" regenerates
  sandbox-world.wasm from hyperlight-sandbox.wit and fails the build
  on git diff. The compiled artifact is consumed by transitive deps
  before our own build scripts run, so it must live in git — this catches
  silent drift between the source and the committed artifact.

Out of scope (explicit follow-ups)

• Async resolver path. The callback is currently sync Fn() -> Result<String, String>
  and runs on the dispatch thread. Production resolvers
  (IMDS, OAuth refresh, Key Vault) need async + caching/refresh; for now
  caching is delegated to the resolver implementer. A future change can
  introduce an async variant without breaking the sync surface.
• Built-in resolver implementations. No IMDS / Key Vault / OAuth
  resolvers ship in this PR — only the callback hook. Those will land as
  separate, opt-in helpers (likely in their own crate) once the async
  story is decided.
• JavaScript backend integration. The JS backend accepts the
  registry parameter but ignores it; attach is not honoured on the JS
  dispatch path. Needs the same wiring as the Wasm backend.
• .NET SDK binding for register_credential. Python is done; .NET
  has no FFI surface for it yet. A faithful binding has to marshal a C#
  delegate across the C-ABI as the resolver callback, keep a GC root on
  the Func<string> for the sandbox's lifetime, and map any .NET
  exception thrown from the delegate back to Rust as the redacted
  Err(String) — without letting the exception message ride across the
  boundary. A constrained first cut (FFI accepting only a static token,
  mapped onto CredentialEntry::with_static_resolver) is feasible in
  isolation, but is deferred so the .NET surface can be designed around
  the callback shape from day one rather than around a static-only stub
  that would later need a breaking rename.
• Stdout/stderr canary sweep. resolver_failure_surfaces_as_error
  asserts the failure diagnostic does not leak, and
  isolated_registries_across_sandboxes proves cross-sandbox isolation,
  but there is no positive test that runs a guest with a known sentinel
  token value and scans stdout / stderr / every error payload to
  assert the sentinel string is absent from every guest-visible
  output.

[jsturtevant]

I really like this idea. There was some discussion on a wasi version similar to this in WebAssembly/wasi-config#16.

The wasmcloud folks have thought this secret thing through a bit and use a similar approach with resources. I think something like what they have till probably end up in the wasi specs eventually. (I actually thought it already made it there but hasn't yet)

This is very specific to the HTTP but i could see something like this being more generically usable. Do you think we could use something like they did or do we need to attach it specifically to the http request? My concern would be that it limits other use cases.