@zackbart/connecta 0.24.1 → 0.24.3

package/documentation/operations.md

@@ -84,6 +84,7 @@ optional.
 | `executor` | — (required) | the sandbox `execute_code` runs in ([code mode](./code-mode.md#what-an-executor-must-implement)) |
 | `auth?` | none ⇒ open (dev only) | one `InboundAuth` or an array; bearer providers are checked before interactive providers ([inbound auth](./auth.md)) |
 | `identity?` | all visible; auth management denied; interactive activity reads | `{ connectorAccess?, credentialAdministration?, personalConnection?, activityAccess? }` derives separate use and management permissions ([identity](./auth.md#principals-visibility-and-operators)) |
+| `pools?` | none | `{ <name>: { tools, grant? } }` named slices served at `/mcp/<name>`, each intersected with the identity view and denied unless `grant` admits ([pools](./auth.md#pools)) |
 | `storage?` | `memoryStorage()` | connector state, catalogs, and result paging; pass storage explicitly to the optional vault ([storage](./storage-and-credentials.md)) |
 | `publicUrl?` | per-request origin | public base URL; an HTTPS value also redirects inbound HTTP |
 | `logger?` | `console`, prefixed `[connecta]` | `{ debug, info, warn, error }`, or `"silent"` to suppress diagnostic output; independent of activity history |
@@ -230,30 +231,30 @@ in.
 | Suite | Covers |
 | --- | --- |
 | `activity.test.ts` | payload-free delivery: a rejected async write attaches to `waitUntil` instead of throwing, approved destructive calls record under their real entry point, result-size friction records without retaining the result, and a hallucinated connector id or invented identity is clamped so the event still cannot carry a payload |
-| `api-connector.test.ts` | `api()` — kind, description, tool defs, dispatch, default args, unknown tools, handler throws, argument validation, and the construction contract |
+| `api-connector.test.ts` | `api()` — kind, description, tool defs, dispatch, default args, unknown tools, handler throws, argument validation, structured transport diagnostics, and the construction contract |
 | `bearer.test.ts` | constant-time bearer compare, case-insensitive scheme, 401 challenges, and the retired audience options refusing rather than silently unbinding |
 | `branding.test.ts` | branding fallbacks and overrides across the operator shells, OAuth result pages, `/favicon.*`, page titles, and escaping — branding is not an injection vector |
-| `call-admission.test.ts` | connector-scoped per-runtime downstream admission ([call admission](./call-admission.md)): independent partitions, exact rolling-window reset, cancellation that charges no budget, bounded partition state, local-refusal health isolation, one shared limiter across direct and program calls, and payload-free `/health` aggregates |
-| `catalog-drift.test.ts` | `vettedCatalog()`, `detectCatalogDrift()`, and `withVettedCatalog()`; drift on the registry surface and on `/health`; the connector seam projected rather than echoed; and the drift types being public |
-| `catalog.test.ts` | lexical ranking and the compact schema renderer — `const`, `allOf` beside siblings, `$ref`, the depth limit, per-schema caching, and 2020-12 keyword compatibility |
+| `call-admission.test.ts` | connector-scoped per-runtime downstream admission ([call admission](./call-admission.md)): independent partitions, exact rolling-window reset, cancellation that charges no budget, bounded partition state, local-refusal health isolation, direct and program calls sharing the appropriate controller, independent personal budgets, shared budgets, shutdown of both controller kinds, eviction preserving live budgets, and id-free `/health` aggregates |
+| `catalog-drift.test.ts` | `vettedCatalog()`, `detectCatalogDrift()`, and `withVettedCatalog()`; bounded schema-digest depth; drift on the registry surface and on `/health`; the connector seam projected rather than echoed; and the drift types being public |
+| `catalog.test.ts` | lexical ranking and the compact schema renderer: `const`, `allOf` beside siblings, memoized `$ref`, node/depth/byte bounds, truncation flags, declared required-key metadata, typed search argument validation, per-schema caching, and 2020-12 tuples, conditional markers, and dynamic references in search and describe |
 | `clerk.test.ts` | protected-resource metadata, the browser sign-in config, OAuth and session tokens, cached best-effort activity labels with their caps, the hand-applied `azp` rejection, and the `allowedDomains` allowlist including every lookalike that must not be repaired into a match |
 | `cloudflare-access-auth.test.ts` | trusted `ctx.access` human and service identities, absent/error fail-closed behavior, service-token MCP admission without operator mutation, human same-origin mutation, and the Clerk-to-ambient shell switch |
 | `cloudflare-provider.test.ts` | `cloudflare()` API and MCP construction, the code-mode safety manifest, API tool surface, current R2 and KV jurisdictions, useful output declarations, request building, projections including additive provider fields, typed failures, and credential test |
 | `code-first-surface.test.ts` | the seven-tool surface itself — an executor required, every removed option and top-level tool refused, compact always-loaded routing pinned below 1,000 characters, complete on-demand usage served, and no rendering instructions |
 | `codemode-compat.test.ts` | the `Executor` seam staying structurally compatible with `@cloudflare/codemode`'s `DynamicWorkerExecutor`, enforced by `tsc` |
-| `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds failing construction, and unknown own-properties rejected by their complete path before construction does work |
+| `config.test.ts` | the grouped `ConnectaConfig` boundary — each group forwarding to its internals, malformed admission bounds, result stash limits, and origin lists failing construction, open-connector warnings including static API auth, and unknown own-properties rejected by their complete path before construction does work |
 | `credentials.test.ts` | the pure stored-shape classifier (containment, not equality) and the AES-GCM vault: round-trip, ciphertext bound to its connector id, named field sets, masked metadata, wrong-key rejection, deletion, coexistence with OAuth keys |
 | `d1-activity-example.test.ts` | the Worker example's deployment-owned D1 activity store: actor namespace round-trip, payload-free friction reconstructed from the persisted code, and agreement with the package's friction table |
-| `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and generation races, runtime-local rotating-token refresh coordination across request scopes, refresh failure/retry, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality, bounded diagnostics, and HTML escaping |
-| `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, and framing errors |
-| `execute.test.ts` | the code-mode host bridge: identifier sanitization, account titles in program discovery, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
+| `downstream-oauth.test.ts` | `KvOAuthProvider` round-trips and generation races, two eight-scope waves of runtime-local rotating-token refresh, recovery after abort/redirect/invalidation, bounded token reads and revision churn, refresh failure/retry, `auth_required` versus `error`, `startAuth`/`finishAuth`, callback refusal equality and identity-free 401 versus explicit 403, bounded diagnostics, and HTML escaping |
+| `errors.test.ts` | `ConnectorCallError` codes, retryable defaults and overrides, `retryAfterMs` round-trip, typed-over-heuristic classification, `AbortError` as a retryable timeout, sanitized bounded unavailable diagnostics, and framing errors |
+| `execute.test.ts` | the code-mode host bridge: identifier sanitization, account titles in program discovery, MCP-result unwrapping, sandbox provider construction, authenticated thrown-failure framing, shared discovery/call budgets including pre-dispatch refusals, bounded recent-failure matching, empty terminal errors, logs on thrown executor failures, short-message failure matching, fail-closed filtering of destructive and unannotated tools, MCP/code-mode invocation parity, and payload-free describe diagnostics |
 | `execute-emit.test.ts` | `connecta.emit` (M1–M10) — block validation, budgets, the provider, delivery after the result envelope on success only, and the defaults |
 | `executor-admission.test.ts` | the portable bounded FIFO both pools use: active and queue ceilings, stable retryable overload, queue timeout, cancellation removal, idempotent release, shutdown |
-| `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, and response handling |
+| `guarded-fetch.test.ts` | the guarded transport — construction, request building, destination confinement, response handling, bounded no-stream text/JSON reads, sanitized transport diagnostics, and delta-seconds/HTTP-date Retry-After hints |
 | `guest-api-contract.test.ts` | the shared guest contract on the Dynamic Worker, including caught call, typed inline describe recovery, discovery, utility, parallel-call, and budget failure codes; plus the real authority boundary — local `data:` fetch, denied egress, unresolved DNS, empty environment paths, unavailable filesystem/HTTP builtins, and present runtime globals |
-| `identity-scope.test.ts` | identity-derived connector visibility, personal credential isolation, separate shared-auth and personal-auth management permissions, and personal OAuth callback ownership |
+| `identity-scope.test.ts` | identity-derived connector visibility, named pools at `/mcp/<pool>` (grant-gated, intersected with the identity ceiling, identical 404 for undeclared, refused, and throwing grants, construction-time refusals), exact `connector.tool` grants enforced identically across discovery, direct calls, the program host bridge, and the connection UI, fail-closed grant parsing, the once-per-isolate absent-grant warning, personal credential isolation, separate shared-auth and personal-auth management permissions, bearer-subject result isolation without activity namespaces, connector authorization visibility for tool grants, and personal OAuth callback ownership |
 | `linear-provider.test.ts` | the Linear proxy's construction, guide, plan-aware catalog superset, and current workspace, template, and issue-sharing classifications |
-| `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, and offset alignment |
+| `meta-tools-call.test.ts` | registry-backed calls: structured errors, truncation and `get_result`, per-connector result bounds, JSON representation failures, MCP content bounds, offset alignment, runtime-wide stash quotas including pending writes and expiry reclamation, and page-proportional decoding |
 | `meta-tools-search.test.ts` | registry-backed discovery: bounded search with page and address maxima, compact and JSON schemas with constraints, typed describe recovery and suggestions, and structured-result compatibility |
 | `meta-tools.test.ts` | the remaining registry-backed meta-tools: the complete on-demand usage skill, connector-guide selection and summary bounds, stored-credential drift, catalog health, authorization, probe timeouts, and unavailable or unknown browse recovery |
 | `mixpanel-provider.test.ts` | the Mixpanel proxy, its conditional-input guide, destructive metadata fill, and complete 64-tool schema-digest manifest |
@@ -263,21 +264,21 @@ in.
 | `optional-modules.test.ts` | absent modules, UI-free OAuth, fast lists and independent detail deadlines, explicit auth-management grants, invalid-resolver refusal, and passive OAuth consent-state protection |
 | `provider-conventions.test.ts` | the conventions a test can hold: hand-written providers refusing schemas they cannot enforce (H5), their compact discovery schemas staying complete (H7), Cloudflare stating its second pagination convention in the schema (H10), and Notion saying it has no escape hatch (H14) |
 | `provider-registry.test.ts` | all seven maintained providers inside real deployments: boot, description, address, catalog, storage, credential, admission, and activity isolation; plus provider-specific discovery and guide contracts |
-| `registry.test.ts` | construction and id validation, startup warnings, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, and broken-connector isolation |
-| `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, and downstream session termination |
+| `registry.test.ts` | construction and id validation, startup warnings, bounded absent-grant warning state, address resolution, version 2 catalog TTL/persistence/completeness, agent-only stale-while-revalidate with cross-request single-flight shared with blocking reads in both start orders, owned teardown, invalidation/fingerprint guards, blocking diagnostics, broken-connector isolation, and bounded opportunistic memory-storage expiry |
+| `remote-mcp.test.ts` | `remoteMcp()` against an in-process server through the `_transportFactory` seam: passthrough, downstream `isError`, Workers-safe output-schema validation, request-scoped client reuse and at-most-once scope close; plus the real transport's manual redirect policy, destination guard, credential containment, session termination on scope close/rotation/abandonment, bounded JSON-RPC/HTTP error classification, and sanitized transport diagnostics |
 | `remote-mcp-credential.test.ts` | `remoteMcp()` drawing a static key from the connection UI: the declared slot and its refusal of named fields and bad header names, header framing (bearer, bare, and the two `Basic` forms) observed on the wire, an empty slot failing as `auth_required` rather than reaching the downstream, a value carrying a control character refused before framing and absent from every surface — `call_tool`, `status`, the Test result, the payload-free activity event, and the thrown error — rotation replacing the cached client and a connect already in flight while a wiped value fails the next call, the Test action's catalog probe and scope close, the cleartext-destination warning, and the vault and `authorize_connector` handoff end to end |
 | `remote-mcp-pagination.test.ts` | the `tools/list` cursor chain in both directions — exact cursor handoff, first-wins dedup, a failed later page rejecting rather than returning its prefix, the runaway backstops, the tool-metadata re-prime across pages, and paginated catalogs reaching the discovery path |
 | `request-admission.test.ts` | `/mcp` bounded before auth, the stable 503 and `Retry-After`, health and operator responsiveness under saturation, payload-free counters, queued cancellation, shutdown rejection while active work drains, and the separate fallback code pool |
 | `result-shapes.test.ts` | passive output-shape learning: value-free bounded inference, merging, 256-entry LRU eviction, 24-hour expiry, runtime isolation, read-only admission, declared-schema precedence, definition-change invalidation, discovery provenance, and failure isolation |
 | `revenuecat-provider.test.ts` | the RevenueCat proxy's per-project key scoping and account-wide OAuth guides, its purpose-bearing summary, the refund-preference read and argued borderline verdicts in its digest-free manifest, and the deliberately unclassified `render-paywall-screenshot` |
-| `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory, account titles, on-demand investigation guidance, and no Apps metadata or resource capability → complete usage skill → `call_tool`), conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, removed connector HTTP hooks rejected at construction, and deferred catalog reads through both discovery surfaces |
-| `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: built-in routes and unknown-path 404s inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
+| `server.test.ts` | end-to-end `/mcp` (401 → compact initialize instructions → seven compact definitions with bounded connector inventory, account titles, on-demand investigation guidance, and no Apps metadata or resource capability → complete usage skill → `call_tool`), fixed seven-tool registration order across requests, conditional guide pointers, open routes, Clerk `.well-known` metadata without network, code mode, removed connector HTTP hooks rejected at construction, and deferred catalog reads through both discovery surfaces |
+| `server-route-contracts.test.ts` | the route contracts `server.ts` must keep byte-identical: Origin refusal before admission/auth/redirects, exact-origin and wildcard CORS, SEP-2243 preflight headers, all pool suffixes behind auth, application overload/shutdown codes, id-free health preserving doctor drift counts, built-in routes and unknown-path 404s inside the security wrapper, open data-free shells with framing denied, per-route auth and same-origin requirements with exact 401/403/405 bodies, and OAuth `verifyState`-before-`finishAuth` ordering |
 | `startup-warnings.test.ts` | every construction-time `logger.warn` and, as importantly, the conditions that must *not* trigger one: open mode with a credential or OAuth connector, `publicUrl` unset beside OAuth, dropped branding and `uiAuth` URLs, a missing `verifyState`, a credential test-hook mismatch, and an unusable `calls.maxResultBytes` |
 | `stripe-provider.test.ts` | the Stripe proxy's mixed-mode OAuth and fixed-mode header contracts, current eleven-tool classifications, admission, exact account selectors, and no-guess rule |
 | `operator-view.test.ts` | the app's pure state rules from `view.ts`: filtering, page routing, capability states, activity summaries, drift display, and identity reset |
 | `ui-credentials.test.ts` | credential-management routes: save, test, delete, validation, authentication, same-origin checks, and multi-field credential shapes |
 | `ui.test.ts` | the server shell and remaining `/ui/*` routes: gated `/ui/data` with broken-connector isolation and registry-owned catalog-observation containment, plus the URL safety gates |
-| `validate.test.ts` | `validateToolInput()` — a returned (not thrown) `invalid_args` naming the path, `additionalProperties: false` enforcement, per-schema validator caching, and an unusable schema passed through with one warning |
+| `validate.test.ts` | `validateToolInput()` — a returned (not thrown) `invalid_args` naming the path, `additionalProperties: false` enforcement, bounded UTF-8 validation detail, per-schema validator caching, and an unusable schema passed through with one warning |
 | `vercel-provider.test.ts` | `vercel()` API and MCP construction, MCP inventory classification, team scoping, project and deployment projections, finite build and runtime logs, value-safe environment variables, domains, lifecycle writes, REST hatches, typed failures, and credential test |
 
 ### Node-bound (`NODE_ONLY_SUITES`)
@@ -291,15 +292,15 @@ justification for *not* re-running it in workerd, so "it was easier" is not one.
 | `doc-links.test.ts` | the documentation checker itself — local file and fragment resolution, repository URLs resolved back to the checkout, duplicate heading slugs, fenced-code exclusion, and useful failures | spawns the Node checker against filesystem fixtures |
 | `doctor-cli.test.ts` | `connecta doctor`'s executor line and credentials end to end — the sandbox the deployment reports is the one named, an unidentifiable executor gets an executor-neutral line, a hostile name is bounded, and a complete Cloudflare Access service-token pair is accepted while a partial pair is refused | spawns the CLI against a Node HTTP deployment over real sockets |
 | `drift-check.test.ts` | the credential-free maintainer drift checker: recorded touched endpoints, heading, table, and inline MCP inventories, setup-only providers, live-schema ownership, a quiet revision bump, clear failures for unavailable inputs, `$ref` traversal, and one well-formed row per endpoint | spawns the checker against filesystem fixtures |
-| `file-storage.test.ts` | `fileStorage()` across instances, logical TTL plus physical pruning without clobbering a newer value, and corrupt-file quarantine | exercises the Node filesystem storage adapter |
+| `file-storage.test.ts` | `fileStorage()` round trips, exclusive writer locks, namespace-aware heartbeat expiry and stale-guard recovery, close/exit cleanup, unique temp files, logical TTL plus physical pruning, and corrupt-file quarantine | exercises the Node filesystem storage adapter |
 | `guest-api-contract-quickjs.test.ts` | the shared guest-contract cases on the real QuickJS executor, including identical caught failure codes and inline describe recovery, its exact absent globals, and blocked runtime imports | runs the contract cases on the Node QuickJS executor |
 | `node.test.ts` | the `listen()` adapter propagating an HTTP client disconnect through the Web `Request` and the MCP handler into a program's connector call, releasing both admission permits | exercises the Node HTTP adapter over real TCP sockets |
 | `packed-links.test.ts` | the packed-link gate itself — shipped targets and repository URLs accepted, relative links into unshipped paths and directories rejected with the citation to write instead, reference definitions seen, fenced examples ignored, the changelog exempt | spawns the Node packed-link gate against filesystem fixtures |
 | `package-surface.test.ts` | the published boundary — built output shipped, the `exports` map carrying exactly the documented subpaths plus `./package.json`, only generic factories, platform storage kept in examples, Clerk and QuickJS behind optional subpaths, dependency-free Cloudflare Access behind its Worker subpath, every provider independently importable, and the Cloudflare API provider free of bare specifiers | walks the package tree with Node filesystem APIs |
 | `purity.test.ts` | the import-graph guardrail ([architecture](./architecture.md#import-graph-purity)) — the core stays Workers-clean | walks the source import graph with Node filesystem APIs |
 | `quickjs-child-entry.test.ts` | a missing QuickJS child entry failing before `fork()`, with the expected path and the bundler-externalization constraint | mocks Node child-process and filesystem APIs |
-| `quickjs-child-stderr.test.ts` | the QuickJS child-process boundary: an explicitly empty environment despite parent secrets and `NODE_OPTIONS`, plus abnormal exits retaining only an 8 KiB stderr tail in the parent-side diagnostic | mocks Node child-process streams |
-| `quickjs-executor.test.ts` | executable usage example with dependent, missing, and approval-required evidence; the child-process sandbox — code normalization, provider bridges and canonical connector calls, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection | runs the Node QuickJS child-process executor |
+| `quickjs-child-stderr.test.ts` | the QuickJS child-process boundary: an explicitly empty environment despite parent secrets and `NODE_OPTIONS`, abnormal exits retaining only an 8 KiB stderr tail in the parent-side diagnostic, host-result serialization failure returning a bounded error reply, streamed logs on real child crashes, bounded parent retention, and log recovery on shutdown, deadline termination, and IPC failures | mocks Node child-process streams and runs the Node QuickJS child-process executor |
+| `quickjs-executor.test.ts` | executable usage example with dependent, missing, and approval-required evidence; the child-process sandbox — code normalization, provider bridges and canonical connector calls, private authenticated-failure transport and bounded error details, bounded IPC, separate guest-CPU and wall budgets, saturation, cancellation and shutdown, crash and OOM recovery, host-call hangs, stalled-promise detection, logs preserved on cancellation after a program starts | runs the Node QuickJS child-process executor |
 | `quickjs-log-limits.test.ts` | bounded `console.*` capture — per-entry cut, cumulative character and transport budgets, escape-heavy floods preserving the guest result | runs the Node QuickJS child-process executor |
 | `suite-partition.test.ts` | this partition, including itself: every `*.test.ts` in exactly one list, stale entries and empty reasons refused | walks the test directory to guard the partition |
 | `template-file-activity.test.ts` | the Node template's own activity store — persistence across restart, torn-line repair, newest-first paging, and compaction past the slack window | runs it against real files |

package/documentation/provider-conventions.md

@@ -231,6 +231,13 @@ convenient reading. A call that can only fail is refused locally as
 `invalid_args` before the round trip. Provider error prose is never parsed to
 invent a classification.
 
+An unreachable transport may report `unavailable` with optional sanitized
+`details.host` and `details.code`. The host is an HTTP(S) origin only, at most
+253 UTF-8 bytes; the code is an allowlisted runtime network code or `timeout`,
+at most 32 bytes. Omit what the runtime cannot establish. The typed error
+constructor strips URL credentials, paths, queries, and fragments, and drops
+invalid or oversized fields. Transport diagnostics never enter activity records.
+
 **A downstream 404 is `not_found` — when the provider means it.** The code
 exists because the next move is none of the others': you do not wait, you do
 not send the agent to `authorize_connector`, you do not repair the argument

package/documentation/request-admission.md

@@ -15,7 +15,7 @@ it.
 
 ## The pools
 
-Every non-preflight `/mcp` request takes one permit from a deployment-wide FIFO
+Every non-preflight `/mcp` or `/mcp/<pool>` request with an admitted Origin takes one permit from a deployment-wide FIFO
 pool. Initialization, discovery, ordinary calls, and `execute_code` all pay it.
 A program then takes a *second* permit from the deliberately smaller code pool,
 so one request cannot trade ordinary capacity for an unbounded number of
@@ -54,6 +54,38 @@ identity rules give its principals different connector views
 ([`ethos.md`](../ethos.md)), so a global queue is not pretending to supply
 something it does not.
 
+## Origin before admission
+
+MCP checks `Origin` before redirects, request admission, auth, and preflight.
+A present, disallowed origin gets HTTP 403 with the exact body
+`{"error":"origin not allowed"}` and `Cache-Control: no-store`. This local
+check consumes no permit or auth lookup, even when the queue is full or closed.
+Requests without Origin, including ordinary non-browser MCP clients, pass.
+`/health`, OAuth callbacks, and auth metadata retain their existing behavior.
+
+`allowedOrigins` accepts a list of exact HTTP(S) origins or `"*"`. An explicit
+list replaces the defaults, including loopback; an empty list admits only
+originless clients. By default the configured `publicUrl` origin and HTTP(S)
+loopback origins at any port are admitted. Loopback means `localhost`,
+`127.0.0.0/8`, or `[::1]`. Without `publicUrl`, only loopback is admitted.
+The inbound Host header never chooses a trusted browser origin. Invalid list
+entries, including paths, credentials, and opaque origins, refuse construction.
+
+```ts
+createConnecta({
+  publicUrl: "https://connecta.example",
+  allowedOrigins: ["https://connecta.example", "https://client.example"],
+  // …
+});
+```
+
+For unrestricted browser access, set `allowedOrigins: "*"` explicitly. Otherwise
+MCP responses reflect an admitted Origin and carry `Vary: Origin`; originless
+and refused requests have no `Access-Control-Allow-Origin`. Allowed preflight
+returns 204 without auth or admission. The SDK validates SEP-2243 parameter
+headers, so preflight echoes valid requested `mcp-param-*` names alongside the
+fixed MCP header list and varies by `Access-Control-Request-Headers` too.
+
 ## Admission before auth
 
 `/mcp` acquires its permit *before* running the auth gate. This looks backwards
@@ -86,7 +118,7 @@ CORS headers, and a stable JSON-RPC error:
   "jsonrpc": "2.0",
   "id": null,
   "error": {
-    "code": -32001,
+    "code": -31001,
     "message": "Server capacity is exhausted. Retry later.",
     "data": { "code": "server_overloaded", "retryable": true, "retryAfterMs": 1000 }
   }
@@ -94,8 +126,10 @@ CORS headers, and a stable JSON-RPC error:
 ```
 
 `Retry-After` is that hint rounded up to at least one whole second. It is
-advice, not a reservation. Shutdown uses `-32002` / `server_shutting_down` and
-is not retryable. Code-pool overload never reaches this layer: it surfaces as
+advice, not a reservation. Shutdown uses `-31002` / `server_shutting_down` and
+is not retryable. These application codes sit outside JSON-RPC's reserved
+range: MCP forbids new allocations in the legacy `-32000..-32019` range.
+Code-pool overload never reaches this layer: it surfaces as
 an ordinary MCP tool error with `executor_overloaded`, `retryable: true`, and
 the executor's own `retryAfterMs`.
 

package/documentation/storage-and-credentials.md

@@ -43,6 +43,57 @@ permissions default to none. Saving, testing, replacing, or removing a value
 never returns it. The vault is read for each call, so a saved replacement takes
 effect without restarting the deployment.
 
+## Result storage
+
+Direct-call result paging uses the same KV interface with a 15-minute TTL.
+`results.maxStashBytes` defaults to 8 MiB of stored paging envelopes, including
+base64 overhead; `results.maxStashEntries` defaults to 64. Both are
+non-negative safe integers, and zero disables stashing. One registry accounts
+for all subjects and reserves capacity for pending writes. A full stash keeps
+the successful call's preview and returns a paging-unavailable notice, without
+a result id. Expired entries are deleted on later stash attempts before their
+capacity is reused, even when the backend only expires entries on read.
+A deletion failure keeps the reservation. Limits apply to writes by one
+runtime; they do not coordinate other processes or Worker isolates, or count
+entries left by a previous runtime.
+
+The memory store also checks up to 16 existing keys on each `set`, rotating
+through live keys so expired entries that nobody reads are eventually removed.
+There are no timers or background sweeps. Paging values use an ASCII base64
+envelope so only the requested bytes need decoding after the KV read. The
+storage adapter's format and interface stay unchanged.
+
+## File storage
+
+`fileStorage` is a single-process development store. It loads one snapshot and
+rewrites the whole state synchronously on each mutation, including result
+stashes. It acquires an exclusive `<path>.lock` before loading, so a second
+instance or process opening the same path fails with the holder's pid instead
+of overwriting a stale snapshot. An unref'd timer refreshes the lock's mtime
+every 15 seconds. A heartbeat older than 60 seconds expires regardless of pid,
+so a container restart cannot leave a reused pid holding the file forever.
+The lock records the host/PID namespace as well as the pid. Within that same
+namespace, a dead pid permits immediate recovery; a matching current pid is
+live only when the in-process registry owns that lock. Other namespaces and
+older locks without namespace metadata rely on heartbeat expiry.
+
+Recovery uses a serialized `.lock.reclaim` guard, which also expires after
+60 seconds if its process crashes or pauses. An incomplete lock likewise
+becomes recoverable after 60 seconds. A holder paused long enough to lose its
+lock fails subsequent writes with "lock was lost". Writes check ownership
+before changing state and again before rename; reads use the loaded snapshot
+without filesystem lock checks. This remains an advisory development store
+on a shared local filesystem, not a distributed storage adapter.
+
+The returned store's `close()` releases the lock and refuses further operations.
+Process exit also releases it, including Node `listen()`'s SIGTERM/SIGINT
+shutdown. Each write uses a unique, exclusively created temp file, and the
+state file's JSON format is unchanged.
+
+Expired entries are removed before each write. Large direct-call results therefore increase both
+retained state and write cost. Use `execute_code` to reduce read-only results
+before returning them, and choose a storage adapter suited to the deployment.
+
 ## Storage continuity
 
 This module extraction changes no encrypted record keys, owner partitions, or
@@ -74,7 +125,9 @@ Personal connectors disappear from a request that has no stable human
 principal. For a principal that can see one, connecta partitions connector
 storage, encrypted vault records, catalog caches, OAuth generations, and
 observed result shapes under an opaque SHA-256 identity key. Results used by
-`get_result` are partitioned by the authenticated subject, so one authenticated subject cannot page another subject's call.
+`get_result` are partitioned by the authenticated subject independently of
+activity configuration. Open deployments and providers that supply no identity
+share one results partition. See [the partition and paging contract](./meta-tools.md#result-representation).
 
 Literal `auth: { type: "headers" }` cannot be personal because its secret lives
 in deployment code. `remoteMcp()` refuses that combination at construction.

package/documentation/upgrading.md

@@ -117,7 +117,7 @@ exist so far:
 | --- | --- | --- |
 | **pre-template** | before 0.10.2 | no `connecta init` existed; hand-written, or copied from the retired `examples/node` |
 | **A** | 0.10.2 – 0.15.1 | `.env.example`, `.gitignore`, `AGENTS.md`, `CLAUDE.md`, `README.md`, `package.json`, `src/index.ts`, `tsconfig.json` |
-| **B** | 0.16.0 – 0.24.1 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
+| **B** | 0.16.0 – 0.24.3 | adds `.dockerignore`, `Dockerfile`, `docker-compose.yml`, and `src/file-activity.ts`; `src/index.ts` grows the four commented operator blocks; `.env.example` ships `CONNECTA_TOKEN=` empty |
 
 Generation A is a decade in template years and identifying it precisely does
 not matter, because you are about to reconstruct it exactly rather than guess
@@ -190,7 +190,7 @@ Generate the *current* template beside the base you already made, into the same
 `$SCRATCH`:
 
 ```sh
-(cd "$SCRATCH" && npx @zackbart/connecta@0.24.1 init current)
+(cd "$SCRATCH" && npx @zackbart/connecta@0.24.3 init current)
 ```
 
 You now have a three-way merge with a real base: `$SCRATCH/base` is what this
@@ -246,7 +246,7 @@ A deployment older than 0.10.2 has no base to diff against. Do not try to
 manufacture one. Instead:
 
 1. `SCRATCH=$(mktemp -d)`, then
-   `(cd "$SCRATCH" && npx @zackbart/connecta@0.24.1 init current)` — there is no
+   `(cd "$SCRATCH" && npx @zackbart/connecta@0.24.3 init current)` — there is no
    `base` leg here, only the current template to read from.
 2. Copy `$SCRATCH/current` into the deployment file by file, **skipping
    `src/index.ts`**.
@@ -267,7 +267,21 @@ first, so cross them bottom-up: start at the oldest one still above this
 deployment's pin and work back up the page, because each boundary assumes the
 older ones are already done.
 
-### 0.23.0 → 0.24.1
+### 0.23.0 → 0.24.3
+
+0.24.3 validates the browser `Origin` header on `/mcp`. A browser MCP client
+hosted on an origin other than `publicUrl` or loopback now gets a 403 until
+the deployment lists it in `allowedOrigins` (or sets `"*"` to keep the old
+open CORS); clients that send no `Origin`, which is every server-side and CLI
+client, are unaffected. The overload and shutdown JSON-RPC error codes moved
+from `-32001`/`-32002` to `-31001`/`-31002`; the `data.code` strings are
+unchanged. See [request admission](./request-admission.md#origin-before-admission).
+`fileStorage` now holds an exclusive lock on its state file: a second process
+opening the same file fails at construction, so a deployment that shared one
+file between two processes must give each its own. The returned store gained
+`close()`. `get_result` stashes are bounded per runtime by the new `results`
+config (8 MiB and 64 entries by default) and partitioned by any authenticated
+subject, not only by providers that declare an activity namespace.
 
 Use the [optional-module migration](./optional-modules-upgrade.md) to select
 modules, grant auth-management permissions, and migrate issued-token clients.
@@ -275,7 +289,9 @@ Preserve storage, encryption keys, and identity namespaces. 0.24.1 adds two
 optional settings, `execute.maxHostCalls` and `execute.hostCallTimeoutMs`, for
 deployments whose providers legitimately run past the 20-call and 15-second
 `execute_code` defaults, and one bounded `warn` log line per failed connector
-call; neither needs migration.
+call; neither needs migration. 0.24.2 adds tool-level
+`connectorAccess` grants and optional named pools at `/mcp/<pool>`; a
+deployment that declares neither is unchanged. See [pools](./auth.md#pools).
 
 ### 0.22.3 → 0.23.0
 

package/ethos.md

@@ -60,7 +60,7 @@ subsystem guides and the CHANGELOG.
 | `connecta.batch` | removed | JavaScript promises suffice |
 | Automatic direct-call retries | removed | callers own retry timing |
 | Connector HTTP routes | removed | deployments own custom routes |
-| Caller-selected toolkits | removed | only config may derive an identity's connector view ([#178](https://github.com/zackbart/connecta/issues/178)) |
+| Caller-selected toolkits | removed | config derives every view; config-declared, grant-gated pools at `/mcp/<pool>` are not caller-selected ([#178](https://github.com/zackbart/connecta/issues/178), [#531](https://github.com/zackbart/connecta/issues/531)) |
 | Proactive credential liveness | removed | fail-at-use is enough ([#179](https://github.com/zackbart/connecta/issues/179)) |
 | Classic (executor-free) surface | removed | an executor is mandatory ([#273](https://github.com/zackbart/connecta/issues/273)) |
 | Per-result lexical query coverage | removed | did not earn its response bytes in a precommitted gate ([#323](https://github.com/zackbart/connecta/issues/323)) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.24.1",
+  "version": "0.24.3",
   "type": "module",
   "sideEffects": false,
   "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of seven meta-tools.",

package/templates/node/package.json

@@ -15,7 +15,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zackbart/connecta": "0.24.1",
+    "@zackbart/connecta": "0.24.3",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {