mainsequence 9.0.8.dev43__py3-none-any.whl → 9.0.8.dev44__py3-none-any.whl

agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md

@@ -92,46 +92,71 @@ Record:
 - whether the API uses backend transport or a contract-defined direct
   development transport
 
-Authenticated FastAPI routes receive the human caller from the Main Sequence
-platform through injected request state. No SDK authentication setup is
-required in repository code:
+Install the SDK's request-identity integration once when creating the FastAPI
+application. Inspect the existing application factory first: the generated
+platform template already calls `install_request_identity(app)`, and a second
+installation raises an error. For an application without that setup:
 
 ```python
-from fastapi import FastAPI, Request
+from fastapi import FastAPI
+from mainsequence.client import User
+from mainsequence.server.fastapi import install_request_identity
 
 
 app = FastAPI()
+install_request_identity(app)
 
 
 @app.get("/me")
-def get_me(request: Request) -> dict[str, str | None]:
-    return {
-        "uid": request.state.user_uid,
-        "username": request.state.user.username,
-    }
+def get_me() -> dict[str, str | None]:
+    user = User.get_logged_user()
+    return {"uid": user.uid, "username": user.username}
 ```
 
-Protected route code must not detect local versus deployed execution, parse
-authentication headers, or resolve the request user itself. Consume the
-platform-injected human caller identity:
+Use `User.get_logged_user()` in authenticated synchronous or asynchronous
+handlers and their shared services. The middleware verifies the caller before
+the handler, binds one isolated request context, and invalidates it on
+completion, errors, or cancellation. Repeated getter calls do not perform
+additional authentication requests.
 
-- `request.state.user` contains canonical `uid` and optional `username`
-- `request.state.user_uid` is the canonical public user UUID
-- `request.state.user_id` does not exist
+The same installation handles both HTTP execution modes:
+
+- Local execution without hosted deployment markers validates the incoming
+  Bearer token against `MAINSEQUENCE_ENDPOINT/api/v1/users/me/`.
+- Platform-hosted execution verifies the gateway's signed caller assertion
+  using deployment-owned issuer, public-key, release, and Environment settings.
+  Hosted configuration cannot select local mode, and failed proof never falls
+  back to UID headers or the process's credentials.
+
+Route code must not select the mode, parse authentication headers, or implement
+another caller resolver. The launcher checks the application's installation
+declaration before serving; it does not install the middleware itself.
+
+The identity contains canonical `uid` and optional `username`; signed HTTP
+proofs contain no username. `request.state.user` and `request.state.user_uid`
+remain projections of the same identity, not a separate resolver. Outside an
+authenticated request, including public routes, `User.get_logged_user()` raises
+`RequestIdentityError`.
 
 On a protected route, this identity is the human making the current HTTP
 request. It is not the release creator, deployment owner, runtime workload
-principal, or runtime target. Pass request state explicitly to shared services;
-do not use `User.get_logged_user()` as a FastAPI entry point. Platform-injected identity is
-not resource authorization; use `request.state.user_uid` when applying the
-endpoint's authorization policy.
+principal, or the process account returned by `User.get_authenticated_user_details()`.
+Caller authentication is not resource authorization; apply the endpoint's
+application policy using the verified user UID.
+
+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
+[FastAPI identity documentation](https://mainsequence-sdk.github.io/mainsequence-sdk/knowledge/fastapi/)
+for the lifecycle and trust contract.
 
 ### Public provider callbacks and webhooks
 
 An external OAuth redirect or webhook cannot supply a Main Sequence Bearer token.
 For a FastAPI release that needs one, use the platform's exact `public_ingress`
 policy. CORS configuration and an app-declared route alone do not make a path
-public. Ordinary routes remain Bearer authenticated.
+public. Ordinary routes still require an authenticated caller through the
+request-identity integration.
 
 1. Implement the provider handler in the FastAPI app loaded by the workflow's
    `source_path`. Declare only its exact `GET` or `POST` method and literal
@@ -166,7 +191,9 @@ public. Ordinary routes remain Bearer authenticated.
 4. Send a provider-style request without a Main Sequence Bearer token to the
    exact public pair. Check that an unlisted path or wrong method is denied.
    An admitted request has `request.state.user` and `user_uid` set to `None`
-   and `request.state.auth_outcome == "public_ingress"`. The handler must verify
+   and `request.state.auth_outcome == "public_ingress"`;
+   `User.get_logged_user()` raises `RequestIdentityError` in that anonymous
+   scope. The handler must verify
    OAuth state and exchange codes, or verify the webhook signature against the
    original body and reject replays. Public admission supplies no User or
    provider identity. Keep provider secrets and live codes out of workflow YAML,

mainsequence/client/models_user.py

@@ -37,6 +37,22 @@ class RequestUserIdentity(BaseModel):
         title="Username",
         description="Optional display name authenticated by the runtime gateway.",
     )
+    team_uids: tuple[str, ...] = Field(
+        (),
+        title="Team UIDs",
+        description=(
+            "Canonical UIDs of the caller's active teams, as signed by the platform "
+            "in the caller assertion. Empty when the request carries 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."
+        ),
+    )
 
     @field_validator("uid", mode="before")
     @classmethod
@@ -46,6 +62,14 @@ class RequestUserIdentity(BaseModel):
         except (AttributeError, TypeError, ValueError) as exc:
             raise ValueError("Request user UID must be a valid UUID.") from exc
 
+    @field_validator("team_uids", mode="before")
+    @classmethod
+    def _canonicalize_team_uids(cls, value: Any) -> tuple[str, ...]:
+        try:
+            return tuple(str(UUID(str(item).strip())) for item in value or ())
+        except (AttributeError, TypeError, ValueError) as exc:
+            raise ValueError("Team UIDs must be valid UUIDs.") from exc
+
     @field_validator("username", mode="before")
     @classmethod
     def _normalize_username(cls, value: Any) -> str | None:

mainsequence/server/caller_assertions.py

@@ -33,6 +33,10 @@ REQUIRED_CLAIMS = frozenset(
         "exp",
     }
 )
+# 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"})
 
 
 class InvalidCallerAssertion(ValueError):
@@ -59,6 +63,25 @@ class AuthenticatedCaller:
     environment_uid: str
     issued_at: int
     expires_at: int
+    team_uids: tuple[str, ...] = ()
+    is_organization_admin: bool = False
+
+
+def _caller_facts(payload: dict) -> tuple[tuple[str, ...], bool]:
+    facts = set(payload) & CALLER_FACT_CLAIMS
+    if set(payload) - facts != REQUIRED_CLAIMS or facts not in (set(), set(CALLER_FACT_CLAIMS)):
+        raise InvalidCallerAssertion("Caller assertion claims are invalid.")
+    if not facts:
+        return (), False
+    raw_team_uids = payload["team_uids"]
+    if not isinstance(raw_team_uids, list):
+        raise InvalidCallerAssertion("Caller team UIDs are invalid.")
+    team_uids = tuple(_canonical_uid(value) for value in raw_team_uids)
+    if list(team_uids) != sorted(set(team_uids)):
+        raise InvalidCallerAssertion("Caller team UIDs must be sorted and unique.")
+    if type(payload["is_organization_admin"]) is not bool:
+        raise InvalidCallerAssertion("Caller admin flag is invalid.")
+    return team_uids, payload["is_organization_admin"]
 
 
 class CallerAssertionVerifier:
@@ -206,8 +229,7 @@ class CallerAssertionVerifier:
                 audience=f"urn:mainsequence:fapi:{self.release_uid}",
                 options={"require": list(REQUIRED_CLAIMS)},
             )
-            if set(payload) != REQUIRED_CLAIMS:
-                raise InvalidCallerAssertion("Caller assertion claims are invalid.")
+            team_uids, is_organization_admin = _caller_facts(payload)
             if (
                 payload["aud"] != f"urn:mainsequence:fapi:{self.release_uid}"
                 or _canonical_uid(payload["resource_release_uid"]) != self.release_uid
@@ -226,6 +248,8 @@ class CallerAssertionVerifier:
                 environment_uid=self.environment_uid,
                 issued_at=iat,
                 expires_at=exp,
+                team_uids=team_uids,
+                is_organization_admin=is_organization_admin,
             )
         except (InvalidTokenError, KeyError, TypeError, ValueError) as exc:
             raise InvalidCallerAssertion("Caller assertion is invalid.") from exc

mainsequence/server/fastapi.py

@@ -213,7 +213,11 @@ class _RequestIdentityMiddleware:
                     elif self.mode == "assertion":
                         assertion = _header(scope, ASSERTION_HEADER.lower().encode()) or ""
                         caller = await asyncio.to_thread(self.verifier.verify, assertion)
-                        user = RequestUserIdentity(uid=caller.user_uid)
+                        user = RequestUserIdentity(
+                            uid=caller.user_uid,
+                            team_uids=caller.team_uids,
+                            is_organization_admin=caller.is_organization_admin,
+                        )
                         state["resource_release_uid"] = caller.release_uid
                         state["organization_environment_uid"] = caller.environment_uid
                     else:

{mainsequence-9.0.8.dev43.dist-info → mainsequence-9.0.8.dev44.dist-info}/METADATA

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

{mainsequence-9.0.8.dev43.dist-info → mainsequence-9.0.8.dev44.dist-info}/RECORD

@@ -1,6 +1,6 @@
 agent_scaffold/AGENTS.md,sha256=W91rpnyQuoQIa-3dsebIYyuwnbGLvkmuq_8X5k2hTAw,6399
 agent_scaffold/skills/a2a_sdk_execution/SKILL.md,sha256=NKtcXibE8TxZzKzz1KzJ2cVZ_EeuJJkb660U6wLvZ3s,11809
-agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md,sha256=EEU3eZGgOmY0KOWTgDZ5RJIrLtM8p6yqK894jM7-ySg,14357
+agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md,sha256=GdbPjIf4xMs5Pz6VrjAwBBePkc7rC3P57s70PNjYZWU,15997
 agent_scaffold/skills/mainsequence-inference/SKILL.md,sha256=IrVnpuzFMZ3_x5oSH4OiPZsZ5jFf_aKdxEynrQhnRZE,11627
 agent_scaffold/skills/maintenance/bug_auditor/SKILL.md,sha256=CCKs7edyZ9RK-WtAgXJXucokJFXZxk8sRUe0_imFtu8,8610
 agent_scaffold/skills/maintenance/code_repository_maintenance/SKILL.md,sha256=pPsZaERlfokSJ6b6vLjpA5U0KuKxbOFzzcxOVW_ikiI,17935
@@ -44,18 +44,18 @@ mainsequence/client/github_issues.py,sha256=pSTUw3UPrmE6wqnpoJctartTaNSq6iu6PQRr
 mainsequence/client/inference.py,sha256=g24H9LWumMRABIevho8FS7BBOuyYvf80pRwCmJZpLeY,7353
 mainsequence/client/models_foundry.py,sha256=iN1jJzDokfniEQF0Ac5eepAB7L5pVjJnKavaHLP7BHA,36310
 mainsequence/client/models_helpers.py,sha256=y7cgcsH8yO3dfIWPhRdcYam7ItWHw3Ps63-WYDe4YHE,46262
-mainsequence/client/models_user.py,sha256=BU_hfn4-4KqYz3nsaPlXuYZmUG6_-7YM892mkM92Zyo,37613
+mainsequence/client/models_user.py,sha256=co9uhe-LKkt7Kw5u8-wDMWcp0yL_lS2LuUOyauW5KF0,38557
 mainsequence/client/observability.py,sha256=_WrDKCaNk_TXmKElKCXC1inork6Exxxe8FRY4m1GI9s,16008
 mainsequence/client/utils.py,sha256=c4JjMIqKfwSz8DdkwLGmGtQ9lSmVn_KEw9KWGDwz_T0,30133
 mainsequence/client/value_sets.py,sha256=7TA-mpuAd3hOduNgO1WTQQTuNOGaFgue-VqCsDWKaC8,6181
 mainsequence/instrumentation/__init__.py,sha256=J_9XmfjprElvz0u2t9rTyJT0kFdyKpxdbkdQiaw28_U,316
 mainsequence/instrumentation/utils.py,sha256=b-ihjSioAepeLfMpudM2SqCtvnxMqIXileHx3klBCQU,3377
 mainsequence/server/__init__.py,sha256=BHUAhtdWPDRdxX07NYO_6wrBv5mf0GsXflecO52PmUc,73
-mainsequence/server/caller_assertions.py,sha256=hZW1pkkvQ9gaFL075bxUbbctTRrgMMQRTSc2Da0vKCM,9705
-mainsequence/server/fastapi.py,sha256=tD1aVuJOgoBTu7H8bs9IldPNYRT4fhkr1leN3KZP1pI,10521
-mainsequence-9.0.8.dev43.dist-info/licenses/LICENSE,sha256=b6Ecsk8wjsEby3lbSzdljR6hHiFGHBizt9iWV2p1c_I,1074
-mainsequence-9.0.8.dev43.dist-info/METADATA,sha256=1GLtjggEXh4UZaisPIBKffjPsaqgkW5LeX7pambJX60,7402
-mainsequence-9.0.8.dev43.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-mainsequence-9.0.8.dev43.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
-mainsequence-9.0.8.dev43.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
-mainsequence-9.0.8.dev43.dist-info/RECORD,,
+mainsequence/server/caller_assertions.py,sha256=f9jHhVeoFK1ScDCmW8h3lEIU5V7zKw70SUSVV2P7wUI,10975
+mainsequence/server/fastapi.py,sha256=Y5QB51CRVbuUVRUcWh5GKQ5b5vMPjbs9scioTt684oQ,10712
+mainsequence-9.0.8.dev44.dist-info/licenses/LICENSE,sha256=b6Ecsk8wjsEby3lbSzdljR6hHiFGHBizt9iWV2p1c_I,1074
+mainsequence-9.0.8.dev44.dist-info/METADATA,sha256=2cyUFtw68GftzC-tFiPNUwc3ZV7Vqg4hpptgihrgOX0,7402
+mainsequence-9.0.8.dev44.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+mainsequence-9.0.8.dev44.dist-info/entry_points.txt,sha256=XGAOq3-mF2lWWpeRJvoaWyMarRcK167mH1g124aGdUs,88
+mainsequence-9.0.8.dev44.dist-info/top_level.txt,sha256=BFeblM_Q9q0cUWBvTxnfWcWQEHtf5XZi9nOS-Gdfwus,28
+mainsequence-9.0.8.dev44.dist-info/RECORD,,