@zackbart/connecta 0.24.4 → 0.26.0

package/dist/connector-access.js

@@ -12,38 +12,69 @@ const hasControlCharacter = (value) => [...value].some((ch) => {
  * Normalize a grant list. A bare connector id grants every tool on that
  * connector; a `connector.tool` address grants one tool. Grants are additive,
  * so a bare id beside addresses for the same connector means the whole
- * connector. Anything else — an unknown shape, an empty tool name, a
- * non-string — throws, and the caller decides whether that is a construction
- * failure or a 403: a grant that cannot be parsed must never fail open.
+ * connector. Identity resolution can opt into `{ tool, requireReadOnly: true }`
+ * for a fixed address that also needs a current explicit read-only annotation;
+ * pool declarations remain strings. Anything else throws, and the caller
+ * decides whether that is a construction failure or a 403: a grant that
+ * cannot be parsed must never fail open.
  */
-export function parseConnectorAccess(value) {
+export function parseConnectorAccess(value, options = {}) {
     if (value === "all")
         return { connectorIds: "all" };
     if (!Array.isArray(value))
         throw new Error("invalid connector permission");
     const whole = new Set();
-    const partial = new Map();
+    const plain = new Map();
+    const guarded = new Map();
     for (const entry of value) {
-        if (typeof entry !== "string")
-            throw new Error("invalid connector permission");
-        if (CONNECTOR_ID_RE.test(entry)) {
+        if (typeof entry === "string" && CONNECTOR_ID_RE.test(entry)) {
             whole.add(entry);
             continue;
         }
-        if (!TOOL_ADDRESS_RE.test(entry) || hasControlCharacter(entry))
+        const isGuarded = typeof entry !== "string";
+        if (isGuarded && (!options.allowReadOnly || entry === null ||
+            typeof entry !== "object" || Array.isArray(entry) ||
+            !Object.hasOwn(entry, "tool") || !Object.hasOwn(entry, "requireReadOnly") ||
+            Object.keys(entry).length !== 2 || entry.requireReadOnly !== true)) {
+            throw new Error("invalid connector permission");
+        }
+        const address = isGuarded ? entry.tool : entry;
+        if (typeof address !== "string" || !TOOL_ADDRESS_RE.test(address) || hasControlCharacter(address)) {
             throw new Error("invalid connector permission");
-        const dot = entry.indexOf(".");
-        const connectorId = entry.slice(0, dot);
-        const tools = partial.get(connectorId) ?? new Set();
-        tools.add(entry.slice(dot + 1));
-        partial.set(connectorId, tools);
+        }
+        const dot = address.indexOf(".");
+        const connectorId = address.slice(0, dot);
+        const target = isGuarded ? guarded : plain;
+        const tools = target.get(connectorId) ?? new Set();
+        tools.add(address.slice(dot + 1));
+        target.set(connectorId, tools);
+    }
+    for (const id of whole) {
+        plain.delete(id);
+        guarded.delete(id);
+    }
+    for (const [id, names] of plain) {
+        const restricted = guarded.get(id);
+        if (!restricted)
+            continue;
+        for (const name of names)
+            restricted.delete(name);
+        if (restricted.size === 0)
+            guarded.delete(id);
+    }
+    const partial = new Map(plain);
+    for (const [id, names] of guarded) {
+        const combined = partial.get(id) ?? new Set();
+        for (const name of names)
+            combined.add(name);
+        partial.set(id, combined);
     }
-    for (const id of whole)
-        partial.delete(id);
     const connectorIds = [...new Set([...whole, ...partial.keys()])];
-    return partial.size > 0
-        ? { connectorIds, toolAccess: partial }
-        : { connectorIds };
+    return {
+        connectorIds,
+        ...(partial.size > 0 ? { toolAccess: partial } : {}),
+        ...(guarded.size > 0 ? { guardedToolAccess: guarded } : {}),
+    };
 }
 /**
  * The view a pool endpoint serves: the pool's grants, never wider than the
@@ -59,6 +90,7 @@ export function intersectAccess(ceiling, pool) {
         : new Set(ceiling.connectorIds);
     const connectorIds = [];
     const toolAccess = new Map();
+    const guardedToolAccess = new Map();
     for (const id of pool.connectorIds) {
         if (allowedIds && !allowedIds.has(id))
             continue;
@@ -73,7 +105,20 @@ export function intersectAccess(ceiling, pool) {
         else if (fromPool ?? fromCeiling) {
             toolAccess.set(id, (fromPool ?? fromCeiling));
         }
+        const guarded = ceiling.guardedToolAccess?.get(id);
+        if (guarded) {
+            const allowed = toolAccess.get(id);
+            const retained = allowed
+                ? new Set([...guarded].filter((name) => allowed.has(name)))
+                : guarded;
+            if (retained.size > 0)
+                guardedToolAccess.set(id, retained);
+        }
         connectorIds.push(id);
     }
-    return toolAccess.size > 0 ? { connectorIds, toolAccess } : { connectorIds };
+    return {
+        connectorIds,
+        ...(toolAccess.size > 0 ? { toolAccess } : {}),
+        ...(guardedToolAccess.size > 0 ? { guardedToolAccess } : {}),
+    };
 }

package/dist/connector-caller.d.ts

@@ -0,0 +1,8 @@
+import type { AuthenticatedIdentity, ConnectorContext } from "./types.js";
+export interface ConnectorCaller {
+    identity: AuthenticatedIdentity;
+    /** The `/mcp/<pool>` the call arrived on, when it was a pool. */
+    pool?: string;
+}
+export declare function attachCaller(ctx: ConnectorContext, caller: ConnectorCaller | undefined): ConnectorContext;
+export declare function callerOf(ctx: ConnectorContext): ConnectorCaller | undefined;

package/dist/connector-caller.js

@@ -0,0 +1,19 @@
+// Who is calling, for the connectors connecta ships and nothing else.
+//
+// `ConnectorContext` deliberately carries no identity: a deployment's own
+// connector acts for the deployment, and one that could read its caller would
+// invite per-user behavior the access rules never saw. The built-in artifacts
+// connector is the exception — every version it writes records who wrote it —
+// so the identity rides beside the context, the way the OAuth sealer does,
+// where only in-repo code can read it. Core sets it from the authorization
+// that admitted the request, on the scoped registry view that request
+// receives; no argument, header, or program can name it.
+const callers = new WeakMap();
+export function attachCaller(ctx, caller) {
+    if (caller)
+        callers.set(ctx, caller);
+    return ctx;
+}
+export function callerOf(ctx) {
+    return callers.get(ctx);
+}

package/dist/connector-scope.js

@@ -1,19 +1,5 @@
-import { sleep } from "./timeout.js";
-/** Enough for local transport abort/close without letting cleanup own latency. */
-const CONNECTOR_SCOPE_CLOSE_BUDGET_MS = 100;
-/**
- * Bound on cleanup continued after the caller-facing window expires.
- *
- * `remoteMcp` spends at most one second asking the downstream to terminate its
- * session, leaving another second for the local close. Custom hooks still get a
- * finite background window: handing a never-settling promise to a Worker's
- * `waitUntil` would otherwise keep the invocation alive until the platform cap.
- */
-const CONNECTOR_SCOPE_DEFER_BUDGET_MS = 2_000;
-/** Resolve when `work` settles or `budgetMs` expires; never reject. */
-function waitAtMost(work, budgetMs) {
-    return Promise.race([work, sleep(budgetMs)]).then(() => { });
-}
+import { closeScope } from "./runtime/connector-scope.js";
+import { runEdge } from "./runtime/run.js";
 /**
  * Tell a connector that a scope owned by the core has ended.
  *
@@ -25,25 +11,8 @@ function waitAtMost(work, budgetMs) {
  * window. Callers own the at-most-once guarantee and must not use the scope
  * again after this returns.
  */
-export async function closeConnectorScope(connector, ctx, defer) {
-    try {
-        const closing = connector.closeScope?.(ctx);
-        if (!closing)
-            return;
-        // Attach both handlers before either timer can win, so a late rejection is
-        // consumed rather than becoming an unhandled rejection.
-        const settled = closing.then(() => { }, () => { });
-        if (defer) {
-            try {
-                defer(waitAtMost(settled, CONNECTOR_SCOPE_DEFER_BUDGET_MS));
-            }
-            catch {
-                // A runtime hook is best-effort too; the caller cap still applies.
-            }
-        }
-        await waitAtMost(settled, CONNECTOR_SCOPE_CLOSE_BUDGET_MS);
-    }
-    catch {
-        // The scope is over whether or not the connector managed to clean it up.
-    }
+export function closeConnectorScope(connector, ctx, defer) {
+    // The Promise face of closeScope (src/runtime/connector-scope.ts), which
+    // owns the budgets; an Effect caller registers it as a Scope finalizer.
+    return runEdge(closeScope(connector, ctx, defer));
 }

package/dist/connectors/api.d.ts

@@ -52,9 +52,9 @@ export interface ApiOptions {
      * discovery metadata. See `Connector.usageGuide`.
      */
     usageGuide?: string | ConnectorUsageGuide;
-    /** Optional operator-managed credential exposed through ctx.credential and /credentials. */
+    /** Optional operator-managed credential exposed through ctx.credential and the connection in the operator UI. */
     credential?: ConnectorCredentialConfig;
-    /** Optional validation behind /credentials' Test action. */
+    /** Optional validation behind the connection's Test action in the operator UI. */
     testCredential?: (value: string, ctx: ConnectorContext) => Promise<CredentialTestResult>;
     /** Optional validation for named multi-field credentials. */
     testCredentials?: (values: ConnectorCredentialValues, ctx: ConnectorContext) => Promise<CredentialTestResult>;

package/dist/connectors/remote-mcp.d.ts

@@ -2,8 +2,8 @@ import type { FetchLike, Transport } from "@modelcontextprotocol/client";
 import { ConnectorCallError } from "../errors.js";
 import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, ConnectorCredentialConfig, ConnectorUsageGuide, Logger } from "../types.js";
 /**
- * A static downstream credential the operator supplies at `/credentials`
- * rather than the deployment baking into its source.
+ * A static downstream credential supplied through the connection in the
+ * operator UI rather than baked into deployment source.
  *
  * The connector, its endpoint, and the credential *slot* stay declared in
  * code; only the secret arrives through the operator route, exactly as for
@@ -15,8 +15,8 @@ import type { Connector, ConnectorCallAdmissionPolicy, ConnectorContext, Connect
 interface RemoteMcpCredentialAuth {
     type: "credential";
     /**
-     * Operator-facing slot description rendered on `/credentials`. Defaults to
-     * `{ label: "API key" }`; a maintained provider passes the name the provider
+     * Slot description rendered in the connection in the operator UI. Defaults
+     * to `{ label: "API key" }`; a maintained provider passes the name the provider
      * itself uses. Named `fields` are refused — this shape reads the reserved
      * `value` field only.
      */
@@ -122,7 +122,8 @@ export declare class RemoteMcpRedirectError extends ConnectorCallError {
  * Wrap fetch with explicit, bounded redirect handling.
  *
  * The starting URL of each fetch call is trusted by its caller (the configured
- * MCP endpoint, or an OAuth URL discovered by the pinned SDK). Only Location
+ * MCP endpoint, or an OAuth URL the pinned SDK discovered and
+ * `learnedUrlSafeFetch` already admitted). Only Location
  * values are policy-controlled here. No rejected target is ever fetched, so
  * arbitrary static header names receive the same protection as Authorization.
  */