mainsequence 9.0.17.dev60__tar.gz → 9.0.18.dev61__tar.gz

{mainsequence-9.0.17.dev60 → mainsequence-9.0.18.dev61}/PKG-INFO

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

{mainsequence-9.0.17.dev60 → mainsequence-9.0.18.dev61}/agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md

@@ -164,9 +164,16 @@ for the lifecycle and trust contract.
 
 Another application, for example an Agent, can call the API while it works for
 a person: the requester. The platform signs the requester into the caller
-assertion it sends to the API. `User.get_logged_user()` still returns the
-caller, the acting application. `User.get_requester()` returns the requester,
-or `None` when the call is not requester-bound:
+assertion it sends to the API, and the SDK verifies it before the handler runs.
+`User.get_logged_user()` still returns the caller, the acting application.
+`User.get_requester()` returns the requester, the checked delegation, with the
+person's own `uid`, `team_uids` and `is_organization_admin`, or `None` when the
+call carries no delegation. A requester-bound call carries the person's
+ordinary permissions, including administrative ones.
+
+Each handler decides whether it needs a person. One that needs a person fails
+with its own error when there is none; one where the person is optional
+authorizes against the person when present, and against the caller otherwise:
 
 ```python
 from fastapi import HTTPException
@@ -184,41 +191,42 @@ def require_requester() -> RequestUserIdentity:
 @app.get("/team-reports/{team_uid}")
 def team_report(team_uid: str) -> dict[str, str]:
     requester = require_requester()
-    if team_uid not in requester.team_uids:
-        raise HTTPException(status_code=403, detail="The requester is not in this team.")
+    if not (requester.is_organization_admin or team_uid in requester.team_uids):
+        raise HTTPException(status_code=403, detail="The requester cannot read this report.")
     return {"team_uid": team_uid, "requested_by": requester.uid}
+
+
+def acting_identity() -> RequestUserIdentity:
+    """The person on a requester-bound call, the caller on any other; never both."""
+    return User.get_requester() or User.get_logged_user()
 ```
 
-- Authorize a requester-bound call against the requester. The acting
-  application has no rights of its own unless the API's policy grants them.
-- The requester can authorize reads and writes within that person's own
-  member-level permissions. Before a write, check the exact object and action;
-  the example's team-membership check is not a general edit, run, share or
-  delete grant. The getter verifies identity, not operation permission.
-- Fail closed: an operation that needs a person refuses the call when
-  `User.get_requester()` is `None`. Never fall back to the caller's rights.
-- Never read a person's UID from the request body, a header or a query
-  parameter, and never let a caller name whom it acts for. Anyone can write a
-  UID there. Only the signed assertion names the requester, and the SDK has
-  verified that it is addressed to this release.
-- The requester carries the `team_uids` the platform signed, and its
-  `is_organization_admin` is always `False`: a requester's access reaches the
-  API at member level only.
+- Authorize against one identity: the person on a requester-bound call, the
+  caller on any other. Never combine the caller's grants with the person's,
+  and never fall back to the caller's rights when the person may not.
+- Before a write, check the exact object and action; the example's
+  team-membership check is not a general edit, run, share or delete grant. The
+  getter verifies identity, not operation permission.
+- Never parse the assertion, headers or MCP `_meta`, never read a person's UID
+  from the request body, a header or a query parameter, and never let a caller
+  name whom it acts for. Anyone can write a UID there. Only the signed
+  assertion names the requester, and the SDK has verified that it is addressed
+  to this release; an invalid one is rejected with 401 before any handler runs.
 - Inside a requester-bound call, `reads_as_caller()` raises
   `RequestIdentityError`: a receiving application cannot forward its inbound
   requester-bearing assertion to the directory endpoints. Platform-authorized
   Agent delegation is separate and keeps the original person and request time.
-- Hosted Agents never receive Secret values. The platform bounds work to at
-  most 24 hours after the original request and checks access on every call;
-  delegation does not restart that limit. This SDK does not enable platform
-  write endpoints or extend the inbound request scope.
+- The platform bounds work to at most 24 hours after the original request and
+  checks access on every call; delegation does not restart that limit. This
+  SDK does not enable platform endpoints or extend the inbound request scope.
 - A model-driven Agent can be steered by prompt injection. Its writes can
   cause damage within the person's permissions; keep object/action checks and
   any mutation approval required by the application's policy outside model
   claims or tool arguments.
 - Test requester-authorized reads and writes, writes refused for a requester
-  without the necessary grant, and requester-required operations refused
-  without a requester even when the calling Agent has its own grants.
+  without the necessary grant, requester-required operations refused without
+  a requester, and writes the calling Agent may make but the person may not
+  refused on a requester-bound call.
 
 Which applications may act for their requester, what that access covers, and
 what people are told:
@@ -233,12 +241,14 @@ To serve MCP tools from the same application, add the `mcp` extra and call
 after `install_request_identity(app)`, with a stateless FastMCP server that
 returns JSON. Tools authorize with `User.get_logged_user()` and
 `User.get_requester()` exactly like REST handlers; admission to the release
-does not authorize every tool. For a tool invoked by an Agent on a person's
-behalf, check that requester for both reads and writes. Refuse a
-requester-required write when the getter returns `None`, and verify object- and
-action-specific permission before mutation; read access and MCP annotations are not
-write authority. Ordinary non-requester calls retain their own caller policy.
-See
+does not authorize every tool. Each tool decides whether it needs a person: a
+tool that needs one fails with its own error when the getter returns `None`,
+and a tool where the person is optional authorizes against the person when
+present and the caller otherwise, never both. Verify object- and
+action-specific permission before mutation; read access and MCP annotations
+are not write authority. The identity reaches tasks a tool starts and worker
+threads it uses through `asyncio.to_thread` or anyio's `to_thread.run_sync`,
+and ends with the call. See
 [Serving MCP](https://mainsequence-sdk.github.io/mainsequence-sdk/knowledge/fastapi/#serving-mcp).
 
 ### Public provider callbacks and webhooks

{mainsequence-9.0.17.dev60 → mainsequence-9.0.18.dev61}/agent_scaffold/skills/platform_operations/access_control_and_sharing/SKILL.md

@@ -240,13 +240,17 @@ whose own request it is serving. The platform setting is `acts_for_requester`.
 
 ### What the requester's access covers
 
-- Reads and the creates, updates, runs, sharing changes and deletes the person
-  may make, where the platform endpoint supports requester-bound access.
+The platform applies one rule to every call an Agent makes for its work: with
+no delegation, the caller's own ordinary permissions; with a valid delegation,
+the person's ordinary permissions, including administrative ones; an invalid or
+expired delegation is rejected, never switched to another identity.
+
+- The reads, creates, updates, runs, sharing changes and deletes the person
+  may make through supported operations.
 - Check the person's permission for the exact object and operation on every
   call. A read grant or team membership alone does not authorize a write.
-- The requester's member level, never an admin's, even when the requester is
-  an Organization admin.
-- Hosted Agents never receive Secret values, including through this access.
+- Only the person's permissions: never the acting Agent's grants, and never
+  the two combined.
 - At most 24 hours after the person's request, and only while the work for that
   request runs.
 - Checked again on every call, so it stops the moment the person's access ends.
@@ -257,42 +261,38 @@ whose own request it is serving. The platform setting is `acts_for_requester`.
 - A receiving application cannot forward its inbound assertion to establish
   another requester binding. `reads_as_caller()` still refuses these requests.
 
-These writes and delegation require platform support; installing this SDK does
-not enable them. Treat a refused operation as refused, never retry it with the
-application's own grants.
+The platform decides which operations support requester-bound access;
+installing this SDK does not enable one. Treat a refused operation as refused,
+never retry it with the application's own grants.
 
 ### Never accept a person's UID from a request
 
 The requester comes only from the platform. An application never accepts a
-person's UID from a request body, header or query parameter, and never lets a
-caller choose whom it acts for. A FastAPI application that receives a
-requester-bound call reads the requester with `User.get_requester()` and
-authorizes reads and writes against that person's object- and operation-specific
-permissions:
+person's UID from a request body, header or query parameter, never parses the
+assertion, headers or MCP `_meta` itself, and never lets a caller choose whom
+it acts for. A FastAPI application that receives a requester-bound call reads
+the requester with `User.get_requester()`, the person's own `uid`, `team_uids`
+and `is_organization_admin`, and authorizes reads and writes against that
+person's object- and operation-specific permissions. Each handler or tool
+decides whether it needs a person. See
 `.agents/skills/mainsequence/application_surfaces/api_surfaces/SKILL.md`.
 
 ### What people are told
 
-Every client that shows an application with `acts_for_requester` uses the exact
-platform-approved statement from
-[Platform ADR-0051, What people are told](https://github.com/Main-Sequence-Server-Side/tdag-django/blob/development/docs/platform/adr/adr-0051-requester-bound-access-for-workloads.md#11-what-people-are-told).
-Do not invent or paraphrase a separate SDK statement. For write-enabled
-deployments, the approved wording must cover supported reads and writes within
-the person's member-level permissions, Organization-admin approval without
-admin powers or Secret values, the original 24-hour limit including delegation,
-access revocation, and prompt-injection risk. Never present a write-enabled
-Agent as read-only or claim that it cannot change, share or delete anything.
+Every client that shows an application with `acts_for_requester` shows the
+platform's statement, exactly:
+
+> **This Agent works with your identity.** It can read, create, change, run, share or delete only what your permissions allow through supported operations, only while serving your request, and for at most 24 hours after you ask. It uses your ordinary permissions, including administrative permissions, and access is checked on every call. Your Organization's administrator approved it to work this way.
 
-The platform behavior and approved write-enabled statement must ship together.
-If the platform still supplies only the earlier read-only text, do not claim
-the disclosure is ready for a write-enabled rollout or invent replacement words.
+Do not invent, paraphrase or shorten it. Never present such an Agent as
+read-only or claim that it cannot change, share or delete anything.
 
 Explain the risk alongside the statement: a model-driven Agent can be steered
 by prompt injection. Its reads and writes can reach as far as the person's
-member-level permissions allow, including sharing and deleting where
-supported, for at most 24 hours after the original request. Only Organization
-admins decide which Agents may receive this authority; the application's
-per-operation permission checks remain necessary.
+ordinary permissions allow, administrative ones included, such as sharing and
+deleting through supported operations, for at most 24 hours after the original
+request. Only Organization admins decide which Agents may receive this
+authority; the application's per-operation permission checks remain necessary.
 
 ## Review Rules
 
@@ -311,7 +311,8 @@ When reviewing an access-control task, look for:
 - an application that takes a person's UID from a request instead of from the
   platform
 - `acts_for_requester` presented as something a non-admin can enable
-- a requester-bound write authorized only by a read grant or the Agent's grants
+- a requester-bound write authorized by a read grant, by the Agent's grants, or
+  by the Agent's grants combined with the person's
 - prompt-injection risk hidden behind a claim that requester access is read-only
 
 ## Validation Checklist
@@ -332,7 +333,7 @@ Do not claim success until you have checked:
 - an application that acts for its requester takes the person only from the
   platform, and its own grants are intentional
 - requester-bound writes enforce the person's permission for the operation,
-  and clients explain both the write risk and the original 24-hour limit
+  and clients show the platform's exact statement and explain the write risk
 
 ## This Skill Must Stop And Escalate When
 

{mainsequence-9.0.17.dev60 → mainsequence-9.0.18.dev61}/mainsequence/client/models_user.py

@@ -33,7 +33,8 @@ class RequestUserIdentity(BaseModel):
     The caller is a person or a workload identity; ``User.get_by_uid(uid)``
     reads its User. ``User.get_requester()`` returns the same type for the
     requester of a requester-bound request, the person the calling
-    application works for; its ``is_organization_admin`` is always ``False``.
+    application works for, with that person's own ``team_uids`` and
+    ``is_organization_admin``.
     """
 
     model_config = ConfigDict(extra="forbid", frozen=True)
@@ -55,18 +56,18 @@ class RequestUserIdentity(BaseModel):
         (),
         title="Team UIDs",
         description=(
-            "Canonical UIDs of the caller's active teams, or the requester's, as signed "
-            "by the platform in the caller assertion. Empty when the request carries no "
-            "such facts."
+            "Canonical UIDs of the active teams the platform signed in the caller "
+            "assertion: the caller's, or for the requester the person's own. Empty in "
+            "local mode and on WebSockets, which carry no such facts."
         ),
     )
     is_organization_admin: bool = Field(
         False,
         title="Organization admin",
         description=(
-            "Whether the platform signed the caller as an admin of the application's "
-            "Organization. False when the request carries no such facts, and always "
-            "False for the requester of a requester-bound request."
+            "Whether the platform signed this identity as an admin of the application's "
+            "Organization: the caller, or for the requester the person. False in local "
+            "mode and on WebSockets, which carry no such facts."
         ),
     )
 
@@ -1307,34 +1308,40 @@ class User(_CallerDirectoryReadMixin, UserApiBaseObjectOrm, BasePydanticModel):
 
     @classmethod
     def get_requester(cls) -> RequestUserIdentity | None:
-        """Return the requester of a requester-bound request, or ``None``.
+        """Return the person a requester-bound request works for, or ``None``.
 
         A requester-bound request comes from another application, for example
         an Agent, while it works for a person: the requester. The platform
-        signs the requester into the caller assertion. ``get_logged_user()``
-        still returns the caller, the acting application. The requester has
-        the ``team_uids`` the platform signed and ``is_organization_admin``
-        ``False``: the requester's access reaches the application at member
-        level only.
+        signs that person into the caller assertion, and the request identity
+        integration verifies it before any handler or tool runs. The result is
+        that checked delegation: the person's own ``uid``, ``team_uids`` and
+        ``is_organization_admin``, as the platform signed them.
+        ``get_logged_user()`` still returns the caller, the acting application.
 
-        Returns ``None`` when the request is not requester-bound, including
+        Returns ``None`` when the request carries no delegation, including
         local mode and WebSockets. Raises ``RequestIdentityError`` outside an
-        authenticated request, as ``get_logged_user()`` does.
-
-        Authorize reads and writes against the requester's permission for the
-        exact object and operation. This getter verifies identity, not
-        authorization; read access or team membership does not authorize a
-        write. Give the acting application no rights of its own unless your
-        policy grants them.
-        An operation that needs a person fails closed when this is ``None``.
-        Never take a person's UID from a request body, header or query
-        parameter instead. Platform-supported requester-bound writes stay
-        within the person's member-level rights, never admin powers or Secret
-        values. The platform checks access on every call and limits the work to
-        at most 24 hours after the original request, including across approved
-        Agent delegation. A model-driven Agent can be steered by prompt
-        injection, so per-operation checks remain necessary. This getter does
-        not enable platform write endpoints or extend its request scope.
+        authenticated request, as ``get_logged_user()`` does. An invalid
+        delegation rejects the whole request before any handler or tool runs;
+        it never falls back to the caller.
+
+        Each handler or tool decides whether it needs a person:
+
+        - one that needs a person fails with its own error when this returns
+          ``None``;
+        - one where the person is optional authorizes against this result when
+          present, and against ``get_logged_user()`` otherwise;
+        - none parses assertions, headers or MCP ``_meta``, takes a person's
+          UID from a request body, header or query parameter, or combines the
+          caller's grants with the person's.
+
+        Authorize against the person's ordinary permissions, including
+        administrative ones, for the exact object and operation. This getter
+        verifies identity, not permission; read access or team membership does
+        not authorize a write. The platform checks access on every call and
+        limits the work to at most 24 hours after the person's request. A
+        model-driven Agent can be steered by prompt injection, so per-operation
+        checks remain necessary. This getter does not enable platform
+        endpoints or extend its request scope.
         """
         requester = _get_requester()
         if requester is not None and not isinstance(requester, RequestUserIdentity):

{mainsequence-9.0.17.dev60 → mainsequence-9.0.18.dev61}/mainsequence/server/caller_assertions.py

@@ -32,12 +32,14 @@ REQUIRED_CLAIMS = frozenset(
         "iat",
         "nbf",
         "exp",
+        # What the platform states about the caller: its active team UIDs and
+        # whether it is an admin of the application's Organization.
+        "team_uids",
+        "is_organization_admin",
     }
 )
-# What the platform states about the caller: active team UIDs and the
-# Organization-admin flag. Sent together, or not at all by a platform that
-# predates them; then the caller has no teams and is not an admin.
-CALLER_FACT_CLAIMS = frozenset({"team_uids", "is_organization_admin"})
+# The person a requester-bound call works for, with the person's own facts.
+REQUESTER_CLAIMS = frozenset({"sub", "team_uids", "is_organization_admin"})
 
 
 class InvalidCallerAssertion(ValueError):
@@ -62,7 +64,8 @@ class _VerifiedRequester:
     """The person a requester-bound call works for, as the platform signed it."""
 
     user_uid: str
-    team_uids: tuple[str, ...] = ()
+    team_uids: tuple[str, ...]
+    is_organization_admin: bool
 
 
 @dataclass(frozen=True)
@@ -72,9 +75,9 @@ class AuthenticatedCaller:
     environment_uid: str
     issued_at: int
     expires_at: int
-    team_uids: tuple[str, ...] = ()
-    is_organization_admin: bool = False
-    # The requester of a requester-bound call, None on any other call. The
+    team_uids: tuple[str, ...]
+    is_organization_admin: bool
+    # The person a requester-bound call works for, None on any other call. The
     # fields above stay the caller's: the acting application (ADR-0036).
     _requester: _VerifiedRequester | None = None
 
@@ -88,34 +91,38 @@ def _team_uids(value: object, *, owner: str) -> tuple[str, ...]:
     return team_uids
 
 
+def _admin_flag(value: object, *, owner: str) -> bool:
+    if type(value) is not bool:
+        raise InvalidCallerAssertion(f"{owner} admin flag is invalid.")
+    return value
+
+
 def _caller_facts(payload: dict) -> tuple[tuple[str, ...], bool]:
-    facts = set(payload) & CALLER_FACT_CLAIMS
+    """The caller's team UIDs and admin flag, which every assertion carries."""
     # A requester-bound call also carries "requester", which _requester() checks.
-    claims = set(payload) - facts - {"requester"}
-    if claims != REQUIRED_CLAIMS or facts not in (set(), set(CALLER_FACT_CLAIMS)):
+    if set(payload) - {"requester"} != REQUIRED_CLAIMS:
         raise InvalidCallerAssertion("Caller assertion claims are invalid.")
-    if not facts:
-        return (), False
-    team_uids = _team_uids(payload["team_uids"], owner="Caller")
-    if type(payload["is_organization_admin"]) is not bool:
-        raise InvalidCallerAssertion("Caller admin flag is invalid.")
-    return team_uids, payload["is_organization_admin"]
+    return (
+        _team_uids(payload["team_uids"], owner="Caller"),
+        _admin_flag(payload["is_organization_admin"], owner="Caller"),
+    )
 
 
 def _requester(payload: dict) -> _VerifiedRequester | None:
-    """The requester of a requester-bound call: exactly ``sub`` and ``team_uids``.
+    """The person a requester-bound call works for, or None on any other call.
 
-    It never carries an admin flag: the requester's access reaches the
-    application at member level only.
+    The claim has exactly ``sub``, ``team_uids`` and ``is_organization_admin``:
+    the person's own User UID, active team UIDs and Organization-admin flag.
     """
     if "requester" not in payload:
         return None
     claim = payload["requester"]
-    if not isinstance(claim, dict) or set(claim) != {"sub", "team_uids"}:
+    if not isinstance(claim, dict) or set(claim) != REQUESTER_CLAIMS:
         raise InvalidCallerAssertion("Caller assertion requester is invalid.")
     return _VerifiedRequester(
         user_uid=_canonical_uid(claim["sub"]),
         team_uids=_team_uids(claim["team_uids"], owner="Requester"),
+        is_organization_admin=_admin_flag(claim["is_organization_admin"], owner="Requester"),
     )
 
 

{mainsequence-9.0.17.dev60 → mainsequence-9.0.18.dev61}/mainsequence/server/fastapi.py

@@ -229,10 +229,11 @@ class _RequestIdentityMiddleware:
                         state["organization_environment_uid"] = caller.environment_uid
                         context.caller_assertion = assertion
                         if caller._requester is not None:
-                            # Never an admin: the requester's access is member level.
+                            # The person this call works for, with the person's own facts.
                             context.requester = RequestUserIdentity(
                                 uid=caller._requester.user_uid,
                                 team_uids=caller._requester.team_uids,
+                                is_organization_admin=caller._requester.is_organization_admin,
                             )
                     else:
                         user = await asyncio.to_thread(_local_user, scope)
@@ -397,9 +398,10 @@ def install_mcp(app, mcp_app, *, lifespan):
 
     Install request identity first. Tools read the caller with
     ``User.get_logged_user()`` and, on a requester-bound call, the person it
-    works for with ``User.get_requester()``. Only authenticated POSTs reach the
-    server; other methods answer 405 and an ``Origin`` other than the release's
-    own or its CORS origins answers 403. See ADR 0038.
+    works for with ``User.get_requester()``; each tool decides whether it needs
+    that person. Only authenticated POSTs reach the server; other methods
+    answer 405 and an ``Origin`` other than the release's own or its CORS
+    origins answers 403. See ADR 0038.
     """
     from starlette.routing import Route
 

{mainsequence-9.0.17.dev60 → mainsequence-9.0.18.dev61}/mainsequence.egg-info/PKG-INFO

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

{mainsequence-9.0.17.dev60 → mainsequence-9.0.18.dev61}/pyproject.toml

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