feat(sdk): resolve iam token placeholders in network transform callbacks

[mishushakov]

Stacked on #1606 (iam-sdk-feature) — merge that one first. This is the second half of SDK-245: it makes the workload tokens registered by Sandbox.create's iam option usable, by letting a network rule's transform be a callback that receives placeholder strings the egress proxy resolves per request.

iam.tokens.aws is the literal string ${e2b.identity.tokens.aws} (the frozen backend spelling — a placeholder can only select a persisted named token, never an inline audience or claim). The SDK never resolves it: the wire payload carries the placeholder and the proxy substitutes a freshly minted JWT-SVID when it forwards the request, so the token value never reaches SDK-side code or the sandbox.

Referencing a name that isn't registered in iam.tokens fails with InvalidArgumentError / InvalidArgumentException listing the names that are — the proxy never turns an unregistered name into a token, so a typo would otherwise surface as a confusing auth failure at the destination. updateNetwork / update_network accepts the same callbacks, but its payload carries no iam config, so token names can't be validated client-side there and any name resolves to its placeholder.

Static transform: { headers } objects keep working unchanged (including hand-written ${e2b.identity.tokens.<name>} strings, which stay the escape hatch for tokens the SDK doesn't know about).

Only { iam } is exposed on the context for now — ${e2b.sandboxId} / ${e2b.teamId} / ${e2b.executionId} from the older prototype are not part of the current backend design, so sandbox can be added later when there is something to resolve.

Usage

import { Sandbox, Secret } from 'e2b'

const sandbox = await Sandbox.create({
  iam: {
    tokens: {
      aws: Secret.iamToken({ audience: 'sts.amazonaws.com', tokenType: 'JWT-SVID' }),
    },
  },
  network: {
    // Only allow egress to hosts that have rules registered.
    allowOut: ({ rules }) => [...rules.keys()],
    rules: {
      'api.internal.example.com': [
        {
          transform: ({ iam }) => ({
            headers: { Authorization: `Bearer ${iam.tokens.aws}` },
          }),
        },
      ],
    },
  },
})

from e2b import Sandbox, Secret

sandbox = Sandbox.create(
    iam={
        "tokens": {
            "aws": Secret.iam_token(audience="sts.amazonaws.com", token_type="JWT-SVID"),
        },
    },
    network={
        "allow_out": lambda ctx: list(ctx.rules.keys()),
        "rules": {
            "api.internal.example.com": [
                {
                    "transform": lambda ctx: {
                        "headers": {"Authorization": f"Bearer {ctx.iam.tokens['aws']}"},
                    },
                },
            ],
        },
    },
)

Both send:

{
  "iam": { "tokens": { "aws": { "audience": "sts.amazonaws.com", "tokenType": "JWT-SVID" } } },
  "network": {
    "allowOut": ["api.internal.example.com"],
    "rules": {
      "api.internal.example.com": [
        { "transform": { "headers": { "Authorization": "Bearer ${e2b.identity.tokens.aws}" } } }
      ]
    }
  }
}

Notes

• allowOut / deny_out selectors run before transforms are resolved, so ctx.rules still hands back the rules you passed — a rule's transform there is the union (object or callback), not the materialized object. The getInfo view keeps its own narrowed SandboxNetworkRuleInfo type.
• Every lookup form on iam.tokens is guarded, not just [name]: Python's map is a Mapping whose __getitem__ owns resolution (so .get('typo') raises instead of returning None), and membership ('aws' in ctx.iam.tokens / 'aws' in iam.tokens) answers "is it registered?" without raising so a callback can branch on it.
• A callback must be synchronous and return a plain transform object; a promise (from an async callback), an array, a Map/Date/class instance, or a missing return value is rejected with an actionable error rather than silently creating a rule with no headers. The awaitable is closed/caught so you don't also get an unawaited-coroutine warning or an unhandled rejection.
• Token lookup checks own keys only, so an unregistered name that collides with an object member (constructor, __proto__) reports as unregistered instead of resolving to a built-in. The four properties the runtime itself reads (toJSON, then, toString, valueOf) still resolve normally, so serializing, awaiting or coercing the map does not trip the guard.

Tests

New payload-level tests: JS tests/sandbox/networkTransform.test.ts (msw), Python tests/shared/sandbox/test_network_transform.py — shared rather than mirrored into the sync and async suites, since they only exercise the shared builders. They cover placeholder resolution, enumerating and membership-testing registered tokens, JSON.stringify of the context not tripping the guard, static transforms staying byte-identical, transform: null, the unregistered-name rejection through both [name] and .get(), the no-iam rejection, non-transform and async return values, and the permissive updateNetwork path.

Verified against production on all three surfaces (JS, sync Python, async Python), where:

1. a static transform carrying Bearer ${e2b.identity.tokens.aws} is accepted by validateNetworkRules and round-trips through getInfo / get_info unchanged;
2. the callback-resolved payload reaches the API and is answered with the expected team-gating error (400: Sandbox IAM workload tokens are not available for your team.), since iam is still feature-flagged;
3. a misspelled token name is rejected client-side before any request is made.

Proxy-side substitution of the placeholder ships separately in belt (EN-1864); until then the header value is forwarded verbatim, which is why there is no end-to-end injection test here.

Part of SDK-245.

[linear-code]

SDK-245

[changeset-bot]

🦋 Changeset detected

Latest commit: 11930bb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
e2b	Minor
@e2b/python-sdk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cursor]

PR Summary

Medium Risk
Changes affect egress header injection and workload-identity wiring; mistakes would show up as auth failures at destinations rather than leaking tokens through the SDK.

Overview
No implementation errors identified in the diff. JS and Python both resolve synchronous transform callbacks at request-build time, wire placeholders instead of token values, validate registered IAM names on sandbox create, and skip that validation on updateNetwork / update_network where no IAM payload is sent.

^{Reviewed by Cursor Bugbot for commit 11930bb. Bugbot is set up for automated code reviews on this repo. Configure here.}

[github-actions]

Package Artifacts

Built from 7fe9a16. Download artifacts from this workflow run.

JS SDK (e2b@2.36.2-network-transform-callback.0):

npm install ./e2b-2.36.2-network-transform-callback.0.tgz

CLI (@e2b/cli@2.16.1-network-transform-callback.0):

npm install ./e2b-cli-2.16.1-network-transform-callback.0.tgz

Python SDK (e2b==2.35.0+network.transform.callback):

pip install ./e2b-2.35.0+network.transform.callback-py3-none-any.whl

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e206170ace

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f0f8f35. Configure here.}