@zackbart/connecta 0.24.1 → 0.24.3

package/dist/routes/mcp.js

@@ -2,9 +2,10 @@ import { createMcpHandler, isLegacyRequest, McpServer, WebStandardStreamableHTTP
 import { registerExecuteTool } from "../execute.js";
 import { ExecutorAdmissionError, } from "../executor-admission.js";
 import { registerMetaTools } from "../meta-tools.js";
+import { intersectAccess } from "../connector-access.js";
 import { instructionsFor } from "../skills.js";
 import { msg } from "../errors.js";
-import { authorize, mayManageConnector, validateAuthPermissions, } from "./shared.js";
+import { authorize, loggableValue, mayManageConnector, validateAuthPermissions, } from "./shared.js";
 export const MCP_CORS_HEADERS = {
     "Access-Control-Allow-Origin": "*",
     "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
@@ -13,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,
@@ -45,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.",
@@ -243,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) => {
@@ -260,10 +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;
-        if (path !== "/mcp")
+        if (path !== "/mcp" && !path.startsWith("/mcp/"))
             return null;
+        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({
@@ -286,38 +359,65 @@ 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
+            // one identical 404 so a credential never enumerates the other pools;
+            // the operator log is where the reason lives.
+            let access = authz;
+            if (poolName !== undefined) {
+                const pool = opts.pools?.get(poolName);
+                let granted = false;
+                let reason = "undeclared";
+                if (pool) {
+                    try {
+                        granted = (await pool.grant(authz.identity)) === true;
+                        reason = granted ? "granted" : "refused";
+                    }
+                    catch {
+                        reason = "grant threw";
+                    }
+                }
+                if (!pool || !granted) {
+                    opts.logger.warn(`[connecta] refused /mcp/${poolName} with 404: pool ${reason}` +
+                        (authz.actor.id ? ` for ${loggableValue(authz.actor.id)}` : ""));
+                    return releaseAdmissionWithResponse(cors(new Response("Not Found", { status: 404 })), admission, request.signal);
+                }
+                access = intersectAccess(authz, pool.access);
             }
             let scopedRegistry;
             try {
                 validateAuthPermissions(authz, opts.registry);
                 scopedRegistry = opts.registry.scoped({
-                    connectorIds: authz.connectorIds,
+                    connectorIds: access.connectorIds,
+                    ...(access.toolAccess ? { toolAccess: access.toolAccess } : {}),
                     ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
                     ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
                 });
             }
             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-management.js

@@ -14,6 +14,7 @@ async function handleOAuthManagementRequest(context, connectorId) {
         validateAuthPermissions(authz, opts.registry);
         registry = opts.registry.scoped({
             connectorIds: authz.connectorIds,
+            ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}),
             ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
             ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
         });

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

@@ -4,7 +4,8 @@ import type { ActivityActor, ActivityReadGate, ActivityStore } from "../activity
 import type { CredentialVault } from "../credential-contract.js";
 import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.js";
-import type { Registry } from "../registry.js";
+import type { Registry, ToolAccess } from "../registry.js";
+import type { ResolvedPool } from "../connector-access.js";
 import type { AuthenticatedIdentity, ConnectaBranding, Executor, InboundAuth, InboundAuthRuntimeContext, Logger } from "../types.js";
 import type { ConnectorPermission, ConnectaIdentityConfig } from "../index.js";
 export { msg } from "../errors.js";
@@ -12,7 +13,10 @@ export interface ServerOptions {
     registry: Registry;
     auth: InboundAuth[];
     identity?: ConnectaIdentityConfig | undefined;
+    /** 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;
@@ -78,6 +82,8 @@ export declare function authorize(request: Request, baseUrl: string, auth: Inbou
     subjectKey?: string;
     principalKey?: string;
     connectorIds: "all" | readonly string[];
+    /** Per-connector tool allowlist for connectors granted by address only. */
+    toolAccess?: ToolAccess;
     operator: boolean;
     credentialAdministration: ConnectorPermission;
     personalConnection: ConnectorPermission;

package/dist/routes/shared.js

@@ -1,3 +1,4 @@
+import { parseConnectorAccess } from "../connector-access.js";
 import { identityStorageKey, validIdentityReference } from "../identity.js";
 export { msg } from "../errors.js";
 export function privateJson(body, init = {}) {
@@ -33,11 +34,9 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
     if (auth.length === 0) {
         const actor = { kind: "anonymous" };
         const identity = { actor, interactive: false };
-        let connectorIds = "all";
+        let access;
         try {
-            connectorIds = identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all";
-            if (connectorIds !== "all" && (!Array.isArray(connectorIds) || !connectorIds.every(id => typeof id === "string" && /^[a-z0-9_-]+$/.test(id))))
-                throw new Error("invalid connector permission");
+            access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all");
         }
         catch {
             return {
@@ -45,7 +44,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 response: privateJson({ error: "identity access resolution failed" }, { status: 403 }),
             };
         }
-        return { ok: true, actor, identity, connectorIds, operator: false, credentialAdministration: "none", personalConnection: "none" };
+        return { ok: true, actor, identity, ...access, operator: false, credentialAdministration: "none", personalConnection: "none" };
     }
     let lastResponse = null;
     for (const provider of auth) {
@@ -53,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,
@@ -77,21 +76,21 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
             let operator = interactive;
             let credentialAdministration = "none";
             let personalConnection = "none";
-            let connectorIds = "all";
+            let access;
             try {
                 if (identityConfig?.activityAccess) {
                     operator = interactive && principal
                         ? await identityConfig.activityAccess(principal)
                         : false;
                 }
-                connectorIds = identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all";
+                access = parseConnectorAccess(identityConfig?.connectorAccess ? await identityConfig.connectorAccess(identity) : "all");
                 if (interactive) {
                     credentialAdministration = identityConfig?.credentialAdministration ? await identityConfig.credentialAdministration(identity) : "none";
                     personalConnection = principal && identityConfig?.personalConnection ? await identityConfig.personalConnection(identity) : "none";
                 }
                 if (typeof operator !== "boolean")
                     throw new Error("invalid activity permission");
-                for (const permission of [connectorIds, credentialAdministration, personalConnection]) {
+                for (const permission of [credentialAdministration, personalConnection]) {
                     if (permission !== "all" && permission !== "none" && (!Array.isArray(permission) || !permission.every(id => typeof id === "string" && /^[a-z0-9_-]+$/.test(id))))
                         throw new Error("invalid identity permission");
                 }
@@ -112,7 +111,7 @@ export async function authorize(request, baseUrl, auth, runtimeContext, identity
                 ...(principal && partitionIdentity
                     ? { principalKey: await identityStorageKey(principal) }
                     : {}),
-                connectorIds,
+                ...access,
                 credentialAdministration,
                 personalConnection,
                 operator,

package/dist/routes/ui.js

@@ -111,6 +111,7 @@ export async function routeUi(context) {
         validateAuthPermissions(authz, opts.registry);
         registry = opts.registry.scoped({
             connectorIds: authz.connectorIds,
+            ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}),
             ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}),
             ...(authz.principalKey ? { principalKey: authz.principalKey } : {}),
         });
@@ -133,7 +134,7 @@ export async function routeUi(context) {
         const connector = registry.getConnector(detail[1]);
         if (!connector)
             return privateJson({ error: "unknown connector" }, { status: 404 });
-        const one = opts.registry.scoped({ connectorIds: [connector.id], ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}), ...(authz.principalKey ? { principalKey: authz.principalKey } : {}) });
+        const one = opts.registry.scoped({ connectorIds: [connector.id], ...(authz.toolAccess ? { toolAccess: authz.toolAccess } : {}), ...(authz.subjectKey ? { subjectKey: authz.subjectKey } : {}), ...(authz.principalKey ? { principalKey: authz.principalKey } : {}) });
         const data = await buildUiData(one, baseUrl, opts.serverInfo, opts.credentialVault, activityEnabled, credentialManagement, defer, false, 1, authz.principalKey, { mayManage, timeoutMs: opts.probeTimeoutMs ?? 30_000, signal: request.signal });
         return privateJson({ ...data.connectors[0], permissions: permissions(connector) });
     }

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;
+};