Repository navigation
feat(environment): sign episode tokens for Environment Server tool grants #5346
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| # SPDX-License-Identifier: Apache-2.0 | ||
|
|
||
| """Tokens that let an agent call one episode's tools on an Environment Server.""" | ||
|
|
||
| import hmac | ||
| import os | ||
| import secrets | ||
| from dataclasses import dataclass | ||
|
|
||
| from itsdangerous import BadData, URLSafeSerializer | ||
| from pydantic import ValidationError | ||
|
|
||
| from nemo_gym.core.episode_types import EpisodeId | ||
|
|
||
|
|
||
| # The header that carries an episode token on a direct HTTP tool call. | ||
| EPISODE_TOKEN_HEADER = "X-NeMo-Gym-Episode-Token" | ||
| # Namespaces the signature, so an episode token cannot pass for another token signed with the same key. | ||
| _EPISODE_TOKEN_SALT = "nemo-gym-episode-token" | ||
| # The signing secret of this server run. Workers inherit it from the main process. | ||
| EPISODE_TOKEN_SECRET_ENV = "NEMO_GYM_EPISODE_TOKEN_SECRET" | ||
|
|
||
|
|
||
| def episode_token_secret() -> str: | ||
| """The random secret that signs this server run's episode tokens. | ||
|
|
||
| The first call in a process without the secret makes one and sets it in ``EPISODE_TOKEN_SECRET_ENV``. A | ||
| multi-worker server builds its server object in the main process before uvicorn starts the workers, so every | ||
| worker inherits the same secret and reads tokens that another worker minted. | ||
| """ | ||
| secret = os.environ.get(EPISODE_TOKEN_SECRET_ENV) | ||
| if not secret: | ||
| secret = os.environ[EPISODE_TOKEN_SECRET_ENV] = secrets.token_urlsafe(32) | ||
| return secret | ||
|
|
||
|
|
||
| @dataclass(frozen=True) | ||
| class EpisodeTokenClaims: | ||
| """The episode a token names, and the nonce that makes the token unguessable.""" | ||
|
|
||
| episode_id: EpisodeId | ||
| nonce: str | ||
|
|
||
| def matches(self, other: "EpisodeTokenClaims") -> bool: | ||
| """Whether ``other`` names the same episode with the same nonce, compared in constant time.""" | ||
| return self.episode_id == other.episode_id and hmac.compare_digest(self.nonce, other.nonce) | ||
|
|
||
|
|
||
| class EpisodeTokens: | ||
| """Mint and read the tokens an Environment Server grants for one episode's tools. | ||
|
|
||
| A rollout ID is predictable (``<task index>-<rollout index>`` unless the caller sets one), so each token | ||
| carries a random nonce. The server accepts a token only while it holds the same claims for that episode | ||
| (``EpisodeTokenClaims.matches``): the nonce is what authenticates a call. The signature, with a random secret | ||
| for each server run (``episode_token_secret``), keeps the claims intact, and lets a worker that does not hold | ||
| the episode read which episode a token names. | ||
| """ | ||
|
|
||
| def __init__(self, secret: str) -> None: | ||
| self._serializer = URLSafeSerializer(secret, salt=_EPISODE_TOKEN_SALT) | ||
|
|
||
| def mint(self, episode_id: EpisodeId) -> tuple[str, EpisodeTokenClaims]: | ||
| """A new token for ``episode_id``, and the claims the server keeps to check it.""" | ||
| claims = EpisodeTokenClaims(episode_id=episode_id, nonce=secrets.token_urlsafe(32)) | ||
| token = self._serializer.dumps({"episode": episode_id.capture_key, "nonce": claims.nonce}) | ||
| return token, claims | ||
|
|
||
| def read(self, token: str) -> EpisodeTokenClaims | None: | ||
| """The claims of a token this server signed, or ``None`` for any other string. It never raises.""" | ||
| try: | ||
| payload = self._serializer.loads(token) | ||
| except BadData: | ||
| # A bad signature, or a valid signature over a payload that does not decode. | ||
| return None | ||
| if not isinstance(payload, dict): | ||
| return None | ||
| capture_key, nonce = payload.get("episode"), payload.get("nonce") | ||
| # A minted nonce is URL-safe ASCII; a non-ASCII one could not be compared in constant time. | ||
| if not isinstance(capture_key, str) or not isinstance(nonce, str) or not nonce or not nonce.isascii(): | ||
| return None | ||
| try: | ||
| episode_id = EpisodeId.from_capture_key(capture_key) | ||
| except (ValueError, ValidationError): | ||
| return None | ||
| return EpisodeTokenClaims(episode_id=episode_id, nonce=nonce) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,113 @@ | ||
| # SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| # SPDX-License-Identifier: Apache-2.0 | ||
|
|
||
| import pytest | ||
| from itsdangerous import URLSafeSerializer | ||
|
|
||
| from nemo_gym.core.episode_types import EpisodeId | ||
| from nemo_gym.server_runtime.base_resources_server import mcp_session_token_serializer | ||
| from nemo_gym.server_runtime.episode_tokens import ( | ||
| _EPISODE_TOKEN_SALT, | ||
| EPISODE_TOKEN_SECRET_ENV, | ||
| EpisodeTokens, | ||
| episode_token_secret, | ||
| ) | ||
|
|
||
|
|
||
| SECRET = "EnvironmentServer___bird_interact" | ||
|
|
||
|
|
||
| def test_a_minted_token_reads_back_as_the_claims_the_server_keeps() -> None: | ||
| tokens = EpisodeTokens(SECRET) | ||
| episode_id = EpisodeId(rollout_id="3-0", attempt=2) | ||
|
|
||
| token, kept = tokens.mint(episode_id) | ||
| read = tokens.read(token) | ||
|
|
||
| assert read is not None | ||
| assert read.episode_id == episode_id | ||
| assert kept.matches(read) | ||
|
|
||
|
|
||
| def test_each_grant_of_one_episode_gets_its_own_nonce() -> None: | ||
| """Re-granting an episode, such as for a retried attempt, retires the earlier token.""" | ||
| tokens = EpisodeTokens(SECRET) | ||
| episode_id = EpisodeId(rollout_id="3-0") | ||
|
|
||
| first_token, _ = tokens.mint(episode_id) | ||
| _, second = tokens.mint(episode_id) | ||
|
|
||
| assert not second.matches(tokens.read(first_token)) | ||
|
|
||
|
|
||
| def test_a_token_for_another_episode_does_not_match() -> None: | ||
| """A neighbor's rollout ID is easy to guess; its nonce is not.""" | ||
| tokens = EpisodeTokens(SECRET) | ||
| _, kept = tokens.mint(EpisodeId(rollout_id="3-0")) | ||
| other_token, _ = tokens.mint(EpisodeId(rollout_id="4-0")) | ||
|
|
||
| assert not kept.matches(tokens.read(other_token)) | ||
|
|
||
|
|
||
| def test_a_forged_token_with_a_guessed_nonce_does_not_match() -> None: | ||
| """Even a signature made with the server's key fails without the episode's nonce.""" | ||
| tokens = EpisodeTokens(SECRET) | ||
| episode_id = EpisodeId(rollout_id="3-0") | ||
| _, kept = tokens.mint(episode_id) | ||
| forged = URLSafeSerializer(SECRET, salt=_EPISODE_TOKEN_SALT).dumps({"episode": "3-0", "nonce": "guess"}) | ||
|
|
||
| read = tokens.read(forged) | ||
|
|
||
| assert read is not None and read.episode_id == episode_id | ||
| assert not kept.matches(read) | ||
|
|
||
|
|
||
| @pytest.mark.parametrize( | ||
| "token", | ||
| [ | ||
| pytest.param("not-a-token", id="garbage"), | ||
| pytest.param(URLSafeSerializer("other-secret", salt=_EPISODE_TOKEN_SALT).dumps({}), id="other-key"), | ||
| pytest.param(mcp_session_token_serializer(SECRET).dumps({"sid": "3-0"}), id="mcp-token-same-key"), | ||
| pytest.param( | ||
| URLSafeSerializer(SECRET, salt=_EPISODE_TOKEN_SALT).dumps({"episode": "3-0"}), id="missing-nonce" | ||
| ), | ||
| pytest.param( | ||
| URLSafeSerializer(SECRET, salt=_EPISODE_TOKEN_SALT).dumps({"episode": "", "nonce": "n"}), | ||
| id="invalid-episode", | ||
| ), | ||
| pytest.param(URLSafeSerializer(SECRET, salt=_EPISODE_TOKEN_SALT).dumps(["3-0", "n"]), id="not-an-object"), | ||
| pytest.param( | ||
| URLSafeSerializer(SECRET, salt=_EPISODE_TOKEN_SALT).make_signer().sign(b"not base64 json!").decode(), | ||
| id="signed-undecodable-payload", | ||
| ), | ||
| pytest.param( | ||
| URLSafeSerializer(SECRET, salt=_EPISODE_TOKEN_SALT).dumps({"episode": "3-0", "nonce": "\u00e9"}), | ||
| id="non-ascii-nonce", | ||
| ), | ||
| ], | ||
| ) | ||
| def test_a_string_this_server_did_not_mint_reads_as_none(token: str) -> None: | ||
| assert EpisodeTokens(SECRET).read(token) is None | ||
|
|
||
|
|
||
| def test_a_tampered_token_reads_as_none() -> None: | ||
| tokens = EpisodeTokens(SECRET) | ||
| token, _ = tokens.mint(EpisodeId(rollout_id="3-0")) | ||
| payload, signature = token.rsplit(".", 1) | ||
|
|
||
| assert tokens.read(f"{payload}.{signature[::-1]}") is None | ||
|
|
||
|
|
||
| def test_the_secret_is_random_for_each_run_and_shared_with_the_workers(monkeypatch: pytest.MonkeyPatch) -> None: | ||
| """The main process makes the secret; a worker started after it inherits the same one from the environment.""" | ||
| monkeypatch.delenv(EPISODE_TOKEN_SECRET_ENV, raising=False) | ||
| main_process = episode_token_secret() | ||
| assert main_process != SECRET and len(main_process) >= 32 | ||
| assert episode_token_secret() == main_process | ||
|
|
||
| token, kept = EpisodeTokens(main_process).mint(EpisodeId(rollout_id="3-0")) | ||
| worker = EpisodeTokens(episode_token_secret()) | ||
| assert kept.matches(worker.read(token)) | ||
|
|
||
| monkeypatch.delenv(EPISODE_TOKEN_SECRET_ENV) | ||
| assert episode_token_secret() != main_process |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.