ms-tau-sdk 1.4.0.dev28__tar.gz → 2.0.0.dev29__tar.gz

{ms_tau_sdk-1.4.0.dev28 → ms_tau_sdk-2.0.0.dev29}/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 2.0.0 — 2026-10-05
+
+- `create_app()` installs request identity, so a hosted Agent starts on a platform launcher that
+  requires it. The application declares it in `app.state.mainsequence_request_identity`:
+  `{"installed": True, "mode": "assertion", "public_ingress": ()}` when Main Sequence hosts the
+  runtime and `"mode": "local"` otherwise. Hosted means `MAINSEQUENCE_CALLER_AUTH_MODE=assertion`
+  or any of `APP_NAME`, `FASTAPI_PUBLIC_BASE_URL`, `MAINSEQUENCE_CALLER_ASSERTION_ISSUER` or
+  `MAINSEQUENCE_CALLER_ASSERTION_JWKS_URL` set, the launcher's own rule. A hosted runtime admits a
+  request only with the platform's signed assertion in `X-MainSequence-Caller-Assertion`: a
+  platform assertion on `/internal/*`, a caller assertion on every other route, `/health`,
+  `/ready` and `/version` included. It verifies the Ed25519 signature against the key set at
+  `MAINSEQUENCE_CALLER_ASSERTION_JWKS_URL`, refreshed once for an unknown `kid`, plus the exact
+  type, the exact claim set, the issuer, the release in `APP_NAME`, the Environment in
+  `MAINSEQUENCE_ORGANIZATION_ENVIRONMENT_UID`, and a lifetime of at most 300 seconds. A missing,
+  invalid, duplicated or wrong-kind assertion gets 401, and a key set that cannot be fetched gets
+  503. The runtime no longer takes a caller from `X-User-UID` in hosted mode: a user turn is
+  stamped with the verified `sub`, while Agent-caller provenance still comes from the gateway's
+  `X-Caller-*` headers. Handlers read the verified caller from `request.state.user`. A hosted
+  configuration that lacks a setting fails at `create_app()` and names it, and local mode refuses
+  to start with the hosting settings. Outside hosting nothing changes. The SDK now depends directly
+  on PyJWT (`crypto`) and `cryptography`, and still not on `mainsequence`. Upgrade note: callers of
+  a hosted runtime must go through the platform, which forwards the assertion, and platform probes
+  use the launcher's own endpoints. See ADR 0019
+  ([#59](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/59)).
+- A hosted runtime lets only a session's owner or an Organization admin address that session. The
+  owner is the User the platform recorded as the session's `created_by_user_uid`, compared with the
+  verified caller; an Organization admin is a caller whose assertion says `is_organization_admin`.
+  Anyone else gets 403 before the runtime acts, on chat, the session model, session cancellation,
+  A2A Message send and stream, Task get, cancel, subscribe and list, and the extended Agent Card,
+  over REST and JSON-RPC alike. A Task list without `contextId` returns only Tasks of sessions the
+  caller may address. The platform's own `/internal/*` calls are not subject to the check, and
+  local mode keeps its own owner scope. See ADR 0019
+  ([#60](https://github.com/mainsequence-sdk/ms-tau-sdk/issues/60)).
+
 ## 1.4.0 — 2026-10-05
 
 - A managed runtime can prove its runtime credential with a projected workload identity token

{ms_tau_sdk-1.4.0.dev28 → ms_tau_sdk-2.0.0.dev29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ms-tau-sdk
-Version: 1.4.0.dev28
+Version: 2.0.0.dev29
 Summary: Workspace-bound Tau application primitives for Main Sequence projects
 Project-URL: Changelog, https://github.com/mainsequence-sdk/ms-tau-sdk/blob/development/CHANGELOG.md
 Project-URL: Documentation, https://github.com/mainsequence-sdk/ms-tau-sdk/tree/development/docs
@@ -14,12 +14,14 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.13
 Requires-Dist: anyio>=4.10
 Requires-Dist: concurrent-log-handler<1,>=0.9.28
+Requires-Dist: cryptography>=42
 Requires-Dist: fastapi>=0.116
 Requires-Dist: httpx>=0.28
 Requires-Dist: jsonschema<5,>=4.25
 Requires-Dist: mcp<2,>=1.27
 Requires-Dist: pydantic-settings>=2.10
 Requires-Dist: pydantic>=2.11
+Requires-Dist: pyjwt[crypto]<3,>=2.10.1
 Requires-Dist: python-multipart>=0.0.20
 Requires-Dist: structlog<27,>=26.1
 Requires-Dist: tau-ai==0.4.2
@@ -121,6 +123,14 @@ from ms_tau_sdk import create_app
 app = create_app()
 ```
 
+When Main Sequence hosts the runtime, `create_app()` admits a request only with the platform's
+signed assertion in `X-MainSequence-Caller-Assertion`, never on gateway identity headers, and lets
+only a session's owner or an Organization admin address that session. It declares this request
+identity to the platform launcher in `app.state.mainsequence_request_identity`; the launcher serves
+only an application that declares it, so serve the application `create_app()` returns. Outside
+hosting, requests are handled as before. See
+[request identity](docs/reference/runtime-contract.md#request-identity).
+
 Job-hosted batch execution is an [accepted design](docs/adrs/0015-job-hosted-batch-execution.md)
 with implementation pending. It will run this SDK's configured Tau composition for one assignment
 inside a project Job, close it, and exit without starting Uvicorn. The Job continues to own its

{ms_tau_sdk-1.4.0.dev28 → ms_tau_sdk-2.0.0.dev29}/README.md

@@ -90,6 +90,14 @@ from ms_tau_sdk import create_app
 app = create_app()
 ```
 
+When Main Sequence hosts the runtime, `create_app()` admits a request only with the platform's
+signed assertion in `X-MainSequence-Caller-Assertion`, never on gateway identity headers, and lets
+only a session's owner or an Organization admin address that session. It declares this request
+identity to the platform launcher in `app.state.mainsequence_request_identity`; the launcher serves
+only an application that declares it, so serve the application `create_app()` returns. Outside
+hosting, requests are handled as before. See
+[request identity](docs/reference/runtime-contract.md#request-identity).
+
 Job-hosted batch execution is an [accepted design](docs/adrs/0015-job-hosted-batch-execution.md)
 with implementation pending. It will run this SDK's configured Tau composition for one assignment
 inside a project Job, close it, and exit without starting Uvicorn. The Job continues to own its

{ms_tau_sdk-1.4.0.dev28 → ms_tau_sdk-2.0.0.dev29}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ms-tau-sdk"
-version = "1.4.0.dev28"
+version = "2.0.0.dev29"
 description = "Workspace-bound Tau application primitives for Main Sequence projects"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -18,12 +18,14 @@ classifiers = [
 dependencies = [
   "anyio>=4.10",
   "concurrent-log-handler>=0.9.28,<1",
+  "cryptography>=42",
   "fastapi>=0.116",
   "httpx>=0.28",
   "jsonschema>=4.25,<5",
   "mcp>=1.27,<2",
   "pydantic>=2.11",
   "pydantic-settings>=2.10",
+  "pyjwt[crypto]>=2.10.1,<3",
   "python-multipart>=0.0.20",
   "structlog>=26.1,<27",
   "tau-ai==0.4.2",

{ms_tau_sdk-1.4.0.dev28 → ms_tau_sdk-2.0.0.dev29}/src/ms_tau_sdk/agent_skills/tau_a2a_runtime_adapter/SKILL.md

@@ -25,6 +25,9 @@ The SDK owns:
 - preserving each tool's canonical name and metadata through host normalization;
 - privately attaching active caller-session proof when a tool advertises
   `mainsequence.ai/requires-caller-session-proof/v1: true`;
+- verifying the platform's signed caller or platform assertion on every inbound request of a
+  hosted runtime, and admitting a request to a session or its Tasks only for the session's owner
+  or an Organization admin;
 - translating inbound A2A requests into the shared TAU runtime; and
 - translating runtime events and results into validated A2A responses.
 

{ms_tau_sdk-1.4.0.dev28 → ms_tau_sdk-2.0.0.dev29}/src/ms_tau_sdk/agent_skills/tau_local_development/SKILL.md

@@ -35,6 +35,10 @@ The SDK looks for the CLI in `MAINSEQUENCE_CLI`, then beside the Python interpre
 CLI. Do not add token lines to `.env`. A pair found there still works, but it is deprecated and
 startup logs a warning. `mainsequence refresh-token` run in that directory removes the lines.
 
+Do not set `APP_NAME`, `FASTAPI_PUBLIC_BASE_URL`, `MAINSEQUENCE_CALLER_AUTH_MODE=assertion`, or the
+`MAINSEQUENCE_CALLER_ASSERTION_*` variables. The platform sets them when it hosts a runtime, and
+local mode refuses to start with them.
+
 Set `MAINSEQUENCE_ENDPOINT` only for a non-default platform endpoint. The CLI session must be for
 the same endpoint. Local mode binds to `127.0.0.1:8787` by default. Treat an explicit public bind
 as privileged exposure: each accepted request can use the authenticated user's live Main Sequence

{ms_tau_sdk-1.4.0.dev28 → ms_tau_sdk-2.0.0.dev29}/src/ms_tau_sdk/agent_skills/tau_repository_integration/SKILL.md

@@ -44,6 +44,20 @@ Both paths construct the same application. The project owns the dependency lock,
 deployable artifact, system packages, and any surrounding ASGI composition. There is no separate
 TAU image, overlay, or SDK-owned deployment.
 
+`create_app()` installs the runtime's request identity. When Main Sequence hosts the runtime, the
+application admits only requests that carry the platform's signed assertion, lets only a session's
+owner or an Organization admin address that session, and declares all this in
+`app.state.mainsequence_request_identity`. The platform launcher serves an application only with
+that declaration, read from the object it serves. Therefore:
+
+- export the object `create_app()` returns as the module's `app`. An application that mounts it
+  inside another one declares nothing, and the launcher refuses it;
+- do not add middleware or routes that take the caller from `X-User-UID` or other gateway headers,
+  and do not install a second request-identity integration; and
+- do not set `APP_NAME`, `FASTAPI_PUBLIC_BASE_URL`, or the `MAINSEQUENCE_CALLER_*` variables in the
+  repository. The platform sets them when it hosts the runtime, and local mode refuses to start
+  with them.
+
 ## Job-hosted batch execution
 
 ADR 0015 accepts a Python batch entry point, but it is **not implemented in this SDK version**.
@@ -106,7 +120,11 @@ When an ASGI shim exists, also import it without starting a second application i
 
 ```bash
 uv run python -c "from api.tau.main import app; print(type(app).__name__)"
+uv run python -c "from api.tau.main import app; print(app.state.mainsequence_request_identity)"
 ```
 
+The second command prints `{'installed': True, 'mode': 'local', 'public_ingress': ()}` outside
+hosting.
+
 Do not require the `mainsequence` Python distribution in the TAU dependency graph. Authentication
 and Main Sequence transport are implemented directly by `ms-tau-sdk`.

{ms_tau_sdk-1.4.0.dev28 → ms_tau_sdk-2.0.0.dev29}/src/ms_tau_sdk/api/a2a.py

@@ -70,6 +70,12 @@ from ms_tau_sdk.runtime.task_context import (
 from ms_tau_sdk.settings import TauSDKSettings
 
 from .dependencies import backend, runtime_manager, settings
+from .request_identity import (
+    SessionAccessDeniedError,
+    require_session_access,
+    sessions_the_caller_may_address,
+    verified_user_uid,
+)
 
 router = APIRouter()
 BackendDep = Annotated[MainSequenceClient, Depends(backend)]
@@ -471,7 +477,31 @@ def _a2a_turn_provenance(
             "actorKind": "agent",
             "actorUid": f"local-a2a-client-{config.workspace_digest}",
         }
-    return turn_provenance_from_request("a2a", request.headers)
+    return turn_provenance_from_request(
+        "a2a",
+        request.headers,
+        verified_user_uid=verified_user_uid(config),
+    )
+
+
+def _requested_context_id(body: dict[str, Any]) -> str:
+    """Return the session a Message request names, before any of its parts is prepared."""
+
+    message = body.get("message")
+    return str(message.get("contextId") or "").strip() if isinstance(message, dict) else ""
+
+
+async def _require_task_session_access(
+    client: MainSequenceClient,
+    task: AgentTask,
+    *,
+    checked: str = "",
+) -> None:
+    """Admit the request to the session of ``task`` unless that session was already checked."""
+
+    session_uid = task.agent_session_uid or task.context_id
+    if not session_uid or session_uid != checked:
+        await require_session_access(client, session_uid)
 
 
 def _output_contract(body: dict[str, Any]) -> StrictJsonContract:
@@ -2204,6 +2234,9 @@ async def message_send(
         provenance = _a2a_turn_provenance(config, request)
     except CallerIdentityError as error:
         return _caller_identity_rejection(request, error)  # type: ignore[return-value]
+    requested_context_id = _requested_context_id(body)
+    if requested_context_id:
+        await require_session_access(client, requested_context_id)
     message, prompt = _request_parts(body, config)
     history_length = _body_history_length(body)
     _bind_a2a_context(
@@ -2233,6 +2266,7 @@ async def message_send(
                 detail="A Task continuation requires configuration.responseKind 'task'",
             )
         existing_task = await client.get_task_by_protocol_id(continuation_task_id)
+        await _require_task_session_access(client, existing_task, checked=requested_context_id)
         continued_message = _task_message_for_backend(
             message,
             context_id=existing_task.context_id,
@@ -2300,6 +2334,8 @@ async def message_send(
             )
             task = await _task_with_history(client, task, history_length=history_length)
             return {"task": _task_payload(task, history_length=history_length)}
+        # An existing Task with this ID is answered only to a caller who may address its session.
+        await _require_task_session_access(client, task, checked=requested_context_id)
         if config.local_mode and task.status == "submitted":
             recovered_prompt, recovered_contract, recovered_provenance = (
                 _recovery_execution_contract(task, config)
@@ -2367,6 +2403,9 @@ async def message_stream(
         a2a_extensions=a2a_extensions,
         streaming=True,
     )
+    requested_context_id = _requested_context_id(body)
+    if requested_context_id:
+        await require_session_access(client, requested_context_id)
     message, prompt = _request_parts(body, config)
     history_length = _body_history_length(body)
     _bind_a2a_context(
@@ -2389,6 +2428,7 @@ async def message_stream(
     )
     task = creation.task
     if not creation.created:
+        await _require_task_session_access(client, task, checked=requested_context_id)
         if config.local_mode and task.status == "submitted":
             recovered_prompt, recovered_contract, recovered_provenance = (
                 _recovery_execution_contract(task, config)
@@ -2428,10 +2468,22 @@ async def list_tasks(
     historyLength: int | None = Query(default=None, ge=0),
 ) -> dict[str, Any]:
     history_length = _history_length(historyLength)
+    if contextId:
+        await require_session_access(client, contextId)
     tasks = await client.list_tasks(
         context_id=contextId or "",
         history_length=history_length,
     )
+    if not contextId:
+        # A list across sessions keeps only the Tasks of sessions the caller may address.
+        visible = await sessions_the_caller_may_address(
+            client,
+            (task.agent_session_uid or task.context_id for task in tasks),
+        )
+        if visible is not None:
+            tasks = [
+                task for task in tasks if (task.agent_session_uid or task.context_id) in visible
+            ]
     return {"tasks": [_task_payload(task, history_length=history_length) for task in tasks]}
 
 
@@ -2442,6 +2494,7 @@ async def cancel_task(
     manager: RuntimeManagerDep,
 ) -> dict[str, Any]:
     task = await client.get_task_by_protocol_id(task_id)
+    await _require_task_session_access(client, task)
     await manager.cancel(task.context_id)
     return {"task": _task_payload(await client.cancel_task(task.uid))}
 
@@ -2454,6 +2507,7 @@ async def subscribe_task(
     after_sequence: int | None = Query(default=None, alias="afterSequence", ge=0),
 ) -> StreamingResponse | JSONResponse:
     snapshot = await client.get_task_snapshot_by_protocol_id(task_id)
+    await _require_task_session_access(client, snapshot.task)
     if snapshot.task.status in TERMINAL:
         return _unsupported_operation_rest_error(
             "SubscribeToTask is unavailable for a terminal Task; use GetTask."
@@ -2474,6 +2528,7 @@ async def get_task(
 ) -> dict[str, Any]:
     history_length = _history_length(historyLength)
     task = await client.get_task_by_protocol_id(task_id, history_length=history_length)
+    await _require_task_session_access(client, task)
     return {"task": _task_payload(task, history_length=history_length)}
 
 
@@ -2513,6 +2568,7 @@ async def extended_agent_card(
     resolved_uid = agent_session_uid or session_uid or context_id
     if not resolved_uid:
         raise HTTPException(status_code=400, detail="agent_session_uid is required")
+    await require_session_access(client, resolved_uid)
     envelope = await client.get_agent_card(resolved_uid)
     payload = envelope.model_dump(mode="json")
     payload["agent_card"] = _effective_agent_card(envelope.agent_card)
@@ -2590,6 +2646,9 @@ async def json_rpc(
                 a2a_extensions=a2a_extensions,
                 streaming=True,
             )
+            requested_context_id = _requested_context_id(params)
+            if requested_context_id:
+                await require_session_access(client, requested_context_id)
             message, prompt = _request_parts(params, config)
             history_length = _body_history_length(params)
             _bind_a2a_context(
@@ -2613,6 +2672,7 @@ async def json_rpc(
             )
             task = creation.task
             if not creation.created:
+                await _require_task_session_access(client, task, checked=requested_context_id)
                 if config.local_mode and task.status == "submitted":
                     recovered_prompt, recovered_contract, recovered_provenance = (
                         _recovery_execution_contract(task, config)
@@ -2669,6 +2729,7 @@ async def json_rpc(
             )
         elif method in {"SubscribeToTask", "tasks/subscribe"}:
             snapshot = await client.get_task_snapshot_by_protocol_id(task_id())
+            await _require_task_session_access(client, snapshot.task)
             if snapshot.task.status in TERMINAL:
                 return _unsupported_operation_json_rpc_error(
                     request_id,
@@ -2698,6 +2759,9 @@ async def json_rpc(
                 "error": {"code": -32601, "message": "Method not found"},
             }
         return {"jsonrpc": "2.0", "id": request_id, "result": result}
+    except SessionAccessDeniedError:
+        # Refused access to a session is answered as HTTP 403 on every transport.
+        raise
     except HTTPException as error:
         return {
             "jsonrpc": "2.0",

{ms_tau_sdk-1.4.0.dev28 → ms_tau_sdk-2.0.0.dev29}/src/ms_tau_sdk/api/chat.py

@@ -22,6 +22,7 @@ from ms_tau_sdk.runtime.provenance import (
 
 from .dependencies import runtime_manager
 from .models import ChatRequest
+from .request_identity import require_session_access, verified_user_uid
 
 router = APIRouter(prefix="/api")
 RuntimeManagerDep = Annotated[SessionRuntimeManager, Depends(runtime_manager)]
@@ -61,7 +62,11 @@ async def chat(
         }
     else:
         try:
-            provenance = turn_provenance_from_request("chat", request.headers)
+            provenance = turn_provenance_from_request(
+                "chat",
+                request.headers,
+                verified_user_uid=verified_user_uid(manager.settings),
+            )
         except CallerIdentityError as error:
             logger.warning(
                 "turn.caller_identity_rejected",
@@ -77,6 +82,8 @@ async def chat(
         session_uid = manager.settings.local_session_uid(body.session_uid)
     elif body.session_uid:
         session_uid = body.session_uid
+        if manager.settings.request_identity_mode == "assertion":
+            await require_session_access(manager.backend, session_uid)
     else:
         raise HTTPException(status_code=422, detail="sessionUid is required")
     try:

ms_tau_sdk-2.0.0.dev29/src/ms_tau_sdk/api/request_identity.py

@@ -0,0 +1,284 @@
+"""Request identity: who calls the runtime, and which sessions that caller may address.
+
+``create_app()`` declares request identity for the platform launcher in
+``app.state.mainsequence_request_identity``. In hosted mode
+(``TauSDKSettings.request_identity_mode == "assertion"``) it also installs
+``RequestIdentityMiddleware``, which admits a request only with the platform's signed assertion of
+the kind its route requires: a platform assertion on ``/internal/*``, a caller assertion on every
+other route. Handlers read the verified caller with ``current_caller()``, or from
+``request.state.user`` and ``request.state.user_uid``.
+
+A request that addresses an existing session must also come from the session's owner or from an
+Organization admin; see ``require_session_access()``. Outside hosted mode nothing here changes how
+requests are handled.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from contextvars import ContextVar
+
+import structlog
+from fastapi import FastAPI, HTTPException
+from starlette.responses import JSONResponse
+from starlette.types import ASGIApp, Receive, Scope, Send
+from starlette.websockets import WebSocketClose
+
+from ms_tau_sdk.backend.assertions import (
+    ASSERTION_HEADER,
+    AssertionKeysUnavailableError,
+    AssertionKind,
+    AssertionVerifier,
+    InvalidAssertionError,
+    VerifiedCaller,
+)
+from ms_tau_sdk.backend.client import MainSequenceClient
+from ms_tau_sdk.backend.models import AgentSession
+from ms_tau_sdk.errors import SessionNotFoundError
+from ms_tau_sdk.logging import bind_request_identity_log_fields
+from ms_tau_sdk.runtime.provenance import CallerIdentityError
+from ms_tau_sdk.settings import TauSDKSettings
+
+logger = structlog.get_logger(__name__)
+
+# The platform launcher reads this declaration from the application state before it serves the
+# application. Its name and keys are the launcher's.
+REQUEST_IDENTITY_STATE_ATTRIBUTE = "mainsequence_request_identity"
+INTERNAL_ROUTE_PREFIX = "/internal"
+_ASSERTION_HEADER_NAME = ASSERTION_HEADER.lower().encode("latin-1")
+_REJECTION_DETAIL: dict[AssertionKind, str] = {
+    "caller": "A valid caller assertion is required.",
+    "platform": "A valid platform assertion is required.",
+}
+_UNAVAILABLE_DETAIL = "Caller authentication is unavailable."
+SESSION_ACCESS_DENIED_DETAIL = (
+    "Only the session's owner or an Organization admin can address this session."
+)
+
+_current_caller: ContextVar[VerifiedCaller | None] = ContextVar(
+    "ms_tau_sdk_verified_caller",
+    default=None,
+)
+
+
+class SessionAccessDeniedError(HTTPException):
+    """A verified caller addressed a session that it neither owns nor administers."""
+
+    def __init__(self) -> None:
+        super().__init__(status_code=403, detail=SESSION_ACCESS_DENIED_DETAIL)
+
+
+def current_caller() -> VerifiedCaller | None:
+    """Return the caller that the current request's verified caller assertion names.
+
+    It is None outside hosted mode and on the platform's own calls to ``/internal/*``.
+    """
+
+    return _current_caller.get()
+
+
+def verified_user_uid(settings: TauSDKSettings) -> str | None:
+    """Return the verified caller's User UID in hosted mode, and None otherwise.
+
+    In hosted mode a request without a verified caller raises ``CallerIdentityError``: the
+    caller is never taken from a header instead.
+    """
+
+    if settings.request_identity_mode != "assertion":
+        return None
+    caller = current_caller()
+    if caller is None:
+        raise CallerIdentityError((ASSERTION_HEADER,))
+    return caller.uid
+
+
+async def require_session_access(
+    client: MainSequenceClient,
+    session_uid: str,
+) -> AgentSession | None:
+    """Admit the current request to ``session_uid`` only for its owner or an Organization admin.
+
+    The owner is the User the platform recorded as the session's creator,
+    ``created_by_user_uid``. The check applies in hosted mode only and raises
+    ``SessionAccessDeniedError`` (403). It returns the session when it had to read it.
+    """
+
+    if client.settings.request_identity_mode != "assertion":
+        return None
+    caller = current_caller()
+    if caller is None or not session_uid:
+        raise SessionAccessDeniedError()
+    if caller.is_organization_admin:
+        return None
+    session = await client.get_session(session_uid)
+    if session.created_by_user_uid != caller.uid:
+        raise SessionAccessDeniedError()
+    return session
+
+
+async def sessions_the_caller_may_address(
+    client: MainSequenceClient,
+    session_uids: Iterable[str],
+) -> set[str] | None:
+    """Return which of ``session_uids`` the current caller may address.
+
+    None means every session: outside hosted mode, or for an Organization admin. A session that
+    no longer exists is left out.
+    """
+
+    if client.settings.request_identity_mode != "assertion":
+        return None
+    caller = current_caller()
+    if caller is None:
+        return set()
+    if caller.is_organization_admin:
+        return None
+    allowed: set[str] = set()
+    for session_uid in set(session_uids):
+        if not session_uid:
+            continue
+        try:
+            session = await client.get_session(session_uid)
+        except SessionNotFoundError:
+            continue
+        if session.created_by_user_uid == caller.uid:
+            allowed.add(session_uid)
+    return allowed
+
+
+def _route_path(scope: Scope) -> str:
+    """Return the path the router matches, the same way Starlette's routing derives it."""
+
+    path = str(scope.get("path") or "")
+    root_path = str(scope.get("root_path") or "")
+    if root_path and path.startswith(root_path) and path != root_path:
+        if path[len(root_path)] == "/":
+            return path[len(root_path) :]
+    return path
+
+
+def required_assertion(scope: Scope) -> AssertionKind:
+    """Name the assertion a route requires: a platform assertion on ``/internal/*`` only."""
+
+    path = _route_path(scope)
+    internal = path == INTERNAL_ROUTE_PREFIX or path.startswith(INTERNAL_ROUTE_PREFIX + "/")
+    return "platform" if internal else "caller"
+
+
+def _assertion(scope: Scope) -> str:
+    values = [
+        value for name, value in scope.get("headers", ()) if name.lower() == _ASSERTION_HEADER_NAME
+    ]
+    if len(values) > 1:
+        raise InvalidAssertionError("The request carries more than one assertion")
+    token = values[0].decode("latin-1").strip() if values else ""
+    if not token:
+        raise InvalidAssertionError("The request carries no assertion")
+    return token
+
+
+class RequestIdentityMiddleware:
+    """Admit a hosted runtime's requests only with the platform's signed assertion."""
+
+    def __init__(self, app: ASGIApp, *, verifier: AssertionVerifier) -> None:
+        self.app = app
+        self.verifier = verifier
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] not in {"http", "websocket"}:
+            await self.app(scope, receive, send)
+            return
+        state = scope.setdefault("state", {})
+        if scope["type"] == "http" and scope.get("method") == "OPTIONS":
+            state.update(user=None, user_uid=None, auth_outcome="not_applicable")
+            bind_request_identity_log_fields(scope, user_uid=None, auth_outcome="not_applicable")
+            await self.app(scope, receive, send)
+            return
+        kind = required_assertion(scope)
+        try:
+            verified = await self.verifier.verify(_assertion(scope), kind=kind)
+        except AssertionKeysUnavailableError as error:
+            await self._deny(scope, receive, send, kind=kind, status_code=503, reason=str(error))
+            return
+        except InvalidAssertionError as error:
+            await self._deny(scope, receive, send, kind=kind, status_code=401, reason=str(error))
+            return
+        caller = verified.caller
+        user_uid = caller.uid if caller is not None else None
+        state.update(
+            user=caller,
+            user_uid=user_uid,
+            auth_outcome="authenticated",
+            resource_release_uid=self.verifier.resource_release_uid,
+            organization_environment_uid=self.verifier.organization_environment_uid,
+        )
+        bind_request_identity_log_fields(scope, user_uid=user_uid, auth_outcome="authenticated")
+        token = _current_caller.set(caller)
+        try:
+            await self.app(scope, receive, send)
+        finally:
+            _current_caller.reset(token)
+
+    async def _deny(
+        self,
+        scope: Scope,
+        receive: Receive,
+        send: Send,
+        *,
+        kind: AssertionKind,
+        status_code: int,
+        reason: str,
+    ) -> None:
+        outcome = "unavailable" if status_code == 503 else "rejected"
+        scope["state"].update(user=None, user_uid=None, auth_outcome=outcome)
+        bind_request_identity_log_fields(scope, user_uid=None, auth_outcome=outcome)
+        logger.warning(
+            "request_identity.rejected",
+            message="Request identity rejected a request",
+            required_assertion=kind,
+            reason=reason,
+            status_code=status_code,
+        )
+        if scope["type"] == "websocket":
+            await WebSocketClose(code=1013 if status_code == 503 else 1008)(scope, receive, send)
+            return
+        response = JSONResponse(
+            status_code=status_code,
+            content={
+                "detail": _UNAVAILABLE_DETAIL if status_code == 503 else _REJECTION_DETAIL[kind]
+            },
+            headers={"Cache-Control": "no-store"},
+        )
+        await response(scope, receive, send)
+
+
+def install_request_identity(app: FastAPI, settings: TauSDKSettings) -> None:
+    """Declare request identity for the platform launcher and, when hosted, enforce it.
+
+    Call it before any other middleware is added, so that it is the innermost one.
+    """
+
+    mode = settings.request_identity_mode
+    if mode == "assertion":
+        app.add_middleware(
+            RequestIdentityMiddleware,
+            verifier=AssertionVerifier.from_settings(settings),
+        )
+    setattr(
+        app.state,
+        REQUEST_IDENTITY_STATE_ATTRIBUTE,
+        {"installed": True, "mode": mode, "public_ingress": ()},
+    )
+
+
+__all__ = [
+    "REQUEST_IDENTITY_STATE_ATTRIBUTE",
+    "RequestIdentityMiddleware",
+    "SessionAccessDeniedError",
+    "current_caller",
+    "install_request_identity",
+    "require_session_access",
+    "required_assertion",
+    "sessions_the_caller_may_address",
+    "verified_user_uid",
+]