mainsequence 9.0.11__tar.gz → 9.0.12.dev51__tar.gz

{mainsequence-9.0.11 → mainsequence-9.0.12.dev51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 9.0.11
+Version: 9.0.12.dev51
 Summary: Main Sequence SDK
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence-9.0.11 → mainsequence-9.0.12.dev51}/agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md

@@ -147,6 +147,13 @@ person, read `User.get_by_uid(uid)`: a workload identity has `identity_type`
 `"workload"`. Caller authentication is not resource authorization; apply the
 endpoint's application policy using the verified user UID.
 
+To list the people, Teams and workloads the caller can see, for example to
+offer sharing candidates, read inside `reads_as_caller()` from
+`mainsequence.server.fastapi`: `User.filter`, `User.get_by_uid`, `Team.filter`
+and `Team.get_by_uid` then answer with the caller's visibility, and workload
+rows carry `managed_by_caller`. Outside a signed HTTP request it raises
+`RequestIdentityError`; it never reads as the application instead.
+
 WebSockets retain the platform's gateway ticket/header contract rather than
 the HTTP Bearer/assertion flow; the getter is available while the authenticated
 connection is active. See the version-matched

mainsequence-9.0.12.dev51/mainsequence/_request_identity.py

@@ -0,0 +1,98 @@
+"""Private lifecycle shared by the request integration and the public user getter."""
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlsplit
+
+CALLER_ASSERTION_HEADER = "X-MainSequence-Caller-Assertion"
+
+
+class RequestIdentityError(RuntimeError):
+    """No authenticated caller is bound to the current request."""
+
+
+@dataclass
+class _RequestScope:
+    user: Any = None
+    active: bool = True
+    # The verified assertion of a hosted HTTP request, kept only so that
+    # reads_as_caller() can present it (ADR-0036, amended for #198).
+    caller_assertion: str | None = field(default=None, repr=False)
+
+
+_current_scope: ContextVar[_RequestScope | None] = ContextVar(
+    "mainsequence_request_identity", default=None
+)
+# The request scope whose caller the directory reads answer as, inside reads_as_caller().
+_caller_reads: ContextVar[_RequestScope | None] = ContextVar(
+    "mainsequence_caller_reads", default=None
+)
+
+
+@contextmanager
+def _request_scope():
+    scope = _RequestScope()
+    token = _current_scope.set(scope)
+    try:
+        yield scope
+    finally:
+        # Copied child-task contexts hold this same frame and must also expire.
+        scope.active = False
+        scope.user = None
+        scope.caller_assertion = None
+        _current_scope.reset(token)
+
+
+def _get_request_identity():
+    scope = _current_scope.get()
+    if scope is None or not scope.active or scope.user is None:
+        raise RequestIdentityError(
+            "No authenticated request user is available. Install request identity "
+            "once in the application and call User.get_logged_user() inside a request."
+        )
+    return scope.user
+
+
+@contextmanager
+def _reads_as_caller():
+    scope = _current_scope.get()
+    if scope is None or not scope.active or scope.user is None:
+        raise RequestIdentityError(
+            "Reading as the caller needs an authenticated request. Install request "
+            "identity once in the application and call reads_as_caller() inside a request."
+        )
+    if scope.caller_assertion is None:
+        raise RequestIdentityError(
+            "This request carries no caller assertion. Reading as the caller needs a "
+            "hosted HTTP request in assertion mode, not local mode or a WebSocket."
+        )
+    token = _caller_reads.set(scope)
+    try:
+        yield
+    finally:
+        _caller_reads.reset(token)
+
+
+def _origin(url: str) -> tuple[str, str | None, int | None]:
+    parts = urlsplit(url)
+    scheme = parts.scheme.lower()
+    return scheme, parts.hostname, parts.port or {"http": 80, "https": 443}.get(scheme)
+
+
+def _caller_read_headers(url: str, endpoint_url: str) -> dict[str, str]:
+    """The header a directory read sends to ``url``: none outside reads_as_caller()."""
+    scope = _caller_reads.get()
+    if scope is None:
+        return {}
+    if not scope.active or scope.caller_assertion is None:
+        raise RequestIdentityError(
+            "The request that reads_as_caller() belongs to has ended; its caller "
+            "assertion is no longer available."
+        )
+    if _origin(url) != _origin(endpoint_url):
+        raise RequestIdentityError(
+            "The caller assertion is sent only to the configured platform endpoint."
+        )
+    return {CALLER_ASSERTION_HEADER: scope.caller_assertion}

{mainsequence-9.0.11 → mainsequence-9.0.12.dev51}/mainsequence/client/base.py

@@ -180,6 +180,11 @@ class BaseObjectOrm:
     def _sdk_owned_query_context(cls, operation: str) -> dict[str, Any]:
         return {}
 
+    @classmethod
+    def _read_request_headers(cls, url: str) -> dict[str, str]:
+        """Headers a filter or detail read adds to its own request to ``url``."""
+        return {}
+
     @classmethod
     def _sdk_owned_create_context(cls, operation: str) -> dict[str, Any]:
         return {}
@@ -540,12 +545,13 @@ class BaseObjectOrm:
 
         while next_url:
             req_payload = {"params": params} if params else {}
+            headers = cls._read_request_headers(next_url)
             r = make_request(
                 s=cls.build_session(),
                 loaders=cls.LOADERS,
                 r_type="GET",
                 url=next_url,
-                payload=req_payload,
+                payload={**req_payload, "headers": headers} if headers else req_payload,
                 time_out=timeout,
             )
             raise_for_response(r, payload=req_payload)
@@ -610,12 +616,16 @@ class BaseObjectOrm:
                 **cls._sdk_owned_query_context(operation),
             }
 
+            payload = {"params": params}  # neede to pass special serializer
+            headers = cls._read_request_headers(detail_url)
+            if headers:
+                payload["headers"] = headers
             r = make_request(
                 s=cls.build_session(),
                 loaders=cls.LOADERS,
                 r_type="GET",
                 url=detail_url,
-                payload={"params": params},  # neede to pass special serializer
+                payload=payload,
                 time_out=timeout,
             )
             raise_for_response(r)

{mainsequence-9.0.11 → mainsequence-9.0.12.dev51}/mainsequence/client/models_user.py

@@ -6,7 +6,11 @@ from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field, StrictBool, field_validator, model_validator
 
-from mainsequence._request_identity import RequestIdentityError, _get_request_identity
+from mainsequence._request_identity import (
+    RequestIdentityError,
+    _caller_read_headers,
+    _get_request_identity,
+)
 from mainsequence.defaults import STANDARD_BACKEND_URL
 
 from .base import (
@@ -336,7 +340,18 @@ class TeamMembershipUpdateResult(BasePydanticModel):
     )
 
 
-class Team(PermissionManagedObjectMixin, BasePydanticModel, UserApiBaseObjectOrm):
+class _CallerDirectoryReadMixin:
+    """Inside ``reads_as_caller()``, ``filter`` and ``get`` reads answer as the
+    request's caller (ADR-0036, amended for #198)."""
+
+    @classmethod
+    def _read_request_headers(cls, url: str) -> dict[str, str]:
+        return _caller_read_headers(url, cls.get_object_url())
+
+
+class Team(
+    _CallerDirectoryReadMixin, PermissionManagedObjectMixin, BasePydanticModel, UserApiBaseObjectOrm
+):
     ENDPOINT: ClassVar[str] = "teams"
     FILTERSET_FIELDS: ClassVar[dict[str, list[str]] | None] = {
         "uid": ["exact", "in"],
@@ -960,7 +975,7 @@ class ShareableAccessState(BasePydanticModel):
     )
 
 
-class User(UserApiBaseObjectOrm, BasePydanticModel):
+class User(_CallerDirectoryReadMixin, UserApiBaseObjectOrm, BasePydanticModel):
     """A platform User: a person, or the workload identity a deployed Job,
     FastAPI release or Agent runs as.
 
@@ -974,6 +989,10 @@ class User(UserApiBaseObjectOrm, BasePydanticModel):
     The reverse direction is ``workload_user_uid`` on ``Job``,
     ``ResourceRelease`` and ``Agent``: the UID of the User that workload runs
     as, to pass to ``User.get_by_uid`` and to sharing calls.
+
+    Inside ``mainsequence.server.fastapi.reads_as_caller()``, ``User.filter``
+    and ``User.get_by_uid`` answer with what the request's caller may see, and
+    workload rows carry ``managed_by_caller``.
     """
 
     # Platform facts, not application authorization policy. None means the
@@ -986,6 +1005,7 @@ class User(UserApiBaseObjectOrm, BasePydanticModel):
         "uid": ["exact", "in"],
         "email": ["exact", "contains", "in"],
         "identity_type": ["exact"],
+        "search": ["exact"],
     }
     FILTER_VALUE_NORMALIZERS: ClassVar[dict[str, str]] = {
         "uid": "uid",
@@ -994,6 +1014,7 @@ class User(UserApiBaseObjectOrm, BasePydanticModel):
         "email__contains": "str",
         "email__in": "str",
         "identity_type": "str",
+        "search": "str",
     }
 
     id: int | None = Field(
@@ -1038,6 +1059,15 @@ class User(UserApiBaseObjectOrm, BasePydanticModel):
         description="UID of the Agent a workload identity belongs to; None otherwise.",
         examples=[None],
     )
+    managed_by_caller: bool | None = Field(
+        None,
+        title="Managed By Caller",
+        description=(
+            "On a workload identity read inside `reads_as_caller()`: whether the "
+            "request's caller manages that workload. None when the row does not carry it."
+        ),
+        examples=[True],
+    )
     profile_picture: str | None = Field(
         None,
         title="Profile Picture URL",

{mainsequence-9.0.11 → mainsequence-9.0.12.dev51}/mainsequence/server/caller_assertions.py

@@ -16,7 +16,8 @@ import requests
 from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
 from jwt import InvalidKeyError, InvalidTokenError
 
-ASSERTION_HEADER = "X-MainSequence-Caller-Assertion"
+from mainsequence._request_identity import CALLER_ASSERTION_HEADER as ASSERTION_HEADER
+
 ASSERTION_TYPE = "mainsequence-caller-assertion+jwt"
 ASSERTION_ALGORITHM = "EdDSA"
 MAX_ASSERTION_SECONDS = 300

{mainsequence-9.0.11 → mainsequence-9.0.12.dev51}/mainsequence/server/fastapi.py

@@ -6,11 +6,12 @@ import asyncio
 import json
 import os
 import re
+from contextlib import contextmanager
 from uuid import UUID
 
 import requests
 
-from mainsequence._request_identity import _request_scope
+from mainsequence._request_identity import _reads_as_caller, _request_scope
 from mainsequence.client.models_user import RequestUserIdentity
 
 from .caller_assertions import (
@@ -220,6 +221,7 @@ class _RequestIdentityMiddleware:
                         )
                         state["resource_release_uid"] = caller.release_uid
                         state["organization_environment_uid"] = caller.environment_uid
+                        context.caller_assertion = assertion
                     else:
                         user = await asyncio.to_thread(_local_user, scope)
                     context.user = user
@@ -267,4 +269,19 @@ def install_request_identity(app):
     )
 
 
-__all__ = ["install_request_identity"]
+@contextmanager
+def reads_as_caller():
+    """Read the directory as the request's caller instead of as the application.
+
+    Inside the block, ``User.filter``, ``User.get_by_uid``, ``Team.filter`` and
+    ``Team.get_by_uid`` present the caller assertion the request arrived with,
+    and the platform answers with what the caller may see. No other call sends
+    it. Raises ``RequestIdentityError`` outside an authenticated request or when
+    the request carries no assertion (local mode, WebSockets); it never reads as
+    the application instead. See ADR-0036.
+    """
+    with _reads_as_caller():
+        yield
+
+
+__all__ = ["install_request_identity", "reads_as_caller"]

{mainsequence-9.0.11 → mainsequence-9.0.12.dev51}/mainsequence.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 9.0.11
+Version: 9.0.12.dev51
 Summary: Main Sequence SDK
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: MIT

{mainsequence-9.0.11 → mainsequence-9.0.12.dev51}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mainsequence"
-version = "9.0.11"
+version = "9.0.12.dev51"
 description = "Main Sequence SDK"
 readme = "README.md"
 requires-python = ">=3.13"

{mainsequence-9.0.11 → mainsequence-9.0.12.dev51}/tests/test_fastapi_request_identity.py

@@ -11,13 +11,14 @@ from cryptography.hazmat.primitives.asymmetric import ed25519
 from fastapi import FastAPI, Request, WebSocket
 from fastapi.testclient import TestClient
 
+import mainsequence.client.base as base_mod
 from mainsequence.client import RequestIdentityError, User
 from mainsequence.server.caller_assertions import (
     ASSERTION_HEADER,
     ASSERTION_TYPE,
     CallerAssertionVerifier,
 )
-from mainsequence.server.fastapi import install_request_identity
+from mainsequence.server.fastapi import install_request_identity, reads_as_caller
 
 USER = str(uuid4())
 OTHER = str(uuid4())
@@ -372,3 +373,142 @@ def test_websocket_invalid_identity_cannot_reach_app(headers, denial_extension):
         assert messages[0]["code"] == 1008
     with pytest.raises(RequestIdentityError):
         User.get_logged_user()
+
+
+class _Page:
+    status_code = 200
+
+    def __init__(self, results=()):
+        self._results = list(results)
+
+    def json(self):
+        return {"results": self._results, "next": None}
+
+
+def test_sync_route_reads_as_its_caller(signed, monkeypatch):
+    token, _, _ = signed
+    proof = token()
+    workload = str(uuid4())
+    sent = []
+
+    def _fake_make_request(*, s, loaders, r_type, url, payload=None, time_out=None):
+        sent.append(payload)
+        row = {
+            "uid": workload,
+            "identity_type": "workload",
+            "is_active": True,
+            "managed_by_caller": True,
+        }
+        return _Page([row])
+
+    monkeypatch.setattr(base_mod, "make_request", _fake_make_request)
+
+    def handler(q: str):
+        with reads_as_caller():
+            rows = User.filter(identity_type="workload", search=q)
+        return [{"uid": row.uid, "managed": row.managed_by_caller} for row in rows]
+
+    with TestClient(app_for(handler, path="/candidates")) as client:
+        response = client.get(
+            "/candidates", params={"q": "prices"}, headers={ASSERTION_HEADER: proof}
+        )
+
+    assert response.json() == [{"uid": workload, "managed": True}]
+    assert sent == [
+        {
+            "params": {"identity_type": "workload", "search": "prices"},
+            "headers": {ASSERTION_HEADER: proof},
+        }
+    ]
+
+
+def test_concurrent_requests_present_their_own_assertions(signed, monkeypatch):
+    from mainsequence.server.fastapi import _RequestIdentityMiddleware
+
+    token, _, verifier = signed
+    proofs = {USER: token(USER), OTHER: token(OTHER)}
+    presented = {USER: [], OTHER: []}
+    entered = 0
+    release = asyncio.Event()
+
+    def _fake_make_request(*, s, loaders, r_type, url, payload=None, time_out=None):
+        presented[User.get_logged_user().uid].append((payload or {}).get("headers"))
+        return _Page()
+
+    monkeypatch.setattr(base_mod, "make_request", _fake_make_request)
+
+    async def application(scope, receive, send):
+        nonlocal entered
+        entered += 1
+        if entered == 2:
+            release.set()
+        await release.wait()
+        with reads_as_caller():
+            User.filter(search="prices")
+            await asyncio.sleep(0)  # the other request reads while this one is inside
+            User.filter(search="prices")
+        User.filter(search="prices")
+        await send({"type": "http.response.start", "status": 200, "headers": []})
+        await send({"type": "http.response.body", "body": b""})
+
+    runtime = _RequestIdentityMiddleware(
+        application, mode="assertion", verifier=verifier, public_ingress=(), routes=()
+    )
+
+    async def run():
+        async def request(user):
+            scope = {
+                "type": "http",
+                "method": "GET",
+                "path": "/",
+                "headers": [(ASSERTION_HEADER.lower().encode(), proofs[user].encode())],
+            }
+
+            async def receive():
+                return {"type": "http.request", "body": b""}
+
+            async def send(message):
+                pass
+
+            await runtime(scope, receive, send)
+
+        await asyncio.gather(request(USER), request(OTHER))
+
+    asyncio.run(run())
+    for user in (USER, OTHER):
+        assert presented[user] == [{ASSERTION_HEADER: proofs[user]}] * 2 + [None]
+
+
+def test_reads_as_caller_needs_a_signed_http_request(monkeypatch):
+    monkeypatch.setenv("MAINSEQUENCE_ENDPOINT", ISSUER)
+    response = Mock(status_code=200)
+    response.json.return_value = {"uid": USER, "username": "local"}
+    monkeypatch.setattr("mainsequence.server.fastapi.requests.get", Mock(return_value=response))
+
+    def handler():
+        with pytest.raises(RequestIdentityError, match="no caller assertion"):
+            with reads_as_caller():
+                pass
+        return {"uid": User.get_logged_user().uid}
+
+    async def ws(websocket: WebSocket):
+        await websocket.accept()
+        with pytest.raises(RequestIdentityError, match="no caller assertion"):
+            with reads_as_caller():
+                pass
+        await websocket.send_json({"uid": User.get_logged_user().uid})
+        await websocket.close()
+
+    app = FastAPI()
+    app.get("/me")(handler)
+    app.websocket("/ws")(ws)
+    install_request_identity(app)
+    client = TestClient(app)
+
+    local = client.get("/me", headers={"Authorization": "Bearer local-token"})
+    assert local.json() == {"uid": USER}
+    with client.websocket_connect("/ws", headers={"X-User-UID": USER}) as connection:
+        assert connection.receive_json() == {"uid": USER}
+    with pytest.raises(RequestIdentityError, match="authenticated request"):
+        with reads_as_caller():
+            pass

mainsequence-9.0.11/mainsequence/_request_identity.py

@@ -1,44 +0,0 @@
-"""Private lifecycle shared by the request integration and the public user getter."""
-
-from contextlib import contextmanager
-from contextvars import ContextVar
-from dataclasses import dataclass
-from typing import Any
-
-
-class RequestIdentityError(RuntimeError):
-    """No authenticated caller is bound to the current request."""
-
-
-@dataclass
-class _RequestScope:
-    user: Any = None
-    active: bool = True
-
-
-_current_scope: ContextVar[_RequestScope | None] = ContextVar(
-    "mainsequence_request_identity", default=None
-)
-
-
-@contextmanager
-def _request_scope():
-    scope = _RequestScope()
-    token = _current_scope.set(scope)
-    try:
-        yield scope
-    finally:
-        # Copied child-task contexts hold this same frame and must also expire.
-        scope.active = False
-        scope.user = None
-        _current_scope.reset(token)
-
-
-def _get_request_identity():
-    scope = _current_scope.get()
-    if scope is None or not scope.active or scope.user is None:
-        raise RequestIdentityError(
-            "No authenticated request user is available. Install request identity "
-            "once in the application and call User.get_logged_user() inside a request."
-        )
-    return scope.user