Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 86 additions & 0 deletions nemo_gym/server_runtime/episode_tokens.py
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
Comment thread
ffrujeri marked this conversation as resolved.
Resolved
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)
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -903,7 +903,7 @@ layers = [
# nothing that runs inside a server may import it
"nemo_gym.server_runtime.supervisor",
# server_runtime/
"nemo_gym.server_runtime._checkpoint : nemo_gym.server_runtime.agent_context : nemo_gym.server_runtime.base_environment_server : nemo_gym.server_runtime.base_resources_server : nemo_gym.server_runtime.base_server : nemo_gym.server_runtime.entrypoint_flags : nemo_gym.server_runtime.mcp_auto_exposure : nemo_gym.server_runtime.ray_support : nemo_gym.server_runtime.registry_server : nemo_gym.server_runtime.request_handling : nemo_gym.server_runtime.runtime_dir : nemo_gym.server_runtime.sandbox_lending : nemo_gym.server_runtime.server_status : nemo_gym.server_runtime.single_agent_turn_types : nemo_gym.server_runtime.tool_access : nemo_gym.server_runtime.testing : nemo_gym.server_runtime.uvicorn_reuse_port : nemo_gym.server_runtime.verifier_observability",
"nemo_gym.server_runtime._checkpoint : nemo_gym.server_runtime.agent_context : nemo_gym.server_runtime.base_environment_server : nemo_gym.server_runtime.base_resources_server : nemo_gym.server_runtime.base_server : nemo_gym.server_runtime.entrypoint_flags : nemo_gym.server_runtime.episode_tokens : nemo_gym.server_runtime.mcp_auto_exposure : nemo_gym.server_runtime.ray_support : nemo_gym.server_runtime.registry_server : nemo_gym.server_runtime.request_handling : nemo_gym.server_runtime.runtime_dir : nemo_gym.server_runtime.sandbox_lending : nemo_gym.server_runtime.server_status : nemo_gym.server_runtime.single_agent_turn_types : nemo_gym.server_runtime.tool_access : nemo_gym.server_runtime.testing : nemo_gym.server_runtime.uvicorn_reuse_port : nemo_gym.server_runtime.verifier_observability",
# artifacts/
"nemo_gym.artifacts",
# metrics/
Expand Down
113 changes: 113 additions & 0 deletions tests/unit_tests/server_runtime/test_episode_tokens.py
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
Loading