@zackbart/connecta 0.24.2 → 0.24.3

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.2 | 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.2 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.2 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.2
+### 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zackbart/connecta",
-  "version": "0.24.2",
+  "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.2",
+    "@zackbart/connecta": "0.24.3",
     "quickjs-emscripten": "0.32.0"
   },
   "devDependencies": {