@zackbart/connecta 0.24.2 → 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.2";
+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.2";
+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`, `/mcp/<pool>` | Admission before auth, then a request-local MCP server. A pool path serves the declared pool intersected with the identity's own view; an undeclared name, a refusing grant, and a throwing grant are one identical 404. |
+| 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 six 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

package/documentation/auth.md

@@ -6,6 +6,16 @@ Cloudflare Access from `/auth/cloudflare-access`. Providers may be combined;
 static bearers are checked first, then other providers in configuration order.
 Connecta no longer issues `cta_` tokens or serves token-management routes.
 
+The bearer adapter challenges with `WWW-Authenticate: Bearer` and deliberately
+omits `resource_metadata`. Its credential is configured out of band; it has no
+OAuth authorization server or registration endpoint to advertise. Interactive
+adapters or the edge own OAuth discovery. Every open deployment with at least
+one connector warns at construction, including API connectors with static auth
+headers. Credential and OAuth connectors add explicit wording about those grants.
+
+MCP browser origins pass the [Origin check](./request-admission.md#origin-before-admission)
+before admission or auth. This is independent of an identity's tool grants.
+
 ## Principals, visibility, and operators
 
 The actor identifies the caller in activity. The subject owns transient results
@@ -13,6 +23,14 @@ such as `get_result` pages. The principal is the human owner of personal
 connector auth. An interactive Clerk or Access user supplies all three. A
 Cloudflare service identity has an actor and subject but no principal.
 
+A subject or user id always selects a result-stash partition, even when the
+provider omits `activityActorNamespace`. An explicit namespace remains the
+partition namespace; without one, Connecta uses `connecta:auth:<provider kind>`.
+Subject ids must be distinct within that namespace. This fallback grants no
+personal-auth ownership and changes no activity attribution. Open deployments
+and providers that return no identity share one result partition. A provider
+that supplies only an explicit principal uses that principal as its subject.
+
 `identity.connectorAccess` returns `"all"` or a list of grants. A grant is a
 declared connector id, which opens every tool on it, or a `connector.tool`
 address, which opens that tool alone. Grants are additive, so a bare id beside
@@ -20,10 +38,15 @@ addresses for the same connector means the whole connector. It governs
 discovery and use, and defaults to all connectors.
 
 Tool grants are enforced in the scoped registry view, below the catalog
-service, so `search_tools`, `describe_tools`, both call tools, a program's
-`connecta.search` and `connecta.call`, and the connection UI all read the same
-filtered list. An ungranted tool fails exactly like one the connector never
-had: `unknown_tool`, with no hint that it exists. That is the whole security
+service. Since 0.24.2, `search_tools`, `describe_tools`, both call tools, a
+program's `connecta.search`, `connecta.describe`, and `connecta.call`, and the
+connection UI read that filtered tool list. Connector-level discovery, guides,
+and `authorize_connector` retain a connector when any tool on it is granted.
+In particular, a `docs.read` grant permits the `docs` authorization handoff,
+subject to the separate auth-management permissions below. Without any grant
+on `docs`, `authorize_connector` returns the same "Unknown connector" refusal
+as an absent connector. An ungranted tool fails exactly like one the connector
+never had: `unknown_tool`, with no hint that it exists. That is the whole security
 claim, and it lives in one place on purpose. There is no separate endpoint per
 tool set; an identity that should see a narrower slice is a branch in this
 resolver, and a bot that needs its own slice is its own bearer subject.
@@ -63,10 +86,13 @@ The rules, each of which is a test:
 - **Grant defaults to deny.** A pool with no `grant` serves nobody. Only a
   literal `true` admits; any other return, a throw, and an undeclared pool
   name produce one 404 identical in status, body, and headers, so a
-  credential does not enumerate the other pools by response. Keep grants
-  pure and fast: a grant that does I/O is the one thing that could make a
-  declared pool distinguishable from an undeclared one by timing. The
-  operator log carries the reason.
+  credential does not enumerate the other pools by response content. Timing
+  is explicitly not hidden: a declared name awaits its grant, while an
+  undeclared name returns without that lookup. We accept this pool-name
+  oracle because names grant no access, a fixed delay cannot hide unbounded
+  grant I/O, and invoking grants for unknown names would add avoidable work
+  while holding an admission permit. Keep grants pure and fast; do not treat
+  pool names as secrets. The operator log carries the refusal reason.
 - **Structural mistakes throw at construction.** A malformed name, an
   unknown connector, an empty pool, and a `connector.tool` address an
   `api()` connector's static catalog lacks all refuse to boot. Remote
@@ -78,7 +104,9 @@ The rules, each of which is a test:
   Cloudflare Managed OAuth is application-level and needs nothing.
 
 A `connector.tool` address the live catalog does not contain is unreachable
-and warned once per isolate. Remote catalogs load lazily, so construction
+and warned once while its address remains in a 1,024-entry FIFO. An evicted
+address may warn again; caller-derived grant text cannot grow retained warning
+state without bound. Remote catalogs load lazily, so construction
 cannot check it, and a catalog that drifts later can never widen a grant
 because there is no wildcard: every tool grant is an exact name.
 
@@ -231,6 +259,11 @@ secret-free handoff to the connection UI. Without the UI, that recovery is
 interactive MCP caller can still start downstream OAuth through
 `authorize_connector` without the UI. Core owns the callback and verifies state
 and principal ownership independently of the optional browser application.
+A browser returning from downstream consent normally carries no MCP
+Authorization header, so an interactive bearer provider's 401 does not reject
+the callback. The verified state and its saved principal handoff select the
+owner; a browser identity, when present, must match that owner and may manage
+the connector. An interactive provider's explicit 403 still refuses the flow.
 
 See [meta-tools](./meta-tools.md#authorization-recovery) and
 [storage and credentials](./storage-and-credentials.md). The