@zackbart/connecta 0.25.0 → 0.26.1

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/connectors/remote-mcp.js

@@ -1,6 +1,7 @@
 import { Client, ProtocolError, SdkHttpError, isInputRequiredResult, specTypeSchemas, StreamableHTTPClientTransport, UnauthorizedError, } from "@modelcontextprotocol/client";
 import { Deferred, Duration, Effect, Exit, Scope } from "effect";
 import { KvOAuthProvider, OAuthRefreshCoordinator, } from "../auth/downstream-oauth.js";
+import { trackOAuthStartReset } from "../auth/oauth-start-reset.js";
 import { MAX_CATALOG_TOOLS } from "../catalog-limits.js";
 import { boundedEchoText, ConnectorCallError, msg, unavailableCallError, } from "../errors.js";
 import { CONNECTA_VERSION } from "../version.js";
@@ -587,7 +588,20 @@ export function remoteMcp(id, opts) {
     const newProvider = (ctx, state) => {
         if (state?.provider)
             return state.provider;
-        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`, refreshCoordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx));
+        const provider = new KvOAuthProvider(id, ctx.storage, `${ctx.baseUrl}/oauth/callback/${id}`, refreshCoordinator, ctx.allowAuthorization === true, oauthSealerFor(ctx), ctx.signal, JSON.stringify({
+            url: new URL(opts.url).href,
+            redirectUri: `${ctx.baseUrl}/oauth/callback/${id}`,
+            clientMetadata: {
+                redirect_uris: [`${ctx.baseUrl}/oauth/callback/${id}`],
+                client_name: "connecta",
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                token_endpoint_auth_method: "none",
+            },
+            authScope: opts.authScope ?? "shared",
+            versionNegotiation: opts.versionNegotiation ?? "auto",
+            redirects: opts.redirects ?? "none",
+        }), (reset) => trackOAuthStartReset(ctx.requestScope ?? ctx, reset));
         if (state)
             state.provider = provider;
         return provider;
@@ -775,6 +789,7 @@ export function remoteMcp(id, opts) {
             // SDK v2 selects its validator by runtime export condition: AJV on
             // Node and @cfworker/json-schema under workerd. The Workers-safe path
             // no longer needs Connecta-specific wiring.
+            const handshakeAbort = new AbortController();
             const c = new Client({ name: "connecta", version: CONNECTA_VERSION }, {
                 versionNegotiation: {
                     mode: opts.versionNegotiation ?? "auto",
@@ -783,6 +798,19 @@ export function remoteMcp(id, opts) {
                 // below as one structured, non-retryable connector failure.
                 inputRequired: { autoFulfill: false },
             });
+            // @modelcontextprotocol/client 2.0.0 can attempt the legacy initialized
+            // notification after we close its transport. Its rejected Promise is
+            // unhandled under workerd even though connect() has a caller. This
+            // connection is already abandoned, so skip only that final handshake
+            // notification after our abort. Remove when the SDK owns this race:
+            // https://github.com/modelcontextprotocol/typescript-sdk/issues/2864
+            const notify = c.notification.bind(c);
+            c.notification = (message, options) => {
+                if (handshakeAbort.signal.aborted && message.method === "notifications/initialized") {
+                    return Promise.resolve();
+                }
+                return notify(message, options);
+            };
             const t = buildTransport(ctx, provider, credentialFramed);
             if (!owned()) {
                 detach(closeConnection(null, t, ctx.logger));
@@ -794,11 +822,11 @@ export function remoteMcp(id, opts) {
             // what aborts a connect still in flight.
             const lease = Scope.forkUnsafe(state.scope);
             const held = { client: null };
-            yield* Scope.addFinalizer(lease, Effect.suspend(() => closeConnection(held.client, t, ctx.logger)));
+            yield* Scope.addFinalizer(lease, Effect.sync(() => handshakeAbort.abort()).pipe(Effect.andThen(Effect.suspend(() => closeConnection(held.client, t, ctx.logger)))));
             state.lease = lease;
             state.transport = t;
             return yield* Effect.gen(function* () {
-                yield* promised(() => c.connect(t));
+                yield* promised(() => c.connect(t, { signal: handshakeAbort.signal }));
                 // A probe deadline can end its scope while connect is still in flight.
                 // The transport is closed immediately by closeScope; if connect wins
                 // that race anyway, close the resulting client rather than resurrecting
@@ -857,13 +885,14 @@ export function remoteMcp(id, opts) {
             }));
         });
     };
-    const disconnectAuthorization = async (ctx, state, operatorDisconnected = false) => {
+    const disconnectAuthorization = async (ctx, state, operatorDisconnected = false, preserveClient = false) => {
         const provider = newProvider(ctx, state);
         // Publish the replacement epoch before waiting on or closing any
         // request-local transport. A hung connect therefore cannot delay the
         // fence, and every late OAuth write stays in the older namespace.
+        const reset = provider.resetAuthorization(operatorDisconnected, preserveClient);
         try {
-            await provider.resetAuthorization(operatorDisconnected);
+            await reset;
         }
         finally {
             // Abandon any connect in flight and close whichever half of the
@@ -1181,22 +1210,32 @@ export function remoteMcp(id, opts) {
             const state = stateFor(ctx);
             state.provider = null;
             const p = newProvider(ctx, state);
-            if (startOpts?.force || (await p.operatorDisconnected())) {
-                await disconnectAuthorization(ctx, state);
+            if (ctx.signal?.aborted)
+                throw ctx.signal.reason;
+            const disconnected = startOpts?.force ? false : await p.operatorDisconnected();
+            if (ctx.signal?.aborted)
+                throw ctx.signal.reason;
+            if (startOpts?.force || disconnected) {
+                await disconnectAuthorization(ctx, state, false, startOpts?.force === true);
             }
             else {
                 // A consent URL already outstanding? Re-issue it rather than re-running
                 // the SDK flow, which would overwrite the PKCE verifier and invalidate
-                // the URL the operator may be mid-consent on.
-                const pending = await p.pendingAuthorizationUrl();
+                // the URL the operator may be mid-consent on. Only a recent one: an
+                // old or untimed URL falls through to a fresh flow in this same
+                // epoch, which keeps the stored client registration and discovery.
+                const pending = await p.reusablePendingAuthorizationUrl();
                 if (pending) {
                     return {
                         state: "auth_required",
                         authorizationUrl: pending,
+                        authorizationReused: true,
                         message: "Authorization required — open the URL to connect.",
                     };
                 }
             }
+            if (ctx.signal?.aborted)
+                throw ctx.signal.reason;
             try {
                 await ensureConnected(ctx, state);
                 return {

package/dist/errors.d.ts

@@ -15,7 +15,14 @@ export type ConnectorCallErrorCode = "timeout" | "auth_required" | "rate_limited
  * code stays `connector_call_failed` or `auth_required` with a message that
  * states the ambiguity (H11).
  */
- | "not_found" | "input_required_unsupported" | "connector_call_failed";
+ | "not_found"
+/**
+ * The write named a base version or revision that is no longer current:
+ * someone else changed the thing first. The caller re-reads, reapplies its
+ * change, and retries with the base `current` reports — repeating the same
+ * call can never succeed, and waiting will not help either.
+ */
+ | "conflict" | "input_required_unsupported" | "connector_call_failed";
 /** One bounded, payload-free explanation of an input-schema mismatch. */
 export interface ArgumentValidationIssue {
     /** JSON Pointer into the submitted arguments; "/" means the root value. */
@@ -88,12 +95,18 @@ export declare class ConnectorCallError extends Error {
     readonly validation: ArgumentValidationDetails | undefined;
     /** Sanitized transport diagnostics for `unavailable` only. */
     readonly details: UnavailableDetails | undefined;
+    /**
+     * For `conflict` only: where each thing the write touched stands now, e.g.
+     * `{ revision: 12, view: 7 }`. Bounded to 20 whole-number entries.
+     */
+    readonly current: Readonly<Record<string, number>> | undefined;
     constructor(code: ConnectorCallErrorCode, message: string, opts?: {
         retryable?: boolean;
         retryAfterMs?: number;
         cause?: unknown;
         validation?: ArgumentValidationDetails;
         details?: UnavailableDetails;
+        current?: Readonly<Record<string, number>>;
     });
 }
 /** The `error` object surfaced in value-mode call results and rejected promises. */
@@ -107,6 +120,8 @@ export interface CallErrorDetails {
     retryAfterMs?: number;
     /** Bounded input-schema findings; paths and expectations, never values. */
     validation?: ArgumentValidationDetails;
+    /** On a `conflict`: where each thing the write touched stands now. */
+    current?: Readonly<Record<string, number>>;
     /** Connector whose failed operation needs recovery. */
     connector?: string;
     /** Canonical downstream address the agent may retry after recovery. */

package/dist/errors.js

@@ -162,9 +162,30 @@ const RETRYABLE_BY_CODE = {
     auth_required: false,
     invalid_args: false,
     not_found: false,
+    conflict: false,
     input_required_unsupported: false,
     connector_call_failed: false,
 };
+/** Entries a conflict's `current` map may carry. */
+const MAX_CURRENT_ENTRIES = 20;
+const MAX_CURRENT_KEY_CHARS = 128;
+/**
+ * Where each thing a conflicting write touched stands now: short names to
+ * whole non-negative numbers, at most 20 of them. Anything else is dropped
+ * whole rather than clipped, because a truncated key names a different thing.
+ */
+function boundedCurrent(current) {
+    if (!current || typeof current !== "object")
+        return undefined;
+    const entries = Object.entries(current).filter(([key, value]) => key.length > 0 &&
+        key.length <= MAX_CURRENT_KEY_CHARS &&
+        key !== "__proto__" &&
+        Number.isSafeInteger(value) &&
+        value >= 0);
+    if (entries.length === 0)
+        return undefined;
+    return Object.freeze(Object.fromEntries(entries.slice(0, MAX_CURRENT_ENTRIES)));
+}
 /** Non-negative integer milliseconds, or undefined for anything else. */
 function normalizeRetryAfterMs(value) {
     if (value === undefined)
@@ -201,6 +222,11 @@ export class ConnectorCallError extends Error {
     validation;
     /** Sanitized transport diagnostics for `unavailable` only. */
     details;
+    /**
+     * For `conflict` only: where each thing the write touched stands now, e.g.
+     * `{ revision: 12, view: 7 }`. Bounded to 20 whole-number entries.
+     */
+    current;
     constructor(code, message, opts = {}) {
         super(message, opts.cause !== undefined ? { cause: opts.cause } : undefined);
         this.name = "ConnectorCallError";
@@ -211,6 +237,7 @@ export class ConnectorCallError extends Error {
             code === "unavailable" ? sanitizedUnavailableDetails(opts.details) : undefined;
         this.validation =
             code === "invalid_args" ? boundedValidation(opts.validation) : undefined;
+        this.current = code === "conflict" ? boundedCurrent(opts.current) : undefined;
     }
 }
 /**
@@ -262,6 +289,7 @@ export function classifyCallError(err, fallbackCode = "connector_call_failed") {
                 : {}),
             ...(err.validation ? { validation: err.validation } : {}),
             ...(err.details ? { details: err.details } : {}),
+            ...(err.current ? { current: err.current } : {}),
         };
     }
     // An aborted fetch rejects with a DOMException named "AbortError" whose