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.
• Token names are validated where they are registered and again before interpolation: a name cannot be empty or contain {, } or control characters. The proxy reads a placeholder up to its first }, so a}b would mint the unrelated token a and leave b} as literal text, and a { in a name can open a second placeholder. The interpolation check is what covers updateNetwork, where any name the callback looks up becomes a placeholder without passing through the iam config.
• 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. Lookup checks own keys only, so an unregistered name colliding 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.
• 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.

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, unusable token names (both braces, a smuggled placeholder, a newline, empty) at registration and on the update path, 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 or unusable 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

SDK-320

[changeset-bot]

🦋 Changeset detected

Latest commit: 35062ec

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 how egress auth headers are built and validated client-side for IAM placeholders; mistakes could ship unusable placeholders on update paths, but secrets still stay on the proxy.

Overview
Network rule transform can be a synchronous callback that receives iam.tokens placeholder strings (${e2b.identity.tokens.<name>} on the wire), so workload identity tokens can be referenced in egress headers without the SDK seeing minted values. On Sandbox.create, only names registered in iam.tokens resolve; typos raise InvalidArgumentError / InvalidArgumentException. Static transform objects behave as before.

updateNetwork / update_network runs the same callbacks but cannot validate names against the sandbox’s registered tokens, so any looked-up name becomes a placeholder. Token names are rejected when empty or containing {, }, or control characters, at registration and when interpolating placeholders.

Callbacks must return a plain transform object; promises and wrong return types are rejected. JS uses a proxied iam.tokens map; Python uses IamTokenPlaceholders with the same lookup and membership rules.

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

[github-actions]

Package Artifacts

Built from 42a060b. Download artifacts from this workflow run.

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

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

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

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

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

pip install ./e2b-2.38.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.}