feat(sdk): add defineSandboxProxy helper

[QuiiBz]

This PR adds a new defineSandboxProxy helper in @vercel/sandbox/proxy to integrate network policies forwarding rules easily within a Vercel Function, or any other platform that supports the Web Handlers syntax (Request/Response objects)

We use jose to verify the OIDC token, then extract the metadata (original host, scheme, port, and source team/project/sandbox ids) before calling a user-defined Web Handler. If the request cannot be authorized, we return a 403 by default, but the user can also override this behavior with a separate Web Handler. A new Request is constructed to correspond to the original sandbox request before being proxied by the sandbox firewall

Example usage in a Vercel Function:

export default {
  fetch: defineSandboxProxy(async (request, meta) => {
    // meta contains the original host & source team/project/sandbox ids
    console.log(meta)

    // return a custom response, or proxy upstream:
    return await fetch(request)
  }, (request, error) => {
    // optional, handle any authorization error
    return new Response("Forbidden", { status: 403 })
  })
}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sandbox	Ready	Preview, Comment, Open in v0	May 14, 2026 4:59pm
sandbox-cli	Ready	Preview, Comment, Open in v0	May 14, 2026 4:59pm
sandbox-sdk	Ready	Preview, Comment, Open in v0	May 14, 2026 4:59pm
sandbox-sdk-ai-example	Ready	Preview, Comment, Open in v0	May 14, 2026 4:59pm
workflow-code-runner	Ready	Preview, Comment, Open in v0	May 14, 2026 4:59pm

[valerian-roche]

Can you clarify why we set this value here?

[valerian-roche]

The path of the request is "proxy URL + original path", so this is likely to not match here, no?

[QuiiBz]

Hum I only tested the / case, for example:

• Rule on vercel.com with forwardURL: "https://proxy.vercel.app/proxy", which is the audience of the OIDC token
• I make a request to https://vercel.com from the sandbox
• The function at https://proxy.vercel.app/proxy receives the request, and has an originalUrl of https://proxy.vercel.app/proxy & vercel-forwarded-host of vercel.com

This indeed doesn't handle requests on other paths like https://vercel.com/sandbox, because now the audience would still be https://proxy.vercel.app/proxy but originalUrl would be https://proxy.vercel.app/proxy/sandbox

We could check only the hostname but that defeats the point of having path-defined audiences. The other option is to explicitly require the user to pass in their configured forwardURL into defineSandboxProxy. Thoughts?