mainsequence 8.1.22.dev21__tar.gz → 8.1.22.dev23__tar.gz

{mainsequence-8.1.22.dev21/mainsequence.egg-info → mainsequence-8.1.22.dev23}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 8.1.22.dev21
+Version: 8.1.22.dev23
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: LicenseRef-MainSequence-Proprietary

{mainsequence-8.1.22.dev21 → mainsequence-8.1.22.dev23}/agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mainsequence-command-center-fastapi
-description: Build, contract-test, release, and verify a FastAPI code repository resource that serves the Command Center frontend. Use when a Main Sequence API must implement a wire contract defined by the mainsequence-sdk/command-center-sdk GitHub repository and then move through local testing, code-repository sync, image and resource resolution, FastAPI ResourceRelease creation, and deployed frontend validation.
+description: Build, contract-test, release, and verify a FastAPI code repository resource serving the Command Center frontend, including applications with public OAuth callback or webhook routes. Use when implementing a Command Center wire contract, declaring exact public ingress, or validating the deployed API.
 ---
 
 # Command Center FastAPI Release Lifecycle
@@ -92,7 +92,7 @@ Record:
 - whether the API uses backend transport or a contract-defined direct
   development transport
 
-FastAPI releases receive the authenticated human from the Main Sequence
+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:
 
@@ -111,21 +111,74 @@ def get_me(request: Request) -> dict[str, str | None]:
     }
 ```
 
-Route code must not detect local versus deployed execution, parse
-authentication headers, or resolve the request user itself. Consume only the
+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:
 
 - `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
 
-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
+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.
 
+### 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.
+
+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
+   root-relative path under the `kind: fastapi` resource's
+   `spec.public_ingress`. The policy is not inferred from decorators or OpenAPI.
+   Do not include query strings, route parameters, wildcards, or a hostname.
+   The default empty list exposes no public paths. In a validated workflow
+   resource, the declaration has this shape:
+
+   ```yaml
+   kind: fastapi
+   spec:
+     source_path: api/provider/main.py
+     public_ingress:
+       - method: GET
+         path: /integrations/provider/oauth/callback/
+       - method: POST
+         path: /integrations/provider/webhook/
+   ```
+
+2. Fetch the exact CodeRepositoryBranch's current workflow template; use its
+   advertised version and fields. Validate the proposed workflow file through
+   the branch's `validate-workflow` action, then commit the handler and workflow
+   file and push the intended branch. Do not set the reserved
+   `FASTAPI_PUBLIC_INGRESS` environment value yourself.
+3. Follow the repository event and DeploymentRun to a ready active revision.
+   A validated file or successful push is not proof of public admission. Read
+   `resource_release.get` and confirm the pair appears in both desired
+   `public_ingress` and active `effective_public_ingress`. Only then append the
+   declared path to the backend-returned `public_url` and register that full
+   callback or webhook URI with the provider. Do not construct a hostname.
+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
+   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,
+   logs, and test evidence.
+
+An existing release can change its desired policy through the canonical
+`resource_release.update` operation. Adding a pair still requires a later ready
+revision containing the route before it becomes public. Removing a desired pair
+denies it immediately. The platform skill
+`mainsequence://platform/skills/code-repository-workflows` owns the detailed
+automatic deployment procedure and current workflow shape.
+
 ### 2. Implement the provider
 
 Keep Command Center contract-bearing route code focused on transport and
@@ -203,6 +256,7 @@ Verify that:
 - resource discovery found that path at the exact deployed commit
 - Django resolved and built the exact image for the workflow event
 - the resulting release kind is `fastapi`
+- any declared `public_ingress` pair matches a mounted FastAPI handler
 - compute and spot settings are intentional
 
 Enable automatic deployment in the repository workflow when the route paths,
@@ -211,11 +265,13 @@ events to promote exact images.
 
 ### 6. Verify the deployed API
 
-Request runtime access for the deployed FastAPI `ResourceRelease` through
-Django and wait for Django's ready result. Use the returned access bundle for
-the deployed checks:
+Request runtime access for protected routes on the deployed FastAPI
+`ResourceRelease` through Django and wait for Django's ready result. Use the
+returned access bundle for authenticated checks. For declared public routes,
+use the provider URI without a Main Sequence Bearer token:
 
-1. verify authentication behavior
+1. verify protected-route authentication and, when configured, exact
+   unauthenticated public-ingress method/path behavior
 2. execute representative contract-bearing requests
 3. validate returned JSON against the same repository-pinned schemas
 4. exercise the consuming Command Center frontend flow
@@ -235,6 +291,9 @@ Report:
 - Git commit, code repository image UID, code repository resource UID, and release identity
 - deployed contract validation and Command Center frontend result
 - whether automatic deployment is enabled and why
+- for public provider routes, the declared method/path pairs, observed
+  `effective_public_ingress`, backend-returned provider URI, and unauthenticated
+  positive and negative request results
 
 The Command Center-facing release is complete only when the frontend consumes
 the deployed contract-bearing responses and they pass the contracts from the

{mainsequence-8.1.22.dev21 → mainsequence-8.1.22.dev23/mainsequence.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 8.1.22.dev21
+Version: 8.1.22.dev23
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License-Expression: LicenseRef-MainSequence-Proprietary

{mainsequence-8.1.22.dev21 → mainsequence-8.1.22.dev23}/pyproject.toml

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