@zackbart/connecta 0.36.1 → 0.37.0

package/documentation/architecture.md

@@ -1199,6 +1199,15 @@ meaning. These facts do not change agent error fields or write outcomes.
 
 ## Configuration
 
+Downstream OAuth browser extensions use `auth.authorizationParams` on
+`remoteMcp()` and `oauth.authorizationParams` on `api()`. Both snapshot and
+validate the string map at construction, reserve protocol/security parameters
+case-insensitively, and add entries only when publishing the consent URL.
+Remote MCP includes canonical sorted entries in its existing client configuration
+binding (omitted and empty maps remain equivalent); static API OAuth retains
+its existing token-endpoint binding. The [auth contract](./auth.md#browser-authorization-parameters)
+owns limits, reserved names, and reconnect requirements.
+
 `ConnectaConfig` is one schema (`src/config.ts`, combinators in
 `src/config-schema.ts`). The same value produces the TypeScript type a
 deployment writes, the unknown-key walk createConnecta runs before reading any
@@ -1210,8 +1219,8 @@ is resolved in place of the caller's object, so no getter or Proxy trap runs;
 an accessor on a config object or array is refused by path, as is an object
 that cannot be inspected. A closed object or record slot takes a plain object
 only: an array or a class instance there is refused by path, unread. String
-maps (static `headers`, `api()`'s `authorizationParams` and
-`tokenRequestHeaders`) are copied the same way and each value must be a
+maps (static `headers`, remote MCP and `api()` OAuth `authorizationParams`,
+and `api()` OAuth `tokenRequestHeaders`) are copied the same way and each value must be a
 string. A discriminated union (`remoteMcp()`'s `auth.type`,
 a provider's `auth.type`) with a missing or unrecognized discriminant throws
 with the valid values. Only plain data is copied. Connectors, modules,
@@ -1744,6 +1753,20 @@ Use the existing stateful fixture vendors and published-edge deployment adapters
   Native transport parity, OAuth and write-provenance suites retain their
   workerd coverage. The shared throwaway RSA key in `test/fixtures/rsa.ts` is
   used by write-provenance and unknown-write-advice fixtures.
+- `test/executor-requests.test.ts` runs overlapping `execute_code` programs
+  as separate workerd requests through the real Worker Loader executor, with
+  real TCP host calls that read their own request's signal. Queued programs
+  and the programs whose release admitted them return their own answers; queue
+  refusals keep the retryable shape. Its fixture applies workerd's request
+  binding of async-context frames, which the pinned runtime predates, through a
+  signal each request owns, so it refuses another request's entry with or
+  without an async-context token, as workerd does; pointing
+  `MINIFLARE_WORKERD_PATH` at a newer workerd runs the native check.
+  `test/executor-native.test.ts` shows that a slot granted just before
+  `close()` never starts a program on the native Worker Loader.
+  `test/request-context.node.test.ts` pins the same wake order and async context
+  on Node for executor and call admission and QuickJS host calls, and gives back
+  grants that shutdown overtook.
 - The request, catalog, auxiliary-call and renewal lifetime
   suites, plus `test/auth-admission-binding.test.ts`, exercise cancellation,
   held native work and garbage collection. These test actual request ownership;
@@ -1770,6 +1793,28 @@ fetch, streams, Web Crypto, lifetime and request-byte behavior, as listed in
 
 ## Optional deployment modules
 
+`/google` (`src/google.ts`) exports the Promise-based
+`googleServiceAccountToken` request-token resolver outside the root graph.
+It reuses `src/providers/_shared/google/service-account.ts` for Web Crypto,
+in-memory token caching and exact-token invalidation, with an absent subject
+for service accounts acting as themselves. Workspace providers keep supplying
+subjects and retain their delegated error guidance. `src/request-token.ts`
+owns the callable resolver contract and optional HTTP-401 invalidation hook;
+`remoteMcp()` invokes it without replaying the failed operation. With
+`auth.principal`, `src/request-principal.ts` reads the admitted caller only
+through `callerOf` (see `src/connector-caller.ts`), refuses callers the policy
+does not accept before resolving, and gives `remoteMcp()` a principal key that
+joins the credential digest, so no client crosses principals. A custom `fetch`
+replaces global fetch and the owned write sender in that connector's transport,
+behind the same redirect wrapper and a same-origin guard.
+`test/remote-mcp-principal-forwarding.test.ts` checks admission, forging,
+client replacement, transport confinement and secrecy on Node, and a real
+service binding on workerd.
+`test/google-service-account-token.test.ts` exercises signing/cache behavior on
+Node and workerd; `test/google-service-account-remote.node.test.ts` checks
+real-socket token/MCP requests, invalidation and one physical attempt per write.
+Operator setup lives in [Google hosted MCP](./auth.md#google-service-account-tokens-and-hosted-mcp).
+
 `createConnecta` takes closed typed `ui`, `vault`, and `activity`
 slots, with factories at `/ui`, `/credentials`, and `/activity`
 and agent tokens at `/auth/access-tokens`. Root exports the contracts, never the implementations, and there
@@ -2004,11 +2049,13 @@ existing execute pipeline, using its request identity and call capabilities.
 The executor seam creates no second request or call owner.
 
 Both built-ins acquire their permits through native admission and return
-execute-once leases with synchronous, idempotent release. A queued standalone
-execution crosses `awaitExecutorLease`'s Promise handoff before host setup, so
-workerd resumes in the waiting request. `execute_code` retains its public
-`acquire()` handoff for that same reason. A cancelled queued handoff withdraws
-its waiter, and a late custom acquisition releases its abandoned lease.
+execute-once leases with synchronous, idempotent release. Admission wakes a
+queued waiter through a Settlement, so it resumes in its own request
+([across requests](#across-requests)). A queued standalone execution also
+crosses `awaitExecutorLease`'s Promise handoff before host setup, and
+`execute_code` retains its public `acquire()` handoff. A cancelled queued
+handoff withdraws its waiter, and a late custom acquisition releases its
+abandoned lease.
 
 The Worker SDK prepares source and dispatchers against an inert loader. The
 native host then acquires the actual Loader handle and RPC entrypoint with
@@ -2024,7 +2071,9 @@ Both built-ins normalize provider leaf returns with `Promise.resolve`, retaining
 direct JavaScript callers' synchronous value tolerance and original host
 rejections. The published provider-function signature remains Promise-shaped.
 
-QuickJS owns host-call fibers in each active run's Scope. Completion,
+QuickJS owns host-call fibers in each active run's Scope, started in the
+async context the run captured: a warm child's IPC events arrive in the
+context of the request that spawned it. Completion,
 interruption, cancellation, recycling and shutdown revoke provider lookup and
 interrupt those fibers; late SDK results and stale IPC cannot reply to another
 run. Releasing a lease during readiness or crash backoff also cancels the old
@@ -2209,24 +2258,40 @@ request's abort handler also releases them idempotently if workerd discards the
 pending continuation on disconnect. Membership cache
 hits precede these bounds; see [organization admission](./auth.md#one-clerk-instance-one-organization-per-deployment).
 
-Asynchronous work shared across requests meets only through a Deferred that the owning
-request completes, never through a fiber that outlives its request. Two
-workerd rules follow, and both have bitten.
-
-**Waiting on a shared Deferred is its own edge.** Deferred resumes a waiting
-fiber synchronously, inside the call that completed it, which on Workers means
-inside the completing request's I/O context. A waiter that goes on to touch its
-own body, transport, or storage there fails with "Cannot perform I/O on behalf
-of a different request", or hangs until its deadline. So the wait runs through
-`runEdge`, and the waiter does its own I/O after awaiting that promise, which
-workerd resumes in the waiter's request as it does any promise resolved from
-another. The same holds one level out for every queue: a queued call, a queued
-`execute_code`, and a queued `/mcp` request are each handed their permit from
-inside the request that released one, so each awaits the controller's
-Promise-shaped `acquire` rather than yielding its Effect program, and does its
-own work only once that promise resolves. Effect's `Semaphore` is not used
-across requests for the same reason, and because a same-tick newcomer can take
-a released permit ahead of a waiter that queued earlier.
+Asynchronous work shared across requests meets only through a `Settlement`
+(`src/runtime/settlement.ts`) that one request settles, never through a fiber
+that outlives its request or a Deferred another request awaits. Two workerd
+rules follow, and both have bitten.
+
+**No request resumes another request's fiber.** Deferred resumes a waiting
+fiber synchronously, inside the call that completed it, and Effect re-enters
+the async context the fiber suspended in through the `AsyncResource` it
+captured. On Workers that context belongs to the waiter's request. Since
+workerd's September 2026 releases, a Worker with compatibility date 2025-06-16
+or later (or `bind_asynclocalstorage_snapshot_to_request`) refuses that entry
+from any other request: "Cannot call this AsyncLocalStorage bound function
+outside of the request in which it was created." The throw escapes the
+completing call, so the request that released an admission slot failed with
+`executor_failed`, and the stranded waiter later timed out (#1106). Older
+runtimes ran the waiter in the completing request instead, where its own I/O
+failed with "Cannot perform I/O on behalf of a different request". Awaiting a
+Promise around the wait fixes neither: the fiber waiting inside that Promise is
+the one resumed. A Settlement records its outcome synchronously, for queue
+arbitration and late-grant cleanup, and wakes each waiter by resolving a
+Promise the waiter's own request created. workerd runs that Promise's reactions
+in the request that created it, and Node runs them a microtask later in the
+waiter's async context. That wake is a turn late, so whatever a waiter acts on
+it rechecks there: an admission queue gives back a grant its controller closed
+in between, while a grant that beat the waiter's own abort stays the waiter's to
+release, and a refresh waiter rechecks its own signal before using a flight's
+answer. Executor admission, `/mcp` request
+admission, connector call admission and OAuth refresh flights all queue through
+Settlements; Effect's `Semaphore` is not used across requests for the same
+reason, and because a same-tick newcomer can take a released permit ahead of a
+waiter that queued earlier. Events from shared native objects follow the same
+rule: a warm QuickJS child's IPC messages arrive in the async context of the
+request that spawned it, so host calls dispatch inside the running program's
+captured context.
 
 **Never read another request's signal.** On workerd, reading `aborted` or
 `reason`, or calling `abort()`, on a signal that belongs to another request

package/documentation/auth.md

@@ -6,16 +6,16 @@
 and package maintenance. This guide owns identity, membership, and downstream
 credential contracts; use [deployment setup](./deploying.md) for runnable steps.
 
-| Task                                                                | Sections                                                                                                                                                                                                                                               |
-| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Connect a machine or migrate an old client                          | [Agent tokens](#agent-tokens-and-upgrading-from-earlier-tokens), [agent endpoints](#agent-endpoints), [static bearer migration](#migrating-static-bearer-clients)                                                                                      |
-| Configure caller visibility, read-only endpoints, or auth ownership | [Principals and operators](#principals-visibility-and-operators), [pools](#pools), [shared and personal auth](#shared-and-personal-auth)                                                                                                               |
-| Lay out an agent's pools                                            | [Organizing an agent's pools](#organizing-an-agents-pools)                                                                                                                                                                                             |
-| Set up human sign-in                                                | [Access on Workers](#cloudflare-access-on-workers), [Clerk tokens and sessions](#clerk-oauth-tokens-and-operator-sessions), [Clerk Organizations](#one-clerk-instance-one-organization-per-deployment), [management](#human-authentication-management) |
-| Enable credential or connection controls                            | [Management permissions](#management-permissions), [start/restart/disconnect](#starting-restarting-and-disconnecting)                                                                                                                                  |
-| Diagnose consent or token refresh                                   | [State at rest](#downstream-oauth-state-at-rest), [callbacks](#consents-and-callbacks), [refresh failures](#refresh-failures), [safe errors](#what-a-servers-errors-may-say)                                                                           |
-| Configure a downstream OAuth client or HTTP handler                 | [Client registration](#downstream-oauth-client-registration), [api() OAuth](#downstream-oauth-on-api), [request-local bearer tokens](#request-local-downstream-bearer-tokens)                                                                          |
-| Review browser or downstream URL boundaries                         | [Origins](#origins), [advertised URLs](#urls-a-downstream-advertises), [one server per grant](#one-server-per-grant)                                                                                                                                   |
+| Task                                                                | Sections                                                                                                                                                                                                                                                                                                      |
+| ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Connect a machine or migrate an old client                          | [Agent tokens](#agent-tokens-and-upgrading-from-earlier-tokens), [agent endpoints](#agent-endpoints), [static bearer migration](#migrating-static-bearer-clients)                                                                                                                                             |
+| Configure caller visibility, read-only endpoints, or auth ownership | [Principals and operators](#principals-visibility-and-operators), [pools](#pools), [shared and personal auth](#shared-and-personal-auth)                                                                                                                                                                      |
+| Lay out an agent's pools                                            | [Organizing an agent's pools](#organizing-an-agents-pools)                                                                                                                                                                                                                                                    |
+| Set up human sign-in                                                | [Access on Workers](#cloudflare-access-on-workers), [Clerk tokens and sessions](#clerk-oauth-tokens-and-operator-sessions), [Clerk Organizations](#one-clerk-instance-one-organization-per-deployment), [management](#human-authentication-management)                                                        |
+| Enable credential or connection controls                            | [Management permissions](#management-permissions), [start/restart/disconnect](#starting-restarting-and-disconnecting)                                                                                                                                                                                         |
+| Diagnose consent or token refresh                                   | [State at rest](#downstream-oauth-state-at-rest), [callbacks](#consents-and-callbacks), [refresh failures](#refresh-failures), [safe errors](#what-a-servers-errors-may-say)                                                                                                                                  |
+| Configure a downstream OAuth client or HTTP handler                 | [Client registration](#downstream-oauth-client-registration), [api() OAuth](#downstream-oauth-on-api), [request-local bearer tokens](#request-local-downstream-bearer-tokens), [principal forwarding](#forwarding-the-admitted-principal), [Google hosted MCP](#google-service-account-tokens-and-hosted-mcp) |
+| Review browser or downstream URL boundaries                         | [Origins](#origins), [advertised URLs](#urls-a-downstream-advertises), [one server per grant](#one-server-per-grant)                                                                                                                                                                                          |
 
 [Credential recognition and admission](#credential-recognition-and-admission)
 defines refusal precedence.
@@ -1336,6 +1336,29 @@ healthy. Restart invalidates it even if the connection ends healthy. Continue
 trusts the stored registration's `redirect_uris`; after changing `publicUrl`,
 Restart registers for the current callback URL.
 
+For `remoteMcp()` OAuth, the owner's stored grant decides whether a connection
+is connected, not whether the downstream answers. Some servers answer
+`initialize` and `tools/list` without credentials and challenge only
+`tools/call`. The operator status, the UI's connected state, and a start agree
+with the gate a call passes:
+
+| Stored grant        | Status                                                      | Start (Connect, Continue, Restart, `authorize_connector`)                                                                                                                                                                                                                          |
+| ------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Disconnected        | `auth_required`; the downstream is not asked                | Replaces the epoch, then proceeds as for no tokens                                                                                                                                                                                                                                 |
+| No tokens           | Connects; `auth_required` even when the downstream answers  | Connects first, so a 401's `resource_metadata` starts consent as before. A downstream that answers without credentials still gets consent, discovered from RFC 9728 metadata at the configured URL's well-known locations. The start answers `auth_required` with the consent URL. |
+| Tokens (any expiry) | Connects; `ok`, or `auth_required` when a 401 needs consent | Connects; `ok` without starting a flow when healthy                                                                                                                                                                                                                                |
+
+A start without a challenge runs the same SDK flow as a 401 without
+`resource_metadata`. Issuer and resource checks, consent state, PKCE, and
+the CIMD, registration, and static-client order are unchanged, and nothing is
+sent to the MCP endpoint. A call never starts consent. A call's 401 that names
+per-tool metadata, such as `/.well-known/oauth-protected-resource/<tool>`,
+renews through it when the grant holds no discovery. That metadata must name
+the configured resource, as any other must. When renewal is refused, the grant
+loses its tokens and the next start hands out consent. Restart (`force: true`)
+removes the tokens first, so it starts consent unless the downstream or
+discovery fails.
+
 ### Consents and callbacks
 
 A start stores its flow record, then the grant's pointer to it. A reset that
@@ -2498,6 +2521,48 @@ stored static-client state and reselects the configured identity.
 Configured `scope` is a fallback; a downstream challenge or protected-resource
 declaration takes precedence, and the SDK adds `offline_access` when advertised.
 
+### Browser authorization parameters
+
+Set `auth.authorizationParams` on an OAuth `remoteMcp()` connector to add
+non-secret provider parameters to the browser consent URL. This works with
+pre-registered clients, CIMD, and DCR. For example:
+
+```ts
+remoteMcp("crm", {
+  url: "https://mcp.example/mcp",
+  auth: {
+    type: "oauth",
+    scope: "records.read",
+    authorizationParams: { access_type: "offline", prompt: "consent" },
+  },
+});
+```
+
+Each configured parameter occurs once, replacing any same-name value already
+on the authorization endpoint URL. These parameters are never added to token
+exchange, refresh, registration, revocation, metadata, or MCP requests.
+Descriptions expose parameter names only. Values are public configuration,
+visible in the consent URL and stored with it; never put secrets here.
+
+The map must be a plain string record with at most 32 entries. Names contain
+1–128 ASCII letters, digits, dots, underscores, or hyphens. Values must be
+nonempty (not whitespace-only), at most 2048 UTF-16 code units, and contain no
+ASCII control characters. Case-variant duplicate names are refused. The
+following names, including every case variant, fail construction with
+`ConfigError`: `response_type`, `response_mode`, `client_id`, `client_secret`,
+`redirect_uri`, `state`, `code_challenge`, `code_challenge_method`, `scope`,
+`resource`, `request`, and `request_uri`. Configure scopes through `auth.scope`.
+`response_mode` is reserved because Connecta accepts callbacks only as GET query
+parameters.
+
+For remote MCP, the map joins the stored client configuration binding, like
+scope and client identity. Adding, removing, or changing a parameter requires
+Restart or Disconnect and reconnect to obtain a grant with the new consent
+settings. The map does not rewrite existing grants or pending consent URLs;
+as with scope, reconfiguring it alone does not obtain a new grant. A DCR
+registration created under different parameters cannot be carried through
+Restart. Key order is irrelevant; an empty map and omission are equivalent.
+
 ## Downstream OAuth on `api()`
 
 `api()` takes a static authorization-code configuration for APIs without MCP
@@ -2532,7 +2597,7 @@ No discovery or registration occurs; all URLs are configuration, so the
 | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | Endpoints                    | Checked at construction: HTTPS, HTTP only on loopback, no credentials or fragment.                                                                                                                                                                                                                                                                                                                                             |
 | `pkce`                       | S256 by default; `false` omits challenge and verifier.                                                                                                                                                                                                                                                                                                                                                                         |
-| `authorizationParams`        | Adds provider parameters; cannot restate the grant's own.                                                                                                                                                                                                                                                                                                                                                                      |
+| `authorizationParams`        | Browser-only string parameters. Exact names `response_type`, `client_id`, `redirect_uri`, `state`, `scope`, `code_challenge`, `code_challenge_method` and `resource` are refused; other names and string values are accepted as before. Remote MCP's [stricter rules](#browser-authorization-parameters) do not apply here.                                                                                                    |
 | `expectedCallbackParameters` | Optional `Readonly<Record<string, string>>` of fixed provider response values. Each configured parameter must occur exactly once with its exact decoded value, after pending-state verification and before issuer validation, flow claims, code exchange, or grant persistence. Missing, duplicate, or mismatched values refuse without exchanging a code or returning parameter values. Omission preserves existing behavior. |
 | `revocationEndpoint`         | Optional trusted HTTPS revocation URL (loopback HTTP allowed), without credentials, query or fragment. Disconnect removes the local grant before one bounded attempt using the configured client. Failure reports `oauth_revocation_failed`; a repeated Disconnect never retries.                                                                                                                                              |
 | `revocationRequestFormat`    | `"form"` by default; `"json"` sends JSON without `token_type_hint`. Requires `revocationEndpoint` when set.                                                                                                                                                                                                                                                                                                                    |
@@ -2585,6 +2650,15 @@ owner's access token as `Authorization: Bearer` with these rules:
 - The answer's `.text()` and `.json()`, clones' too, decode its bytes as UTF-8, so
   workerd never quotes a downstream's Content-Type in its own log.
 
+`api()` already supports `oauth.authorizationParams` through the same OAuth
+provider and browser-only injection. It keeps its existing, more permissive
+validation (see the `api()` option table), so existing configurations still
+construct. Use only GET query response modes with it. Its existing binding remains
+unchanged: the token endpoint identifies the grant; scope, client identity,
+and authorization parameters do not add a stored client configuration binding.
+Changing authorization parameters affects new consents; reconnect to obtain a
+grant with different consent settings.
+
 The grant record and consents, epoch fencing, vault sealing, shared/personal ownership,
 callback state/principal checks, `authorize_connector`, Connect, Restart, and
 Disconnect match `remoteMcp()`. Status calls report a stored grant for the
@@ -2597,12 +2671,26 @@ For providers offering both, deployment config chooses; handlers check `ctx.oaut
 
 `remoteMcp("<id>", { auth: { type: "request", token: async (ctx) => … } })` resolves
 its token before connecting and before reusing a client. The callback receives
-the operation's cancellation context, never an agent-selected credential owner.
+the operation's cancellation context only. It never receives an agent-selected
+credential owner, and without the opt-in below it never receives the caller.
 Only shared ownership is accepted. Tokens remain inside the request's hardened
 transport, are not stored or described, and a changed token replaces the client.
 This mode refuses cleartext non-loopback origins. Optional `auth.headers` carry
 static protocol/catalog controls and cannot set Authorization.
 
+Return the same token for the same caller while it remains valid, and cache a
+minted token until shortly before it expires. A value that changes on every
+resolution replaces the client each time; a change that lands while a call
+connects fails that call with a retryable error.
+
+A resolver may expose `token.invalidate(rejectedToken, ctx): Promise<void>` to
+remove a cached token after a downstream HTTP 401. The hook receives the exact
+token sent by that transport, so it must leave a newer cached token intact.
+Hook failures are withheld and preserve the original 401. Request auth never
+automatically repeats the operation or renews the grant inside the failed
+scope: authorization failure stays latched for that scope. A new request resolves
+the callback again. In particular, no dispatched write is replayed.
+
 The GitHub provider validates each tool's owner/repo and scope access before
 resolving an installation token. It creates one token-bound MCP client for that
 operation and closes it before returning. Completed installation/token caches
@@ -2613,6 +2701,223 @@ is retained across requests, and rejected writes are never replayed. An omitted
 `describe()` includes neither the key nor the minted tokens. The maintained
 provider skill explains App permissions and installation prerequisites.
 
+### Forwarding the admitted principal
+
+Set `auth.principal` instead of `auth.token` to let the resolver act for the
+caller inbound auth admitted. Use it only for a downstream the deployment
+controls and that already trusts this deployment, so the downstream needs no
+per-person OAuth:
+
+```ts
+auth: {
+  type: "request",
+  principal: {
+    accept: "human",
+    token: async (ctx, { principal }) => await notesAssertion(principal),
+  },
+},
+```
+
+- `principal` is `{ kind: "human", namespace, id }`: the admitted person's
+  stable reference, the same `{ namespace, id }` a pool member resolves to.
+  Inbound auth admits no verified email or display name into it; map the id in
+  deployment code or in the downstream when one is needed.
+- `accept: "human"` admits only people. Agents, anonymous callers,
+  principal-less machine credentials and contexts no request admitted are
+  refused with `auth_required` before the resolver runs. Agents still see the
+  connector, and their calls fail. No identity is ever substituted.
+- `accept: "human-or-agent"` also admits declared agents as
+  `{ kind: "agent", name, pool }`, the pool being the one the agent arrived on.
+  An agent is never presented as a person, its pool's owner included.
+- The caller comes only from the authorization that admitted the request.
+  Tool arguments, program code and request headers cannot choose or change it.
+- The principal joins the client's identity. A different principal never
+  reuses a client, connection or connect in flight, even when the resolver
+  returns the same token. `token.invalidate(rejected, ctx, { principal })`
+  receives the principal the rejected token was minted for.
+- Catalog listing needs an admitted caller like any call, and its cache stays
+  partitioned per caller. Operator status and catalog checks carry no caller,
+  so they report `auth_required` without connecting.
+- The connector stays shared. Connecta keeps no per-principal credential state
+  and never stores, logs or describes the principal or the token. `describe()`
+  reports `mode: "request"` as for any request resolver.
+
+#### Over a Workers service binding
+
+Pair principal forwarding with the optional `fetch` to reach a sibling Worker
+through a service binding. Then neither Cloudflare Access, the public internet
+nor a service token lies between the two Workers:
+
+```ts
+const notes = remoteMcp("notes", {
+  url: "https://notes.example.com/mcp",
+  fetch: (input, init) => env.NOTES.fetch(input, init),
+  auth: {
+    type: "request",
+    principal: {
+      accept: "human",
+      token: async (_ctx, { principal }) => await notesAssertion(principal, env.NOTES_ASSERTION_KEY),
+    },
+  },
+});
+```
+
+`notesAssertion` is deployment code. It signs a short-lived assertion naming
+`principal.namespace` and `principal.id` with a key both Workers hold, and
+caches it per principal until shortly before it expires. Over a binding, the
+token may instead be an unsigned principal reference, provided the downstream
+reads it only where the trust rule below holds.
+
+The downstream must accept a forwarded identity only through its binding
+entry point or after verifying the signature. Bind to a named entrypoint, such
+as `{ "binding": "NOTES", "service": "notes", "entrypoint": "Connecta" }` in
+the deployment's Wrangler `services`, and read the identity only in that
+entrypoint. Never accept it on a public route: anyone who can reach that route
+could name any person. A signature verified with a deployment-held key is also
+safe on a public route.
+
+`fetch` carries every MCP request, including handshakes, catalog reads, calls,
+writes and session close. Global fetch is never used for that connector. The
+configured `url` stays the logical origin: its HTTPS rule, cleartext refusal,
+redirect policy and same-origin redirect checks apply unchanged. A request for
+any other origin is refused before it reaches `fetch`. Each request, writes
+included, is handed to `fetch` once with `redirect: "manual"`, and a dispatched
+write is never sent again, so `fetch` must not retry or follow redirects. On
+Node, such writes do not need the owned transport. `fetch` cannot be combined
+with OAuth auth, because discovery, registration and token requests go to
+authorization servers the downstream names.
+
+Contributor evidence: `test/remote-mcp-principal-forwarding.test.ts` runs on
+Node and, through a real service binding, on workerd.
+
+### Google service-account tokens and hosted MCP
+
+Import `googleServiceAccountToken` from `@zackbart/connecta/google` to connect a
+Google hosted MCP server using a service-account JSON key on Node or Workers.
+This optional subpath is outside the root import graph. Supply deployment secrets
+through the environment or platform secret store:
+
+```ts
+import { remoteMcp } from "@zackbart/connecta";
+import { googleServiceAccountToken } from "@zackbart/connecta/google";
+
+const warehouse = remoteMcp("warehouse", {
+  url: "https://bigquery.googleapis.com/mcp",
+  authScope: "shared",
+  auth: {
+    type: "request",
+    token: googleServiceAccountToken({
+      serviceAccount: env.GOOGLE_SERVICE_ACCOUNT_JSON,
+      scopes: ["https://www.googleapis.com/auth/bigquery"],
+    }),
+  },
+});
+
+const warehousePersonal = remoteMcp("warehouse_personal", {
+  url: "https://bigquery.googleapis.com/mcp",
+  authScope: "personal",
+  auth: {
+    type: "oauth",
+    scope: "https://www.googleapis.com/auth/bigquery",
+    authorizationParams: { access_type: "offline", prompt: "consent" },
+    client: {
+      issuer: "https://accounts.google.com",
+      clientId: env.GOOGLE_CLIENT_ID,
+      clientSecret: env.GOOGLE_CLIENT_SECRET,
+      tokenEndpointAuthMethod: "client_secret_post",
+    },
+  },
+});
+```
+
+`serviceAccount` accepts downloaded JSON text or
+`{ clientEmail, privateKey, clientId? }`; `privateKey` is a PKCS#8 RSA PEM of at
+least 2048 bits. `scopes` must be a non-empty array of HTTPS URLs without
+credentials, whitespace, or fragments. Unknown options fail construction with
+`ConfigError`. An optional fixed `subject: "alice@example.com"` requests
+Workspace domain-wide delegation and requires its admin grant. Omit `subject`
+for BigQuery: the signed assertion then has no `sub` and acts as the service
+account itself. See [Google's service-account grant documentation](https://developers.google.com/identity/protocols/oauth2/service-account).
+
+The helper signs RS256 JWT-bearer assertions and exchanges them at Google's fixed
+token endpoint. It keeps only bounded in-memory token entries, partitioned by
+account, key fingerprint, absent-or-present subject and scope set. Concurrent
+mints share a flight; tokens refresh with a one-minute margin. Keys, assertions
+and tokens are never logged, persisted or described. Bearer tokens use request
+auth's existing secret redaction. A 401 evicts only the rejected token; the next
+request mints again. The failed operation is never automatically repeated.
+
+#### Separate agent and people connections
+
+Grant the shared connection to agent pools (including pools used by Eve agents)
+and the personal connection to pools used by people. Add these entries to the
+existing deployment configuration, keeping its inbound auth, executor, vault and
+storage configuration:
+
+```ts
+connectors: [warehouse, warehousePersonal],
+agents: ["assistant"],
+pools: {
+  warehouse_agents: { tools: ["warehouse"], members: ["agent:assistant"] },
+  warehouse_people: { tools: ["warehouse_personal"], members: ["user_alice"] },
+},
+```
+
+Replace `user_alice` with Alice's admitted principal ID. Agents have no principal;
+`authScope: "personal"` connectors never appear for them, even if included in a
+pool's tools. The shared connection uses its fixed service account for every
+member; the personal connection uses each person's own encrypted OAuth grant.
+People connect through `authorize_connector` or their member page. Follow
+[Add a person](#add-a-person), [agent tokens](#agent-tokens-and-upgrading-from-earlier-tokens)
+and [shared credential ownership](#connect-a-shared-credential) for admission and
+pool membership. The request-token connection gets its key from deployment
+configuration and does not need a credential-vault slot.
+
+#### Google-side setup
+
+1. Enable the BigQuery API in the Google Cloud project and confirm that the
+   BigQuery MCP service is available under the project's organization policies.
+   Google's current setup uses `https://bigquery.googleapis.com/mcp` and API
+   enablement; follow its current server setup if enablement requirements change.
+   Grant the service account MCP Tool User (`roles/mcp.toolUser`) and BigQuery
+   Job User (`roles/bigquery.jobUser`) on the project where queries run.
+   [BigQuery MCP setup and required roles](https://docs.cloud.google.com/bigquery/docs/use-bigquery-mcp).
+2. Grant BigQuery Data Viewer (`roles/bigquery.dataViewer`) on the datasets the
+   service account may query. Dataset grants restrict data access separately
+   from project-level job execution. Grant further permissions only for the
+   operations you intend to expose; OAuth scopes do not replace IAM.
+   [BigQuery IAM roles and grant levels](https://docs.cloud.google.com/bigquery/docs/access-control).
+   Create a service-account JSON key and store it as
+   `GOOGLE_SERVICE_ACCOUNT_JSON` in the deployment secret store; the helper
+   does not use ADC, metadata-server credentials, or workload identity federation.
+   [Service-account key creation](https://docs.cloud.google.com/iam/docs/keys-create-delete).
+3. For the personal connection, configure Google Auth Platform branding,
+   audience and data access. Choose **Internal** for an application restricted to
+   people in your Workspace organization, using a project belonging to that
+   organization. Internal consent does not grant dataset access; each person
+   still needs the applicable IAM permissions.
+   [Configure consent and audience](https://developers.google.com/workspace/guides/configure-oauth-consent).
+4. Create a **Web application** OAuth client under Google Auth Platform → Clients.
+   Register the exact Connecta callback, for example
+   `https://connecta.example/oauth/callback/warehouse_personal`, using the
+   deployment's configured public origin. Store its client ID and secret as
+   deployment secrets. Google's hosted MCP servers do not support DCR or client
+   metadata documents, so configure the static `auth.client` shown above.
+   [Web OAuth client setup](https://docs.cloud.google.com/mcp/set-up-authentication-mcp-servers#web),
+   [Google MCP registration limitations](https://docs.cloud.google.com/mcp/authenticate-mcp#limitations).
+
+The pre-registered client path supports Google's exact issuer and
+`client_secret_post`; Google's [discovery document](https://accounts.google.com/.well-known/openid-configuration)
+advertises that method, PKCE S256, and `https://oauth2.googleapis.com/token`.
+The personal example requests `access_type=offline` to obtain a refresh token
+and `prompt=consent` to show consent again when reconnecting. See
+[Google's offline-access requirements](https://developers.google.com/identity/protocols/oauth2/web-server#offline).
+Connecta retains the stored refresh token when a successful refresh response
+omits `refresh_token`, allowing later refreshes with that same token. After
+adding these parameters to an existing connector, Disconnect and reconnect.
+Live Google consent and project-specific permissions still need verification
+against the operator's project.
+
 ## Contributor reference
 
 ### INV-5 output redaction limits

package/documentation/code-mode.md

@@ -65,9 +65,15 @@ createConnecta({ executor: workerExecutor({ loader: env.LOADER }), readOnly: fal
 ```
 
 The adapter uses only `loader` and an optional `timeout`. Its admission defaults
-are two active runs, eight queued runs, and a five-second queue deadline, settable
-through `admission`. Lease release disposes RPC and loader handles independently
-of guest settlement. `bindings`, `modules`, or `globalOutbound` violate `P2`.
+are two active runs, eight queued runs, a 60-second queue deadline (the default
+guest deadline) and a one-second `retryAfterMs` hint. `admission` replaces all
+four: `{ concurrency, maxQueueSize, queueTimeoutMs, retryAfterMs? }`, where an
+omitted `retryAfterMs` equals `queueTimeoutMs`. The pool belongs to the executor
+instance, so a Worker that builds one per isolate bounds each isolate, not the
+deployment or a caller: concurrent requests that land on one isolate share its
+slots, and requests on other isolates do not count. Lease release disposes RPC
+and loader handles independently of guest settlement. `bindings`, `modules`, or
+`globalOutbound` violate `P2`.
 The [Worker example](../examples/worker/README.md#code-mode) has the full setup.
 
 Keep the Worker's optional peer. Unbranded executors throw, including bundled upstream copies.
@@ -981,7 +987,21 @@ payload is refused before parsing and names no address.
 plus a bounded queue with a wait timeout. Overload is a retryable
 `executor_overloaded` carrying `retryAfterMs`; cancellation and shutdown are
 terminal. Admission happens _before_ any catalog or provider is built, so a
-queued request holds no state.
+queued request holds no state. A full queue refuses at once with
+`Executor queue is full.`; a queued run that outlives `queueTimeoutMs` is
+refused with `Executor admission timed out after <n>ms.`. Either arrives as an
+error result whose `structuredContent.error` is
+`{ code: "executor_overloaded", message, retryable: true, retryAfterMs }`, with
+`hostCalls` all zero; the program never started, so retrying it after
+`retryAfterMs` sends nothing twice. Whichever request releases a slot, the
+queued run resumes, builds its providers, makes its host calls and holds its
+sandbox handles in its own request; the releasing request's result is
+unaffected. A slot handed to a queued run is heard a turn after it is granted.
+When the executor closes in that gap, the slot is given back and the run is
+refused with `executor_closed`, so nothing granted before `close()` starts after
+it. A grant that beat the caller's abort stays the caller's, which releases it
+on arrival. A queued run also holds its MCP request permit
+([request admission](./architecture.md#admission-in-two-places)) while it waits.
 
 **L8.** Result, log, host-call, and emission budgets are deployment configuration.
 A call may request `timeoutMs` just as a direct call does; the guest deadline is
@@ -1287,7 +1307,7 @@ rejection, and branded adapter acceptance across module copies.
 | `L1`, `L2`             | `test/guest-api-contract.test.ts` (in-flight call fails `cancelled`), `test/execute.test.ts` (cancels outstanding host calls, discovery included, and refuses discovery after the run; a cancelled wedged executor, or one whose `acquire()` ignores the signal, returns promptly and releases its lease)                                                                                                                                                                                                                       |
 | `L3`, `X1`             | `test/guest-api-contract.test.ts` (short-deadline executors), `test/execute.test.ts` (the watchdog ends a never-settling executor, frees the default pool, spares a slow run, and falls back from an unusable value)                                                                                                                                                                                                                                                                                                            |
 | `L4`, `L8`             | `test/guest-api-contract.test.ts`, `test/execute.test.ts` (shared discovery/call budgets and terminal catch-and-continue loops and queued-write cancellation on both executors), `test/worker-budget-response.node.test.ts` (native handle disposal and admission recovery across completed HTTP responses)                                                                                                                                                                                                                     |
-| `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue)                                                                                                                                                                                                                                                                                                                                                                                    |
+| `L5`, `L7`, `X2`       | `test/quickjs-executor.node.test.ts` (CPU, heap), `test/execute.test.ts` and `test/executor-admission.test.ts` (bounded admission and queue), `test/executor-requests.test.ts` (queued handoffs and refusal shape across separate workerd requests), `test/request-context.node.test.ts` (queued and QuickJS host-call request context)                                                                                                                                                                                         |
 | `L6`, `X10`            | `test/guest-api-contract-quickjs.node.test.ts` and `test/guest-api-contract.test.ts` (whole oversized reads and one-write pageable handles), `test/sqlite-storage.node.test.ts` and `test/kv-to-d1.test.ts` (SQL stash and native D1 fault probes), `test/quickjs-executor.node.test.ts` (bridge and IPC bounds for arguments and result; the address in the over-bound message), `test/quickjs-child-stderr.node.test.ts` (outer reply serialization failure settles the call)                                                 |
 | `V1`–`V4`              | `test/guest-api-contract.test.ts` (dispatched calls, every refusal class including an address no connector owns, the friction each derives, no event for the execution itself), `test/activity.test.ts` (the shared code → friction table, the identity clamp, the one-attempt floor), `test/browser/operator-ui.spec.ts` (identity changes), `test/sql-storage-contract.ts`, run by `test/sqlite-storage.node.test.ts` (historical activity rows still round-trip)                                                             |
 | `V5`, `W9`             | `test/program-writes.test.ts` (unawaited program drain, failed-program accounting), `test/identity-write-journey.node.test.ts` (committed ambiguity, reconciliation and physical writes), `test/invocation-pipeline.test.ts` (the gate after validation, an unrecorded refusal)                                                                                                                                                                                                                                                 |