@zackbart/connecta 0.24.1 → 0.24.3

package/dist/storage/file.js

@@ -1,11 +1,263 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
-import { dirname } from "node:path";
+import { chmodSync, closeSync, existsSync, futimesSync, mkdirSync, openSync, readFileSync, readdirSync, readlinkSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { hostname } from "node:os";
+import { dirname, resolve } from "node:path";
+const HEARTBEAT_MS = 15_000;
+const STALE_LOCK_MS = 60_000;
+const localLocks = new Map();
+// A pid is meaningful only in its own host/namespace. Container hostnames may
+// be shared, so Linux uses the kernel boot id and the actual PID namespace.
+const pidScope = (() => {
+    if (process.platform !== "linux")
+        return hostname();
+    try {
+        return `${readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim()}:${readlinkSync("/proc/self/ns/pid")}`;
+    }
+    catch {
+        return undefined; // Without namespace evidence, rely on the heartbeat.
+    }
+})();
+function stale(path) {
+    return Date.now() - statSync(path).mtimeMs > STALE_LOCK_MS;
+}
+// One listener per module, removed when the last store closes. Node's listen()
+// drains requests before process.exit(), so the lock lasts through those writes.
+const openStores = new Set();
+const closeStores = () => {
+    for (const close of openStores) {
+        try {
+            close();
+        }
+        catch {
+            // A dead-pid or expired-heartbeat lock can be reclaimed next startup.
+        }
+    }
+};
+function hasCode(error, code) {
+    return error?.code === code;
+}
+function lockFile(path) {
+    const lockPath = `${path}.lock`;
+    const contents = JSON.stringify({
+        pid: process.pid,
+        pidScope,
+        createdAt: Date.now(),
+        id: randomUUID(),
+    });
+    const readLock = () => {
+        try {
+            return readFileSync(lockPath, "utf8");
+        }
+        catch (error) {
+            if (hasCode(error, "ENOENT"))
+                return null;
+            throw error;
+        }
+    };
+    const refuseLiveHolder = () => {
+        const raw = readLock();
+        if (raw === null)
+            return false;
+        try {
+            if (stale(lockPath))
+                return true;
+        }
+        catch (error) {
+            if (hasCode(error, "ENOENT"))
+                return false;
+            throw error;
+        }
+        let holder;
+        try {
+            holder = JSON.parse(raw);
+            if (!holder || !Number.isInteger(holder.pid) || holder.pid <= 0 ||
+                holder.pid > 2147483647 || !Number.isFinite(holder.createdAt)) {
+                throw new Error("Invalid lock holder");
+            }
+        }
+        catch {
+            throw new Error(`[connecta] state file ${path} has an unreadable lock at ${lockPath}. ` +
+                `Refusing to start. Retry after its heartbeat has been stale for 60 seconds.`);
+        }
+        if (pidScope !== undefined && holder.pidScope === pidScope) {
+            if (holder.pid === process.pid) {
+                // A new container process may inherit the old holder's pid. Only our
+                // own registry can distinguish that incarnation from a second opener.
+                if (localLocks.get(path) !== raw)
+                    return true;
+            }
+            else {
+                try {
+                    process.kill(holder.pid, 0);
+                }
+                catch (error) {
+                    if (hasCode(error, "ESRCH"))
+                        return true;
+                    // Permission errors do not establish that the holder is dead.
+                }
+            }
+        }
+        throw new Error(`[connecta] state file ${path} is held by pid ${holder.pid} ` +
+            `(lock timestamp ${holder.createdAt}). Close that store before opening another.`);
+    };
+    const acquire = () => {
+        let fd;
+        try {
+            fd = openSync(lockPath, "wx", 0o600);
+        }
+        catch (error) {
+            if (hasCode(error, "EEXIST"))
+                return false;
+            throw error;
+        }
+        try {
+            writeFileSync(fd, contents);
+            const now = new Date();
+            futimesSync(fd, now, now);
+        }
+        catch (error) {
+            unlinkSync(lockPath);
+            throw error;
+        }
+        finally {
+            closeSync(fd);
+        }
+        return true;
+    };
+    if (!acquire()) {
+        refuseLiveHolder();
+        // Serialize stale-lock removal. Without this guard, two reclaimers could
+        // both observe the dead pid and the slower one unlink the new live lock.
+        // Recovery is synchronous. A guard older than the lease is from a crashed
+        // or paused reclaimer, which must recheck its ownership before continuing.
+        const reclaimPath = `${lockPath}.reclaim`;
+        const recoveryError = () => new Error(`[connecta] state file ${path} has a lock recovery in progress at ${reclaimPath}. ` +
+            `Retry after its 60-second lease expires.`);
+        try {
+            const expired = statSync(reclaimPath);
+            if (Date.now() - expired.mtimeMs > STALE_LOCK_MS) {
+                const markers = readdirSync(reclaimPath);
+                const current = statSync(reclaimPath);
+                if (current.dev !== expired.dev || current.ino !== expired.ino ||
+                    current.birthtimeMs !== expired.birthtimeMs || !stale(reclaimPath)) {
+                    throw recoveryError();
+                }
+                // Delete only the expired owner's unique marker. A competing cleanup
+                // cannot empty a replacement guard by deleting these old filenames.
+                for (const marker of markers)
+                    rmSync(`${reclaimPath}/${marker}`, { force: true });
+                rmdirSync(reclaimPath);
+            }
+        }
+        catch (error) {
+            if (hasCode(error, "ENOTEMPTY") || hasCode(error, "EEXIST"))
+                throw recoveryError();
+            if (!hasCode(error, "ENOENT"))
+                throw error;
+        }
+        try {
+            mkdirSync(reclaimPath, { mode: 0o700 });
+        }
+        catch (error) {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+            throw recoveryError();
+        }
+        const guard = statSync(reclaimPath);
+        const markerPath = `${reclaimPath}/${randomUUID()}`;
+        const ownsGuard = () => {
+            try {
+                const current = statSync(reclaimPath);
+                return current.dev === guard.dev && current.ino === guard.ino &&
+                    existsSync(markerPath);
+            }
+            catch (error) {
+                if (hasCode(error, "ENOENT"))
+                    return false;
+                throw error;
+            }
+        };
+        const assertGuard = () => {
+            if (!ownsGuard() || stale(reclaimPath))
+                throw recoveryError();
+        };
+        try {
+            writeFileSync(markerPath, "", { flag: "wx", mode: 0o600 });
+            if (!ownsGuard())
+                throw recoveryError();
+            const now = new Date();
+            utimesSync(reclaimPath, now, now);
+            const removeStale = refuseLiveHolder();
+            assertGuard();
+            if (removeStale)
+                unlinkSync(lockPath);
+            if (!acquire()) {
+                refuseLiveHolder();
+                throw new Error(`[connecta] state file ${path} lock changed during recovery. Retry opening it.`);
+            }
+        }
+        finally {
+            const owned = ownsGuard();
+            rmSync(markerPath, { force: true });
+            if (owned)
+                rmdirSync(reclaimPath);
+        }
+    }
+    const assertHeld = () => {
+        if (readLock() !== contents) {
+            throw new Error(`[connecta] state file ${path} lock was lost. Refusing to write a stale snapshot.`);
+        }
+    };
+    localLocks.set(path, contents);
+    const heartbeat = setInterval(() => {
+        try {
+            assertHeld();
+            const now = new Date();
+            utimesSync(lockPath, now, now);
+        }
+        catch {
+            // A replaced lock belongs to its new holder. Failed refreshes let the
+            // lease expire; subsequent writes still have to prove ownership.
+            clearInterval(heartbeat);
+        }
+    }, HEARTBEAT_MS);
+    heartbeat.unref();
+    return {
+        assertHeld,
+        release() {
+            clearInterval(heartbeat);
+            if (localLocks.get(path) === contents)
+                localLocks.delete(path);
+            if (readLock() === contents)
+                unlinkSync(lockPath);
+        },
+    };
+}
 /**
  * JSON-file-backed KVStorage for Node. Loads once, persists on every write via
- * a temp-file + rename (atomic-ish). Only reachable via the "@zackbart/connecta/node"
+ * an exclusive temp-file + rename. Refuses a second holder of the same path.
+ * Call close() when finished to release its lock; process exit also releases it.
+ * Only reachable via the "@zackbart/connecta/node"
  * subpath so the main entry stays Workers-clean.
  */
 export function fileStorage(path, opts = {}) {
+    path = resolve(path);
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const lock = lockFile(path);
+    let closed = false;
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        openStores.delete(close);
+        if (!openStores.size)
+            process.removeListener("exit", closeStores);
+        lock.release();
+    };
+    const assertOpen = () => {
+        if (closed)
+            throw new Error(`[connecta] state file ${path} is closed.`);
+    };
     const logger = opts.logger ?? console;
     // The state file holds downstream OAuth access/refresh tokens in cleartext,
     // so keep it owner-only. Repair is best-effort: chmod is a no-op or throws on
@@ -20,51 +272,68 @@ export function fileStorage(path, opts = {}) {
         }
     };
     let data = {};
-    if (existsSync(path)) {
-        tighten();
-        try {
-            data = JSON.parse(readFileSync(path, "utf8"));
-        }
-        catch (error) {
-            // Never let a damaged state file be silently replaced by an empty one:
-            // the next set() would persist {} over irreplaceable downstream OAuth
-            // tokens and credential-vault entries. Quarantine the bytes so they
-            // survive for manual recovery, and refuse to start if even that fails —
-            // losing the file loudly beats losing it quietly.
-            const quarantine = `${path}.corrupt-${Date.now()}`;
+    try {
+        if (existsSync(path)) {
+            tighten();
             try {
-                renameSync(path, quarantine);
+                data = JSON.parse(readFileSync(path, "utf8"));
             }
-            catch (renameError) {
-                throw new Error(`[connecta] state file ${path} is not valid JSON and could not be ` +
-                    `moved aside (${String(renameError)}). Refusing to start rather ` +
-                    `than overwrite it. Move or repair the file, then restart.`);
+            catch (error) {
+                // Never let a damaged state file be silently replaced by an empty one:
+                // the next set() would persist {} over irreplaceable downstream OAuth
+                // tokens and credential-vault entries. Quarantine the bytes so they
+                // survive for manual recovery, and refuse to start if even that fails —
+                // losing the file loudly beats losing it quietly.
+                const quarantine = `${path}.corrupt-${Date.now()}`;
+                try {
+                    renameSync(path, quarantine);
+                }
+                catch (renameError) {
+                    throw new Error(`[connecta] state file ${path} is not valid JSON and could not be ` +
+                        `moved aside (${String(renameError)}). Refusing to start rather ` +
+                        `than overwrite it. Move or repair the file, then restart.`);
+                }
+                logger.error(`[connecta] state file ${path} is not valid JSON ` +
+                    `(${error instanceof Error ? error.message : String(error)}) — ` +
+                    `moved to ${quarantine}, starting from empty state. Downstream ` +
+                    `OAuth connectors must be re-authorized and stored credentials ` +
+                    `re-entered.`);
+                data = {};
             }
-            logger.error(`[connecta] state file ${path} is not valid JSON ` +
-                `(${error instanceof Error ? error.message : String(error)}) — ` +
-                `moved to ${quarantine}, starting from empty state. Downstream ` +
-                `OAuth connectors must be re-authorized and stored credentials ` +
-                `re-entered.`);
-            data = {};
         }
     }
+    catch (error) {
+        close();
+        throw error;
+    }
+    if (!openStores.size)
+        process.on("exit", closeStores);
+    openStores.add(close);
     const persist = () => {
         // Physical expiry rides on an operation that was already going to write.
-        // A read must not flush this instance's load-once snapshot: another live
-        // instance may have written newer unrelated values since we loaded it.
+        // Reads only prune memory; they do not rewrite the state file.
         const now = Date.now();
         for (const [key, entry] of Object.entries(data)) {
             if (entry.exp && now > entry.exp)
                 delete data[key];
         }
-        const dir = dirname(path);
-        if (dir)
-            mkdirSync(dir, { recursive: true, mode: 0o700 });
-        const tmp = `${path}.tmp`;
+        const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
         // 0o600 on the tmp file; the atomic rename below preserves it, so the live
         // state file is never briefly world-readable.
-        writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
-        renameSync(tmp, path);
+        const fd = openSync(tmp, "wx", 0o600);
+        try {
+            try {
+                writeFileSync(fd, JSON.stringify(data));
+            }
+            finally {
+                closeSync(fd);
+            }
+            lock.assertHeld();
+            renameSync(tmp, path);
+        }
+        finally {
+            rmSync(tmp, { force: true });
+        }
         tighten();
     };
     const fresh = (key) => {
@@ -78,10 +347,16 @@ export function fileStorage(path, opts = {}) {
         return e;
     };
     return {
+        close,
         async get(key) {
+            // Reads use the loaded snapshot; only writes need filesystem ownership
+            // checks to prevent a reclaimed holder from overwriting newer state.
+            assertOpen();
             return fresh(key)?.value ?? null;
         },
         async set(key, value, opts) {
+            assertOpen();
+            lock.assertHeld();
             data[key] = {
                 value,
                 ...(opts?.ttlSeconds
@@ -91,10 +366,13 @@ export function fileStorage(path, opts = {}) {
             persist();
         },
         async delete(key) {
+            assertOpen();
+            lock.assertHeld();
             delete data[key];
             persist();
         },
         async list(prefix) {
+            assertOpen();
             return Object.keys(data)
                 .filter((key) => Boolean(fresh(key)) && key.startsWith(prefix))
                 .sort();

package/dist/storage/memory.js

@@ -1,11 +1,12 @@
 /** In-memory KV store with expiry. The default for dev and Node. */
 export function memoryStorage() {
     const map = new Map();
+    let sweep = map.keys();
     const fresh = (key) => {
         const e = map.get(key);
         if (!e)
             return null;
-        if (e.exp && Date.now() > e.exp) {
+        if (e.exp !== undefined && Date.now() >= e.exp) {
             map.delete(key);
             return null;
         }
@@ -16,6 +17,16 @@ export function memoryStorage() {
             return fresh(key)?.value ?? null;
         },
         async set(key, value, opts) {
+            // Rotate through at most 16 existing keys. Live entries cannot keep an
+            // expired tail resident forever, and no request starts a background job.
+            for (let i = 0; i < 16; i++) {
+                const next = sweep.next();
+                if (next.done) {
+                    sweep = map.keys();
+                    break;
+                }
+                fresh(next.value);
+            }
             map.set(key, {
                 value,
                 ...(opts?.ttlSeconds

package/dist/validate.js

@@ -1,5 +1,5 @@
 import { Validator } from "@cfworker/json-schema";
-import { ConnectorCallError } from "./errors.js";
+import { boundedEchoText, ConnectorCallError } from "./errors.js";
 import { MAX_ARGUMENT_VALIDATION_ISSUES } from "./errors.js";
 // Lazy validator cache keyed by the schema object itself; null marks a schema
 // the validator rejected (warned once, then passed through rather than
@@ -250,10 +250,10 @@ export function validateToolInput(schema, args, opts) {
     if (result && !result.valid) {
         const units = normalizedValidationUnits(schema, result.errors);
         const nestedUnits = units.filter((unit) => unit.instanceLocation !== "#");
-        const detail = (nestedUnits.length > 0 ? nestedUnits : units)
+        const detail = boundedEchoText((nestedUnits.length > 0 ? nestedUnits : units)
             .slice(0, MAX_ARGUMENT_VALIDATION_ISSUES)
             .map((unit) => `${unit.instanceLocation}: ${agentFacingValidationError(unit)}`)
-            .join("; ");
+            .join("; "), 256);
         return new ConnectorCallError("invalid_args", `Invalid arguments for "${opts.address}": ${detail || "input does not match the tool's inputSchema"}`, { validation: validationDetails(schema, units) });
     }
     return null;

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export declare const CONNECTA_VERSION = "0.24.1";
+export declare const CONNECTA_VERSION = "0.24.3";

package/dist/version.js

@@ -4,4 +4,4 @@
  * a bump that forgets this file fails the build rather than shipping a stale
  * version to `/health` and to downstream MCP handshakes.
  */
-export const CONNECTA_VERSION = "0.24.1";
+export const CONNECTA_VERSION = "0.24.3";

package/documentation/architecture.md

@@ -29,6 +29,15 @@ removes only its own wait. The owner's request signal belongs to its token
 fetch. Cancelling that owner fails current joiners too because promoting one
 could replay a refresh token the authorization server already consumed.
 
+A valid token response is a consumed refresh token whether or not the owner
+survives to save it. The coordinator therefore keeps the accepted tokens on the
+flight, and when the owner fails after that response — cancelled, redirected
+to authorization, or invalidated — it persists the rotation on the host's own
+write, holds contenders behind the pending-mutation marker until that write
+lands, and hands them the saved rotation. No contender ever redeems the retired
+token again, and the marker can no longer outlive the write that clears it
+([#526](https://github.com/zackbart/connecta/issues/526)).
+
 The coordinator retains the owner's abort signal only through one temporary
 listener on the exact active refresh. Save, failure, cancellation, or
 generation retirement removes it along with the map entry. It never retains a
@@ -56,22 +65,24 @@ scope resolved from the request rather than remembered.
 
 ## Request lifecycle
 
-`src/server.ts` is the composition root. It does three things in order: upgrade
-the scheme when it must, run the route table, then wrap whatever came back in
+`src/server.ts` is the composition root. It checks MCP origins, upgrades the
+scheme when it must, runs the route table, then wraps whatever came back in
 security headers. Route *order* is the contract — several routes would behave
 differently if they were reachable in another order — so the table below is
 read top to bottom.
 
 | Order | Route | Notes |
 | --- | --- | --- |
+| 0 | MCP Origin check | `/mcp` and every `/mcp/` suffix reject a disallowed `Origin` with a fixed 403 before redirects, admission, auth, or preflight. `allowedOrigins` defaults to the configured public origin plus HTTP(S) loopback origins at any port. Requests without Origin are admitted. |
 | 0 | HTTPS upgrade | 308 to `publicUrl` when it is HTTPS and the request arrived over HTTP. Path and query are *assigned* onto the configured URL, never resolved against it, so a `//host` pathname cannot replace the deployment origin. `/health` is exempt: a loopback container probe must not depend on public DNS and TLS. `/ui` is canonicalized to `/` while upgrading. |
 | 0 | Cloudflare Access (Worker deployment, when enabled) | Edge admission before this route table. Managed OAuth owns its challenge and discovery metadata; an admitted direct invocation carries trusted identity in `ctx.access`. |
 | 1 | Mounted UI routes | The optional UI handles its shells, assets, data, details, and auth mutations before wildcard OPTIONS. Mutation routes refuse preflight rather than inheriting MCP CORS. No UI module means none of these routes. |
-| 2 | `OPTIONS` | Auth metadata gets a chance, otherwise MCP CORS preflight. |
+| 2 | MCP preflight | Allowed `OPTIONS` on `/mcp` or any `/mcp/` suffix returns 204 without admission or auth. Reflect the allowed origin and requested valid `mcp-param-*` header names. |
+| 2 | Other `OPTIONS` | Auth metadata gets a chance, otherwise compatibility CORS preflight. |
 | 3 | `/.well-known/*` | Auth metadata, or 404. |
-| 4 | `/health` | Open payload-free health, executor, admission, and deployment metadata; reserved routes reflect installed modules. |
+| 4 | `/health` | Open payload-free health, executor, admission, and deployment metadata; connector drift uses stable short hashes and downstream admission sums shared and personal controllers without ids. Reserved routes reflect installed modules. |
 | 5 | `/oauth/callback/<connectorId>` | Core downstream OAuth completion, state verification and personal ownership checks; independent of UI. |
-| 6 | `/mcp` | Admission before auth, then a request-local MCP server. |
+| 6 | `/mcp`, `/mcp/<pool>` | Origin check before admission, admission before auth, then a request-local MCP server. A pool path serves the declared pool intersected with the identity's own view; any undeclared suffix, including malformed names, a refusing grant, and a throwing grant return the same 404 status, body, and headers after auth. Grant lookup latency is not hidden; see [pools](./auth.md#pools). |
 | 7 | Other paths | 404. Custom HTTP routes belong to the deployment. |
 
 
@@ -80,7 +91,12 @@ policy, HSTS on HTTPS, while the UI module adds a nonce-based script CSP and fra
 and the exact refusal bodies; it exists because the ordering is invisible in
 any one file and a reordering reads like a harmless refactor.
 
-`/mcp` itself is five steps, in this order and for these reasons:
+`/mcp` first checks Origin, including on preflight. A disallowed browser origin
+costs no permit and no auth lookup. The explicit `allowedOrigins: "*"` escape
+hatch preserves open CORS; a list reflects only admitted origins and varies
+responses by Origin. An originless client needs no CORS allow-origin header.
+
+An admitted non-preflight request then takes six steps:
 
 1. **Admit.** One permit from the deployment-wide FIFO pool, taken before auth
    so an unauthenticated flood costs a permit rather than a Clerk lookup
@@ -92,13 +108,18 @@ any one file and a reordering reads like a harmless refactor.
    only, and it warns at construction.
 3. **Derive the registry view.** Auth supplies a namespaced subject and, for a
    human, a principal. `identity.connectorAccess` selects declared connector
-   ids. Personal connectors use the principal partition; result paging uses
+   ids and, for a narrower slice, exact `connector.tool` addresses; the
+   scoped view filters every catalog read through them. Personal connectors use the principal partition; result paging uses
    the subject partition. No caller parameter selects either.
-4. **Refuse `?toolkit=`.** Caller-selected toolkits were removed ([#178](https://github.com/zackbart/connecta/issues/178))
+4. **Narrow to the pool.** On `/mcp/<pool>`, look the name up in the
+   declared pools and run its grant against the authenticated identity. The
+   view becomes the pool intersected with the identity's `connectorAccess`;
+   a pool can never widen it. Anything else is a 404 that names no pool.
+5. **Refuse `?toolkit=`.** Caller-selected toolkits were removed ([#178](https://github.com/zackbart/connecta/issues/178))
    but the URLs naming them were handed out, so the parameter is a 404 rather
    than silently serving the full registry. Retiring a scoping boundary into
    fail-open is the one outcome worse than the 404.
-5. **Serve.** A fresh `McpServer` per request, the seven meta-tools registered
+6. **Serve.** A fresh `McpServer` per request, the seven meta-tools registered
    against the registry and the response
    handed back.