SysEngineering

cos_lab

Adam Schembri’s personal chief of staff, built as the SCSP MCP connector in miniature: Claude connects to one remote MCP connector (Cloud Run, Google sign-in) that reads Adam’s own GitHub, Jira and Confluence, Calendar, Gmail and Okta. It proves the SCSP design on one person before SCSP depends on it. Read HANDOFF.md first (current state, Adam’s pending tasks, the plan for the next step), then README.md for the step table.

• Code: this folder in Hillspire/SysEngineering. It moved here on 2026-10-15 from the short-lived Hillspire/adam-cos-lab repo, deleted once the move is merged. Changes go through PRs like everything else in this repo; the Claude reviewer and the “SCSP CoS Lab Tests” workflow cover this folder.
• Google Cloud: project adam-cos-lab (schmidtentity.com org, same billing as Adam’s other projects). Jira: ITPROJ-1421, under SCSP epic ITPROJ-1401. Comment on the ticket in first person when a step lands.
• SCSP context: the parent folder (../HANDOFF.md, ../CLAUDE.md) and Confluence IPO → 3.M SCSP Initiative.
• The connector’s OAuth comes from Gwen’s production connector: ../../gwen_grant_memo_agent/mcp_oauth.py.
• Run commands from this folder: the package is lab, imported relative to it (pyproject.toml sets pythonpath = ["."]).
• Adam switches between a Windows desktop and a MacBook. Keep paths and commands portable: no absolute paths in committed config.

Invariants (each has a test; keep it that way)

• Read-only. Connectors reach the network only through one GET helper; Google scopes end in .readonly; no write method appears in lab/tools/google.py.
• The model never chooses whose data. No tool schema has a user, email or account parameter. Identity comes from the verified sign-in.
• Tool results are untrusted. frame() wraps every result in UNTRUSTED_*_DATA markers.
• Append-only history in the loop. Responses go back exactly as returned. The only rewrite is the documented fallback rule in history_content().
• Stable prompt prefix. The system prompt and tool list never change between calls.
• No secrets on disk. Locally gh auth token plus op run; deployed, Secret Manager in adam-cos-lab only. Never gw-admin-assistant, where harry-devs can read every secret.
• Least privilege per source. Okta and Atlassian get read-only scoped credentials, never Adam’s admin token.
• Company accounts only. No consumer AI plan ever sees this data.
• Natural language only. No keyword lists or regex intent matching.

The connector (lab/connector/, step 2)

• /mcp needs a token. The low-level SDK server guards /mcp only when handed token_verifier; drop it and /mcp is silently open. A test walks every route, mounts included: anything outside the listed sign-in and discovery endpoints must answer 401.
• Codes go only to loopback (Claude Code): plain http, any port (RFC 8252), no query, no fragment. A registered query would put a second, attacker-chosen iss in front of ours. Claude’s hosted callback (claude.ai) waits for step 7: a sign-in started in someone else’s claude.ai account and forwarded would look exactly like the person’s own on the consent page. Step 7 first proves with two accounts that claude.ai ties its callback to the account that started the flow, and adds hosted wording to the consent page.
• Consent before Google, and the same browser back, once. Our consent page names the client, where codes go and what Google shares. Approving sets a cookie named for that sign-in (__Host- on https; plain on http, where browsers will not keep a __Host- one), and Google’s callback finishes only in the browser holding it. The first arrival claims the approval in the store, so a refused one (say, a forwarded link) cannot be replayed from a request log; every sign-in also carries the process’s boot ID, so a restart cannot revive one either. The connector itself keeps no access log. The MCP spec requires consent of a connector that signs people in with one fixed Google client for self-registered clients.
• The consent page’s Referrer-Policy is same-origin, never no-referrer: under no-referrer a browser posts the page’s own form with Origin: null and the Origin check refuses it, so nobody can sign in. The unit tests could not see this; a review driving real Chrome and Edge did. tests/connector_kit.py now sends the Origin a browser would.
• Google’s answer is believed only if the ID token verifies against Google’s keys (30 s skew), names our client and Google, carries this sign-in’s nonce, has email_verified: true and an hd equal to the email’s domain. No hd means a personal account made with a work address: refused. The Google code exchange uses PKCE.
• Every redirect back to the client carries iss, equal character for character to the metadata’s issuer (RFC 9207), and the metadata says so. That includes the refusals the SDK’s /authorize sends itself, which our wrapper route completes. After the browser is proven, every outcome reaches the client: a refusal page links back to it.
• Sessions. A Google sign-in starts a session of at most 7 days. Refresh tokens rotate; a retry within 60 s gets the same answer; any other reuse ends the session. Revoking either token, expired or not, ends the session. Every access token names its session and is refused once it ends.
• Memory store fails closed. Codes and sessions live in this process: a restart signs everyone out, and Cloud Run must run one instance (--max-instances 1) until a shared store replaces MemoryStore.
• Data tools are the owner’s alone until step 6’s policy file: they read LAB_OWNER_EMAIL’s accounts, so anyone else allowed to sign in gets whoami only.
• Arguments are checked against the tool’s schema before it runs; the MCP SDK does not. Whole-number floats are passed as integers (JSON Schema counts 5.0 as an integer).
• Record of use: one JSON event per sign-in step and tool call through audit.record(), never arguments, results, tokens or exception messages (an HTTP error’s message holds the request URL, so a Gmail query). Failures log the exception type and file:line only. A call the client abandons is recorded as cancelled, since its thread still reads. Every refusal is recorded too: at registration, /authorize (the SDK’s own included), the consent page, Google’s answer and /token. A failed Google sign-in records a fixed sub-reason (Google’s error code, an ID-token check, the hd and email domains), never Google’s own text, so the first live run can be diagnosed from the log alone. Tests check the record as production writes it (as_written), not pytest’s caplog text, which never shows the audit fields.
• The signing key comes from python -m lab.connector.signer: 48 random bytes plus a checksum, which a typed phrase cannot pass by accident. Anyone can get a signed value from /register and test guesses offline, so the key must be random.

Facts learned the hard way

• mcp 2.x: the low-level Server takes on_list_tools / on_call_tool in its constructor (the 1.x decorators are gone); types are snake_case with camelCase aliases. streamable_http_app’s default host settings reject every non-localhost Host header, which means everything behind Cloud Run (Gwen hit this).
• claude.ai connectors: only Owners can add one on Team/Enterprise; OAuth endpoints get about 10 s, so keep one warm instance; tool calls get about 240 s.
• An adversarial review (2026-10-15, three rounds) ran the connector in real headless Chrome and Edge over CDP and drove it with the MCP SDK’s own OAuth client: both caught what hand-built test requests could not. tests/test_connector_e2e.py keeps the second, and the kit’s browsers now refuse cookies a real browser would drop for their prefix.
• AnthropicVertex accepts middleware=. Vertex has no server-side refusal fallback, so BetaRefusalFallbackMiddleware plus one BetaFallbackState per conversation does it.
• Claude Opus 5.5: thinking cannot be disabled, effort defaults to medium (set it), and forced tool_choice returns 400.
• Vertex Claude quota can be zero in a project that has never used it (429 on the first call; seen in gw-admin-assistant 2026-10-08). The 5.5 models are served on us and global only. Request quota in adam-cos-lab before relying on the Vertex loop.
• hillspire.com is outside the schmidtentity.com GCP organization, so OAuth consent screens here must be External (Testing mode: refresh tokens expire after 7 days).
• mcp 2.3 auth internals: custom routes are appended after the SDK’s own, so replacing an SDK endpoint means inserting a route in front (app.router.routes[0:0]). Its /revoke requires a client_secret field, so it refuses every public client, Claude included; ours replaces it. Its metadata omits "none" and RFC 9207 iss support; ours adds both. It never checks tool arguments against input_schema. A bare AnyHttpUrl gains a trailing slash, while AuthSettings.issuer_url keeps none: build iss from the latter.
• Claude’s OAuth (claude.com/docs/connectors/building/authentication): hosted apps redirect to https://claude.ai/api/mcp/auth_callback; the claude.com “twin” a support article mentions answered 404 on 2026-10-15, so it is not a callback. Discovery, registration and token calls get 10 s; refreshes get 30 s. Rotate refresh tokens for public clients; answer a dead one with invalid_grant. Claude uses CIMD only if the metadata says so, otherwise DCR.
• Claude Code 2.1.263 (checked in its binary, 2026-10-15): registers by DCR as a public client, client_name “Claude Code ()", redirect `http://localhost:/callback`, listening on 127.0.0.1 and reusing its last port when free. It checks `state`, and checks the FIRST `iss` against the metadata issuer before the token exchange; error callbacks are reported without an iss check. It refreshes with 300 s or less left, under a cross-process file lock, retries a failed refresh up to three times with the same token (inside our 60 s window), and re-registers on `invalid_client`. It revokes the refresh token, then the access token, with `client_id` in the body.
• The SDK’s /authorize answers bad scopes, PKCE methods and response types itself, with error and state but no iss: _authorize_route in app.py adds it. Starlette redirects /mcp/ to /mcp from the request’s own scheme (http behind Cloud Run’s TLS), so redirect_slashes is off.
• Google’s hd is believed to be the Workspace organization’s domain. A person whose address is on a secondary domain may then be refused as not_a_workspace_account. Unproven: check on the first live sign-in, and before SCSP, which may need a configured set of domains.
• Starlette 1.7’s TestClient runs on httpx2, not httpx, and refuses non-ASCII header text: send such headers as latin-1 bytes in tests. A second browser on the same app is a second TestClient used without with (the app’s lifespan may run only once).

Working here

<venv python> -m pytest -q -p no:cacheprovider
op run --env-file=secrets.env.tpl -- <venv python> -m lab.cli
<venv python> -m lab.connector            # the connector at http://localhost:8080/mcp

lab/connector/__init__.py maps the connector’s modules to the steps of the sign-in journey; oauth.py’s docstring walks the journey itself. REVIEWS.md holds every finding of the three security reviews, with its fix and the test that pins it: read it before changing anything in lab/connector/.