mainsequence 9.0.25.dev69__tar.gz → 9.0.26__tar.gz

{mainsequence-9.0.25.dev69/mainsequence.egg-info → mainsequence-9.0.26}/PKG-INFO

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

{mainsequence-9.0.25.dev69 → mainsequence-9.0.26}/agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md

@@ -160,6 +160,52 @@ connection is active. See the version-matched
 [FastAPI identity documentation](https://mainsequence-sdk.github.io/mainsequence-sdk/knowledge/fastapi/)
 for the lifecycle and trust contract.
 
+### Team membership
+
+The application owns its team policies. Check whether the caller belongs to
+the teams a policy names with `in_teams()`. Never take team facts from the
+request body, a header, a query parameter or the assertion:
+
+```python
+from fastapi import HTTPException
+from mainsequence.client import User
+
+
+@app.post("/teams/{team_uid}/reports")
+def publish_report(team_uid: str) -> dict[str, str]:
+    caller = User.get_logged_user()
+    # A write: ask the platform now instead of reusing an older answer.
+    if team_uid not in caller.in_teams([team_uid], max_age_seconds=0):
+        raise HTTPException(status_code=403, detail="Only the team's members can publish.")
+    return {"team_uid": team_uid, "published_by": caller.uid}
+```
+
+- `in_teams(team_uids, *, max_age_seconds=None)` returns the subset of
+  `team_uids` the person is an active member of, as a `frozenset` of canonical
+  UIDs; an empty set means none. Unknown and inactive teams are left out. It
+  works on `User.get_logged_user()` and `User.get_requester()`, asks only about
+  that request's caller or requester, and sends longer lists in calls of at
+  most 100 teams.
+- How long an answer may be reused is the application's choice.
+  `install_request_identity(app, team_membership_cache_seconds=60)` reuses an
+  answer across requests while it is younger than 60 seconds; the default, `0`,
+  reuses it only within its request. `max_age_seconds` sets the lifetime for
+  one call, and `max_age_seconds=0` always asks the platform: use it before a
+  write or anything that must see a removal at once.
+- It raises `RequestIdentityError` outside a signed HTTP request, in local mode
+  and on WebSockets, and the SDK's API error when the platform cannot answer.
+  Let the request fail: never read an exception as "member" or "not a member".
+- It calls the platform when it has no answer to reuse, and that call blocks.
+  Call it from a `def` handler, or from an `async def` handler with
+  `await asyncio.to_thread(caller.in_teams, team_uids)`, which keeps the
+  request's identity.
+- `team_uids` on the identity is deprecated and warns when read. In a signed
+  HTTP request it raises `RequestIdentityError` when the assertion carried no
+  team list, as every assertion will once the platform stops signing them.
+  Replace every check that reads it with `in_teams()`.
+- Membership is not team administration and not a grant on an object: check
+  the exact object and action as well.
+
 ### Requester-bound calls
 
 Another application, for example an Agent, can call the API while it works for
@@ -168,9 +214,9 @@ 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` and `is_organization_admin`, or `None` when the call carries
-no delegation. `in_teams(team_uids)` on either identity asks the platform which
-of those teams the person belongs to; `team_uids` is deprecated. A requester-bound call carries the person's
-ordinary permissions, including administrative ones.
+no delegation. `in_teams()` on the requester answers for the person's teams
+([Team membership](#team-membership)). 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

{mainsequence-9.0.25.dev69 → mainsequence-9.0.26}/agent_scaffold/skills/platform_operations/access_control_and_sharing/SKILL.md

@@ -136,6 +136,10 @@ Keep these separate:
 - inherited access to shared resources
 - administration of the team itself
 
+An application that checks whether its caller or requester belongs to a team
+uses `in_teams()`, never the deprecated `team_uids`; see
+`.agents/skills/mainsequence/application_surfaces/api_surfaces/SKILL.md`.
+
 ### 5. `Constant` vs `Secret` is a security boundary
 
 Use `Constant` for non-sensitive runtime values.
@@ -304,6 +308,9 @@ When reviewing an access-control task, look for:
 - using direct user grants where a team should be used
 - using a team when the access is clearly one-off
 - treating team membership as team administration
+- team checks that read the deprecated `team_uids` instead of `in_teams()`,
+  that read an `in_teams()` error as "not a member", or that reuse an older
+  answer (no `max_age_seconds=0`) before a write that must see a removal
 - storing sensitive data in a `Constant`
 - creating a `Constant` or `Secret` blindly without resolving whether the name already exists
 - weak or unverified claims about who can access a resource

{mainsequence-9.0.25.dev69 → mainsequence-9.0.26/mainsequence.egg-info}/PKG-INFO

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

{mainsequence-9.0.25.dev69 → mainsequence-9.0.26}/pyproject.toml

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

{mainsequence-9.0.25.dev69 → mainsequence-9.0.26}/tests/test_team_memberships.py

@@ -5,6 +5,7 @@ membership check is a fake ``make_request`` that answers from a set of
 memberships and records every call.
 """
 
+import asyncio
 import time
 import warnings
 from types import SimpleNamespace
@@ -157,6 +158,26 @@ def test_the_caller_learns_which_of_the_asked_teams_it_belongs_to(sign, platform
     assert call.payload["headers"] == {ASSERTION_HEADER: proof}
 
 
+def test_an_async_handler_asks_through_a_worker_thread_as_its_caller(sign, platform):
+    # The call blocks, so an async handler runs it in a worker thread; the
+    # thread keeps the request's identity (the skill and knowledge page say so).
+    research, operations = teams(2)
+    platform.members = {(CALLER, research)}
+    proof = sign()
+
+    async def handler():
+        caller = User.get_logged_user()
+        return sorted(await asyncio.to_thread(caller.in_teams, [research, operations]))
+
+    with TestClient(app_with(handler)) as client:
+        answer = client.get("/check", headers={ASSERTION_HEADER: proof}).json()
+
+    assert answer == [research]
+    (call,) = platform.calls
+    assert call.person == CALLER
+    assert call.payload["headers"] == {ASSERTION_HEADER: proof}
+
+
 def test_the_requester_and_the_acting_caller_are_asked_about_separately(sign, platform):
     research, operations = teams(2)
     platform.members = {(PERSON, research), (CALLER, operations)}