@zackbart/connecta 0.24.2 → 0.24.3

package/dist/registry.js

@@ -1,7 +1,7 @@
 import { closeConnectorScope, } from "./connector-scope.js";
 import { storedCredentialShape, } from "./credential-rules.js";
 import { ConnectorCallError, msg } from "./errors.js";
-import { ConnectorCallAdmissionController, } from "./call-admission.js";
+import { ConnectorCallAdmissionController, aggregateCallAdmissionSnapshots, } from "./call-admission.js";
 import { boundedCatalogDrift } from "./catalog-drift.js";
 import { fingerprintSerializedCatalog, snapshotCatalog, } from "./catalog-fingerprint.js";
 import { MAX_CATALOG_CHUNK_BYTES, MAX_CATALOG_TOOLS, MAX_SERIALIZED_CATALOG_BYTES, } from "./catalog-limits.js";
@@ -80,6 +80,7 @@ function namespaced(storage, prefix) {
     };
 }
 const MAX_PERSONAL_REGISTRIES = 1_024;
+const MAX_ABSENT_GRANT_WARNINGS = 1_024;
 const OAUTH_HANDOFF_TTL_SECONDS = 15 * 60;
 async function sha256Hex(value) {
     const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
@@ -117,9 +118,13 @@ export class Registry {
     persistToolCatalog;
     /** Result-size guard cap threaded to the meta-tools. */
     maxResultBytes;
+    /** Only keys, byte counts, and expiry survive requests; never write promises. */
+    resultStash = new Map();
+    resultStashBytes = 0;
     configuredConnectors;
     personalRegistries = new Map();
-    /** `connector.tool` grants that matched nothing, warned once per isolate. */
+    callAdmissionClosed = false;
+    /** Bounded FIFO of absent grants already warned about. */
     warnedAbsentGrants = new Set();
     constructor(connectors, opts) {
         this.opts = opts;
@@ -174,18 +179,24 @@ export class Registry {
             this.personalRegistries.set(principalKey, existing);
             return existing;
         }
+        if (this.personalRegistries.size >= MAX_PERSONAL_REGISTRIES) {
+            // Eviction must not reset a live rolling budget or orphan queued calls.
+            const idle = [...this.personalRegistries].find(([, candidate]) => [...candidate.callAdmission.values()].every(admission => admission.isIdle()));
+            if (!idle) {
+                throw new Error("Personal connector capacity is exhausted; retry after calls and rolling budgets drain.");
+            }
+            idle[1].closeCallAdmission();
+            this.personalRegistries.delete(idle[0]);
+        }
         const registry = new Registry(this.configuredConnectors.filter((connector) => connector.authScope === "personal"), {
             ...this.opts,
             storage: namespaced(this.opts.storage, `principal:${principalKey}:`),
             credentialOwner: principalKey,
             constructionChecks: false,
         });
+        if (this.callAdmissionClosed)
+            registry.closeCallAdmission();
         this.personalRegistries.set(principalKey, registry);
-        const oldest = this.personalRegistries.keys().next().value;
-        if (this.personalRegistries.size > MAX_PERSONAL_REGISTRIES &&
-            typeof oldest === "string") {
-            this.personalRegistries.delete(oldest);
-        }
         return registry;
     }
     /** Build the only connector view an authenticated request receives. */
@@ -214,6 +225,11 @@ export class Registry {
         if (this.warnedAbsentGrants.has(key))
             return;
         this.warnedAbsentGrants.add(key);
+        if (this.warnedAbsentGrants.size > MAX_ABSENT_GRANT_WARNINGS) {
+            const oldest = this.warnedAbsentGrants.values().next().value;
+            if (oldest !== undefined)
+                this.warnedAbsentGrants.delete(oldest);
+        }
         // Grant names are operator data but may carry any non-control character;
         // quote them so a line terminator a log reader honours cannot forge a line.
         const quoted = JSON.stringify(key).replace(/[\u2028\u2029]/g, (ch) => `\\u${ch.charCodeAt(0).toString(16)}`);
@@ -345,11 +361,19 @@ export class Registry {
             return admission.acquire(input);
         return Promise.resolve({ waitMs: 0, release() { } });
     }
-    /** Payload-free aggregate state for the open health endpoint. */
+    /** Connector totals across root and personal controllers; health removes ids. */
     callAdmissionSnapshot() {
-        return Object.fromEntries([...this.callAdmission].map(([id, admission]) => [
-            id,
-            admission.snapshot(),
+        const snapshots = new Map();
+        for (const [id, admission] of this.callAdmission) {
+            snapshots.set(id, [admission.snapshot()]);
+        }
+        for (const registry of this.personalRegistries.values()) {
+            for (const [id, admission] of registry.callAdmission) {
+                snapshots.get(id)?.push(admission.snapshot());
+            }
+        }
+        return Object.fromEntries([...snapshots].map(([id, values]) => [
+            id, aggregateCallAdmissionSnapshots(values),
         ]));
     }
     /**
@@ -416,8 +440,54 @@ export class Registry {
     }
     /** Reject queued/future downstream admission; active permits release safely. */
     closeCallAdmission() {
+        this.callAdmissionClosed = true;
         for (const admission of this.callAdmission.values())
             admission.close();
+        for (const registry of this.personalRegistries.values())
+            registry.closeCallAdmission();
+    }
+    /** Reserve capacity and write one ASCII paging envelope in this runtime. */
+    async stashResult(key, value, ttlSeconds, prefix = "results:") {
+        const maxBytes = this.opts.results?.maxStashBytes ?? 8 * 1024 * 1024;
+        const maxEntries = this.opts.results?.maxStashEntries ?? 64;
+        // The paging envelope is ASCII, so its string length is its stored byte count.
+        const bytes = value.length;
+        if (bytes > maxBytes || maxEntries === 0)
+            return false;
+        const now = Date.now();
+        for (const [oldKey, entry] of this.resultStash) {
+            if (entry.busy || entry.expiresAt > now)
+                continue;
+            entry.busy = true;
+            try {
+                // TTL alone cannot reclaim a lazy backend. Keep the charge until deletion
+                // succeeds, including writes which persisted before throwing.
+                await this.opts.storage.delete(oldKey);
+                this.resultStash.delete(oldKey);
+                this.resultStashBytes -= entry.bytes;
+            }
+            finally {
+                entry.busy = false;
+            }
+        }
+        if (this.resultStash.size >= maxEntries || this.resultStashBytes + bytes > maxBytes)
+            return false;
+        const fullKey = prefix + key;
+        const entry = { bytes, expiresAt: Infinity, busy: true };
+        this.resultStash.set(fullKey, entry);
+        this.resultStashBytes += bytes;
+        try {
+            await this.opts.storage.set(fullKey, value, { ttlSeconds });
+            entry.expiresAt = Date.now() + ttlSeconds * 1000;
+            return true;
+        }
+        catch (error) {
+            entry.expiresAt = 0;
+            throw error;
+        }
+        finally {
+            entry.busy = false;
+        }
     }
     /**
      * Storage namespaced to the meta-tool result store (`results:` prefix), kept
@@ -1125,10 +1195,14 @@ class ScopedRegistryView {
         return registry.contextFor(...args);
     }
     admitCall(...args) {
-        if (!this.registryFor(args[0])) {
+        const registry = this.registryFor(args[0]);
+        if (!registry) {
             return Promise.reject(new Error(`Unknown connector "${args[0]}"`));
         }
-        return this.root.admitCall(...args);
+        return registry.admitCall(...args);
+    }
+    stashResult(key, value, ttlSeconds) {
+        return this.root.stashResult(key, value, ttlSeconds, this.scope.subjectKey ? `subject:${this.scope.subjectKey}:` : "results:");
     }
     resultsStorage() {
         return this.scope.subjectKey

package/dist/routes/mcp.d.ts

@@ -4,4 +4,7 @@ export declare const MCP_CORS_HEADERS: {
     "Access-Control-Allow-Methods": string;
     "Access-Control-Allow-Headers": string;
 };
-export declare function createMcpRoute(opts: ServerOptions): (context: RouteContext) => Promise<Response | null>;
+export declare function createMcpRoute(opts: ServerOptions): {
+    handle(context: RouteContext): Promise<Response | null>;
+    rejectOrigin(request: Request): Response | null;
+};

package/dist/routes/mcp.js

@@ -14,11 +14,26 @@ export const MCP_CORS_HEADERS = {
 // Browser-based MCP clients call /mcp cross-origin. Without CORS on every
 // response — errors included — the browser hides the 401, the client cannot
 // read WWW-Authenticate, and OAuth discovery silently never starts.
-function withMcpCors(response) {
+function withMcpCors(response, request, allowedOrigin) {
     const headers = new Headers(response.headers);
     for (const [name, value] of Object.entries(MCP_CORS_HEADERS)) {
         headers.set(name, value);
     }
+    headers.delete("Access-Control-Allow-Origin");
+    if (allowedOrigin !== null)
+        headers.set("Access-Control-Allow-Origin", allowedOrigin);
+    headers.append("Vary", "Origin");
+    if (request.method === "OPTIONS") {
+        // Browsers do not interpret a prefix wildcard in Allow-Headers. Echo only
+        // valid SEP-2243 field names; unrelated requested headers stay disallowed.
+        const paramHeaders = (request.headers.get("Access-Control-Request-Headers") ?? "")
+            .toLowerCase().split(",").map(name => name.trim())
+            .filter(name => /^mcp-param-[!#$%&'*+.^_`|~0-9a-z-]+$/.test(name));
+        if (paramHeaders.length) {
+            headers.append("Access-Control-Allow-Headers", [...new Set(paramHeaders)].join(", "));
+        }
+        headers.append("Vary", "Access-Control-Request-Headers");
+    }
     headers.set("Access-Control-Expose-Headers", "WWW-Authenticate, Retry-After, mcp-session-id, mcp-protocol-version");
     return new Response(response.body, {
         status: response.status,
@@ -46,7 +61,10 @@ function requestAdmissionFailure(error) {
         jsonrpc: "2.0",
         id: null,
         error: {
-            code: overloaded ? -32001 : -32002,
+            // MCP 2026-07-28 basic#error-codes forbids new allocations in the
+            // legacy -32000..-32019 range. Use application codes outside the
+            // JSON-RPC reserved range, avoiding retired protocol meanings.
+            code: overloaded ? -31001 : -31002,
             message: overloaded
                 ? "Server capacity is exhausted. Retry later."
                 : "Server is shutting down.",
@@ -244,6 +262,49 @@ async function serveMcp(request, opts, baseUrl, actor, registry, canManageAuth,
     return transport.handleRequest(request);
 }
 export function createMcpRoute(opts) {
+    const configuredOrigins = opts.allowedOrigins;
+    const isExactOrigin = (value) => {
+        if (typeof value !== "string")
+            return false;
+        try {
+            const url = new URL(value);
+            return (url.protocol === "http:" || url.protocol === "https:") && url.origin === value;
+        }
+        catch {
+            return false;
+        }
+    };
+    if (configuredOrigins !== undefined && configuredOrigins !== "*" &&
+        (!Array.isArray(configuredOrigins) || !configuredOrigins.every(isExactOrigin))) {
+        throw new TypeError('ConnectaConfig.allowedOrigins must be an array of exact HTTP(S) origins or "*".');
+    }
+    const origins = new Set(configuredOrigins === undefined
+        ? opts.publicUrl ? [new URL(opts.publicUrl).origin] : []
+        : configuredOrigins === "*" ? [] : configuredOrigins);
+    const allowsOrigin = (origin) => {
+        if (configuredOrigins === "*")
+            return true;
+        if (!isExactOrigin(origin))
+            return false;
+        if (origins.has(origin))
+            return true;
+        if (configuredOrigins !== undefined)
+            return false;
+        const hostname = new URL(origin).hostname;
+        return hostname === "localhost" || hostname === "[::1]" || /^127\.\d+\.\d+\.\d+$/.test(hostname);
+    };
+    const rejectOrigin = (request) => {
+        const path = new URL(request.url).pathname;
+        if (path !== "/mcp" && !path.startsWith("/mcp/"))
+            return null;
+        const origin = request.headers.get("Origin");
+        if (origin === null || allowsOrigin(origin))
+            return null;
+        return withMcpCors(new Response('{"error":"origin not allowed"}', {
+            status: 403,
+            headers: { "Content-Type": "application/json", "Cache-Control": "no-store" },
+        }), request, null);
+    };
     let lastAdmissionWarningAt = 0;
     let suppressedAdmissionWarnings = 0;
     const warnAdmissionRejected = (error) => {
@@ -261,12 +322,21 @@ export function createMcpRoute(opts) {
         lastAdmissionWarningAt = now;
         suppressedAdmissionWarnings = 0;
     };
-    return async function routeMcp(context) {
+    async function routeMcp(context) {
         const { path, request, baseUrl, runtimeContext, } = context;
-        const poolPath = /^\/mcp\/([a-z0-9_-]+)$/.exec(path);
-        if (path !== "/mcp" && !poolPath)
+        if (path !== "/mcp" && !path.startsWith("/mcp/"))
             return null;
-        const poolName = poolPath?.[1];
+        const poolName = path === "/mcp" ? undefined : path.slice("/mcp/".length);
+        const origin = request.headers.get("Origin");
+        const allowed = origin === null || allowsOrigin(origin);
+        const cors = (response) => withMcpCors(response, request, configuredOrigins === "*" ? "*" : allowed ? origin : null);
+        // DNS-rebinding refusals cost neither a permit nor an auth lookup. This
+        // local header check also guards OPTIONS before any provider metadata.
+        const refusal = rejectOrigin(request);
+        if (refusal)
+            return refusal;
+        if (request.method === "OPTIONS")
+            return cors(new Response(null, { status: 204 }));
         let admission;
         try {
             admission = await opts.requestAdmission.acquire({
@@ -289,14 +359,14 @@ export function createMcpRoute(opts) {
                 if (error.code === "executor_overloaded") {
                     warnAdmissionRejected(error);
                 }
-                return withMcpCors(requestAdmissionFailure(error));
+                return cors(requestAdmissionFailure(error));
             }
             throw error;
         }
         try {
             const authz = await authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity);
             if (!authz.ok) {
-                return releaseAdmissionWithResponse(withMcpCors(authz.response), admission, request.signal);
+                return releaseAdmissionWithResponse(cors(authz.response), admission, request.signal);
             }
             // A pool endpoint narrows the identity's own view and nothing else. An
             // undeclared name, a grant that refuses, and a grant that throws are
@@ -319,7 +389,7 @@ export function createMcpRoute(opts) {
                 if (!pool || !granted) {
                     opts.logger.warn(`[connecta] refused /mcp/${poolName} with 404: pool ${reason}` +
                         (authz.actor.id ? ` for ${loggableValue(authz.actor.id)}` : ""));
-                    return releaseAdmissionWithResponse(withMcpCors(new Response("Not Found", { status: 404 })), admission, request.signal);
+                    return releaseAdmissionWithResponse(cors(new Response("Not Found", { status: 404 })), admission, request.signal);
                 }
                 access = intersectAccess(authz, pool.access);
             }
@@ -334,19 +404,20 @@ export function createMcpRoute(opts) {
                 });
             }
             catch (error) {
-                return releaseAdmissionWithResponse(withMcpCors(new Response(JSON.stringify({ error: msg(error) }), {
+                return releaseAdmissionWithResponse(cors(new Response(JSON.stringify({ error: msg(error) }), {
                     status: 403,
                     headers: { "Content-Type": "application/json" },
                 })), admission, request.signal);
             }
             if (new URL(request.url).searchParams.has("toolkit")) {
-                return releaseAdmissionWithResponse(withMcpCors(toolkitRetired(opts.logger)), admission, request.signal);
+                return releaseAdmissionWithResponse(cors(toolkitRetired(opts.logger)), admission, request.signal);
             }
-            return releaseAdmissionWithResponse(withMcpCors(await serveMcp(request, opts, baseUrl, authz.actor, scopedRegistry, id => { const connector = scopedRegistry.getConnector(id); return Boolean(connector && mayManageConnector(authz, connector)); }, runtimeContext)), admission, request.signal);
+            return releaseAdmissionWithResponse(cors(await serveMcp(request, opts, baseUrl, authz.actor, scopedRegistry, id => { const connector = scopedRegistry.getConnector(id); return Boolean(connector && mayManageConnector(authz, connector)); }, runtimeContext)), admission, request.signal);
         }
         catch (error) {
             admission.release();
             throw error;
         }
-    };
+    }
+    return { handle: routeMcp, rejectOrigin };
 }

package/dist/routes/oauth.js

@@ -137,6 +137,10 @@ export async function routeOAuthCallback(context) {
         return refused();
     }
     const expectedPrincipalKey = callbackTarget?.principalKey;
+    // A browser returning from consent normally has no MCP Authorization
+    // header. An interactive bearer provider therefore answers 401 here; state
+    // and the saved state-to-principal handoff still prove ownership below.
+    // Rejecting 401 would break that callback. A 403 is an explicit denial.
     const browserIdentity = await authorizeUiIdentity(context.request, baseUrl, opts.auth, "OAuth callback", context.runtimeContext, opts.identity);
     if (browserIdentity.ok) {
         try {

package/dist/routes/shared.d.ts

@@ -16,6 +16,7 @@ export interface ServerOptions {
     /** Validated named pools served at `/mcp/<name>`; empty when none declared. */
     pools?: ReadonlyMap<string, ResolvedPool> | undefined;
     publicUrl?: string | undefined;
+    allowedOrigins?: readonly string[] | "*" | undefined;
     serverInfo: Implementation;
     logger: Logger;
     activity?: ActivityStore | undefined;

package/dist/routes/shared.js

@@ -52,20 +52,20 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
         if (result.ok) {
             const subjectId = result.subjectId ?? result.userId;
             const actorNamespace = activityActorNamespace(provider);
-            const subject = subjectId && actorNamespace
-                ? { namespace: actorNamespace, id: subjectId }
-                : undefined;
             const derivedPrincipal = result.userId && actorNamespace
                 ? { namespace: actorNamespace, id: result.userId }
                 : undefined;
             const principal = validIdentityReference(result.principal)
                 ? result.principal
                 : derivedPrincipal;
+            const subject = subjectId
+                ? { namespace: actorNamespace ?? `connecta:auth:${provider.kind}`, id: subjectId }
+                : principal;
             const interactive = Boolean(result.userId && provider.interactiveOperator);
             const actor = {
                 kind: provider.kind,
                 ...(subjectId ? { id: subjectId } : {}),
-                ...(subject ? { namespace: subject.namespace } : {}),
+                ...(subjectId && actorNamespace ? { namespace: actorNamespace } : {}),
             };
             const identity = {
                 actor,

package/dist/server.js

@@ -1,3 +1,4 @@
+import { aggregateCallAdmissionSnapshots } from "./call-admission.js";
 import { isAdmittingExecutor } from "./executor-admission.js";
 import { createMcpRoute, MCP_CORS_HEADERS } from "./routes/mcp.js";
 import { routeOAuthCallback, } from "./routes/oauth.js";
@@ -18,6 +19,9 @@ export function createFetchHandler(opts) {
         const defer = runtimeContext
             ? runtimeContext.waitUntil.bind(runtimeContext)
             : undefined;
+        const originRefusal = routeMcp.rejectOrigin(request);
+        if (originRefusal)
+            return withSecurityHeaders(originRefusal, url, path);
         // Container and orchestrator probes reach /health over plain HTTP on
         // loopback, where no proxy has set X-Forwarded-Proto. Redirecting them to
         // the public origin would make an internal liveness check depend on
@@ -59,6 +63,9 @@ export function createFetchHandler(opts) {
             if (uiResponse)
                 return uiResponse;
             if (request.method === "OPTIONS") {
+                const preflight = await routeMcp.handle(context);
+                if (preflight)
+                    return preflight;
                 for (const provider of auth) {
                     if (provider.handleMetadata) {
                         const response = await provider.handleMetadata(request, baseUrl);
@@ -102,14 +109,19 @@ export function createFetchHandler(opts) {
                     // Counts only, from refreshes that already happened — the endpoint
                     // asks no downstream anything, and `connecta doctor` reads it to
                     // report a stale allowlist without a probe of its own (#343).
-                    catalogDrift: registry.catalogDriftSnapshot(),
+                    // Stable 64-bit hashes preserve that shape without publishing ids.
+                    catalogDrift: Object.fromEntries(await Promise.all(Object.entries(registry.catalogDriftSnapshot()).map(async ([id, report]) => {
+                        const hash = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(id)));
+                        const key = Array.from(hash.subarray(0, 8), byte => byte.toString(16).padStart(2, "0")).join("");
+                        return [key, report];
+                    }))),
                     admission: {
                         policy: "global-fifo",
                         requests: opts.requestAdmission.snapshot(),
                         code: codeAdmission ?? { managedByExecutor: true },
                         downstreamCalls: {
                             policy: "connector-partitioned-per-runtime",
-                            connectors: registry.callAdmissionSnapshot(),
+                            aggregate: aggregateCallAdmissionSnapshots(Object.values(registry.callAdmissionSnapshot())),
                         },
                         reservedRoutes: [
                             "/health",
@@ -123,7 +135,7 @@ export function createFetchHandler(opts) {
             const oauthCallback = await routeOAuthCallback(context);
             if (oauthCallback)
                 return oauthCallback;
-            const mcp = await routeMcp(context);
+            const mcp = await routeMcp.handle(context);
             if (mcp)
                 return mcp;
             return new Response("Not Found", { status: 404 });

package/dist/skills.js

@@ -1,3 +1,4 @@
+import { boundedEchoText } from "./errors.js";
 export const CONNECTA_INSTRUCTIONS = 'Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Inspect unfamiliar result shapes with a small sample before proceeding. Only readOnlyHint: true tools run there. Keep catalog inspection and unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
 const USAGE_SKILL_BASE = `# Connecta usage
 
@@ -423,14 +424,14 @@ export function resolveSkill(name, connectors) {
         if (!connector) {
             return {
                 found: false,
-                message: `Unknown connector "${id}". Available skills: ${available()}.`,
+                message: `Unknown connector "${boundedEchoText(id)}". Available skills: ${available()}.`,
             };
         }
         const guide = connectorGuide(connector);
         if (!guide) {
             return {
                 found: false,
-                message: `Connector "${id}" has no usage guide. Available skills: ${available()}.`,
+                message: `Connector "${boundedEchoText(id)}" has no usage guide. Available skills: ${available()}.`,
             };
         }
         return { found: true, content: guide };
@@ -440,12 +441,12 @@ export function resolveSkill(name, connectors) {
         return {
             found: false,
             message: connectorGuide(bare)
-                ? `Unknown skill "${name}". Connector guides are fetched as "${connectorSkillName(name)}". Available skills: ${available()}.`
-                : `Connector "${name}" has no usage guide. Available skills: ${available()}.`,
+                ? `Unknown skill "${boundedEchoText(name)}". Connector guides are fetched as "${boundedEchoText(connectorSkillName(name))}". Available skills: ${available()}.`
+                : `Connector "${boundedEchoText(name)}" has no usage guide. Available skills: ${available()}.`,
         };
     }
     return {
         found: false,
-        message: `Unknown skill "${name}". Available skills: ${available()}.`,
+        message: `Unknown skill "${boundedEchoText(name)}". Available skills: ${available()}.`,
     };
 }

package/dist/storage/file.d.ts

@@ -5,7 +5,11 @@ export interface FileStorageOptions {
 }
 /**
  * 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 declare function fileStorage(path: string, opts?: FileStorageOptions): KVStorage;
+export declare function fileStorage(path: string, opts?: FileStorageOptions): KVStorage & {
+    close(): void;
+};