@zackbart/connecta 0.41.0 → 0.42.0

package/dist/auth-elicitation.js

@@ -3,7 +3,7 @@ import { RequestScope, requestOwner } from "./runtime/request-scope.js";
 import { upwardStep } from "./upward.js";
 import { authAwait, authCall, authInvoke, authFlow, authMethod, registerAuthMethod, authOwnMethod, } from "./auth/native.js";
 import { registryProgram } from "./runtime/registry.js";
-import { enableAuthorizationHandoffs } from "./authorization-handoff.js";
+import { authorizationHandoff, connectLinkFields, enableAuthorizationHandoffs } from "./authorization-handoff.js";
 import { createRequestStateCodec, inputRequired, ProtocolError, INVALID_PARAMS, PROTOCOL_VERSION_META_KEY, CLIENT_CAPABILITIES_META_KEY, } from "@modelcontextprotocol/server";
 import { Effect } from "effect";
 import { runEdge, withDeadlineEffect } from "./runtime/run.js";
@@ -17,6 +17,23 @@ import { DownstreamElicitation, MAX_RELAY_STATE_CHARS, } from "./downstream-inpu
 import { canonicalState as canonical, requestDigest as digest, stateObject as object, invalidRequestState as invalidState, REQUEST_STATE_TTL_MS as TTL_MS, MAX_INPUT_ROUNDS as MAX_ROUNDS, } from "./request-state.js";
 const INPUT_KEY = "connecta_auth";
 const MESSAGE = "Connect this service in your browser, then retry the request.";
+// A client may answer without showing anything, and the response cannot prove
+// otherwise. Neither text claims a person saw the prompt, and neither names a
+// route: an agent told to call again would only reach the same refusal.
+const REFUSED = {
+    decline: {
+        code: "auth_declined",
+        message: "The client declined the connection prompt, possibly automatically, so the user may not have seen it. Nothing was retried.",
+    },
+    cancel: {
+        code: "auth_cancelled",
+        message: "The client cancelled the connection prompt, possibly automatically, so the user may not have seen it. Nothing was retried.",
+    },
+};
+// Only a repeat can recover a refusal whose link failed, and it asks for a new
+// prompt, so a person's refusal stays final. Nothing on the server limits it to one.
+const REFUSED_NO_LINK = " No connection link could be issued. If the user has not refused this connection, repeat this request once for a new link, then give it to them. Stop if that repeat also fails.";
+const refusedPurpose = (recipient) => `Give this link to the user, unchanged, ${recipient}once, then stop. Do not prompt again, retry, or reach this service another way until they confirm. If they already refused this connection in this conversation, only mention that the link is available.`;
 function failure(code, message) {
     return toolError({ code, message, retryable: false }, { ok: false });
 }
@@ -45,14 +62,26 @@ export class AuthElicitation {
             context,
         ]));
     }
-    browserProgress(state) {
-        return runEdge(authOwnMethod(AuthElicitation.prototype, this, "browserProgress", [
-            state,
-        ]));
+    browserCompleted(state) {
+        return runEdge(authOwnMethod(AuthElicitation.prototype, this, "browserCompleted", [state]));
     }
     connected(id, context) {
         return runEdge(authOwnMethod(AuthElicitation.prototype, this, "connected", [id, context]));
     }
+    refused(action, state, force) {
+        return runEdge(authOwnMethod(AuthElicitation.prototype, this, "refused", [action, state, force]));
+    }
+    /** The one gate before any recovery link: this caller may connect this connector here. */
+    mayConnect(id) {
+        const { registry, principal, publicUrl, canManage, unavailable, credentialUi } = this.options;
+        const connector = typeof id === "string" ? registry.getConnector(id) : undefined;
+        return (typeof id === "string" &&
+            /^[a-z0-9_-]+$/.test(id) &&
+            Boolean(connector?.startAuth || (connector?.credential && credentialUi)) &&
+            Boolean(principal && publicUrl) &&
+            !unavailable &&
+            canManage(id));
+    }
     bind(context) {
         this.downstream.bind(context);
     }
@@ -114,12 +143,8 @@ export class AuthElicitation {
                     !(yield* upwardStep(authInvoke(self.options, "claimRetry", [previous.connector, previous.browserNonces.at(-1)])))) {
                     return failure("invalid_request_state", "Invalid or expired requestState");
                 }
-                if (previous && object(response)) {
-                    if (response.action === "decline")
-                        return failure("auth_declined", "Connection was declined. The request was not retried.");
-                    if (response.action === "cancel")
-                        return failure("auth_cancelled", "Connection was cancelled. The request was not retried.");
-                }
+                if (previous && object(response) && (response.action === "decline" || response.action === "cancel"))
+                    return yield* upwardStep(authInvoke(self, "refused", [response.action, previous, args.force]));
                 if (previous?.reads.length) {
                     const catalog = new CatalogService(self.options.registry, self.options.publicUrl, {
                         requestScope: self.options.requestScope,
@@ -156,18 +181,12 @@ export class AuthElicitation {
                     }
                     bindReplayReads(self.options.requestScope, previous.reads);
                 }
-                const browser = previous && tool === "authorize_connector"
-                    ? yield* upwardStep(authInvoke(self, "browserProgress", [previous]))
-                    : undefined;
-                if (browser?.completed && previous) {
-                    // Retire unspent links before the status read. A browser claim racing
-                    // these CASes either wins and is observed as pending, or is refused.
-                    yield* upwardStep(authInvoke(self.options, "closeLinks", [previous.connector, previous.browserNonces]));
-                    if ((yield* upwardStep(authInvoke(self, "browserProgress", [previous]))).completed &&
-                        (yield* upwardStep(authInvoke(self, "connected", [previous.connector, context])))) {
-                        const structuredContent = { connector: previous.connector, status: "ok" };
-                        return { structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
-                    }
+                if (previous &&
+                    tool === "authorize_connector" &&
+                    (yield* upwardStep(authInvoke(self, "browserCompleted", [previous]))) &&
+                    (yield* upwardStep(authInvoke(self, "connected", [previous.connector, context])))) {
+                    const structuredContent = { connector: previous.connector, status: "ok" };
+                    return { structuredContent, content: [{ type: "text", text: JSON.stringify(structuredContent) }] };
                 }
                 const envelope = context.mcpReq.envelope;
                 const capabilities = envelope?.[CLIENT_CAPABILITIES_META_KEY];
@@ -216,16 +235,8 @@ export class AuthElicitation {
                         content: [{ type: "text", text: JSON.stringify(structuredContent) }],
                     };
                 }
-                const { registry, vault, principal, publicUrl, canManage, unavailable } = self.options;
-                const connector = typeof id === "string" ? registry.getConnector(id) : undefined;
-                const recoverable = connector?.startAuth || (connector?.credential && self.options.credentialUi);
-                if (typeof id !== "string" ||
-                    !/^[a-z0-9_-]+$/.test(id) ||
-                    !recoverable ||
-                    !principal ||
-                    !publicUrl ||
-                    unavailable ||
-                    !canManage(id))
+                const { vault, principal } = self.options;
+                if (!self.mayConnect(id) || !principal)
                     return result;
                 // Incapable hosts already received the shared explicit-authorization handoff.
                 if (!capable)
@@ -237,9 +248,9 @@ export class AuthElicitation {
                         ...result.structuredContent,
                         error: {
                             ...result.structuredContent?.error,
-                            authorizationUrl: error.authorizationUrl ??
+                            ...connectLinkFields(error, id, error.authorizationUrl ??
                                 (yield* upwardStep(authInvoke(self.options, "connectLink", [id])))
-                                    .url,
+                                    .url),
                         },
                     };
                     return {
@@ -250,13 +261,13 @@ export class AuthElicitation {
                 }
                 if (previous && previous.round >= MAX_ROUNDS)
                     return failure("auth_round_limit", "Connection is still required after three prompts. Connect explicitly, then start a new request.");
-                // Once a verified browser has started this attempt, retries continue it.
-                // A pending consent must never be reset by another force=true prompt.
+                // Accept is consent to open the link, not proof it opened, so every round's
+                // link stays live and they share one reset (claimOAuthConnectStart).
                 const forced = explicit && args.force === true;
                 const link = yield* upwardStep(authInvoke(self.options, "connectLink", [
                     id,
-                    forced && !browser?.predecessor,
-                    forced ? browser?.predecessor : undefined,
+                    forced,
+                    forced ? previous?.browserNonces[0] : undefined,
                 ]));
                 const state = {
                     version: 1,
@@ -285,7 +296,7 @@ export class AuthElicitation {
                         ...result.structuredContent,
                         error: {
                             ...result.structuredContent?.error,
-                            authorizationUrl: link.url,
+                            ...connectLinkFields(result.structuredContent?.error, id, link.url),
                         },
                     };
                     return {
@@ -305,6 +316,59 @@ export class AuthElicitation {
                 });
             }), this.options.requestSignal).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
         }, AuthElicitation.prototype.run);
+        registerAuthMethod(AuthElicitation.prototype, "refused", function (action, state, force) {
+            const self = this;
+            return authAwait(authFlow(function* () {
+                const { code, message } = REFUSED[action];
+                const { connector: id, tool } = state;
+                if (!self.mayConnect(id))
+                    return failure(code, message);
+                const { registry, publicUrl, canManage, unavailable, credentialHandoffUrl, routes, requestScope } = self.options;
+                try {
+                    // The signed state bound these arguments, so this is the restart the
+                    // caller asked for, sharing the prompt's reset if that prompt was opened.
+                    const forced = tool === "authorize_connector" && force === true;
+                    // The ordinary handoff, except that the link is the sealed form this
+                    // client was already shown: the agent sees no principal in it.
+                    const handoff = yield* upwardStep(authCall(authorizationHandoff, [
+                        registry,
+                        publicUrl,
+                        requestScope,
+                        {
+                            canManageAuth: canManage,
+                            credentialHandoffUrl,
+                            oauthConnectUnavailable: unavailable,
+                            routes,
+                            oauthConnectUrl: authMethod(() => authInvoke(self.options, "connectLink", [
+                                id,
+                                forced,
+                                forced ? state.browserNonces[0] : undefined,
+                            ]).pipe(Effect.map((link) => link.url))),
+                        },
+                        { connector: id },
+                    ]));
+                    const url = handoff.authorizationUrl ?? handoff.operatorUrl;
+                    if (!url)
+                        return failure(code, message);
+                    if (handoff.authorizationUrl)
+                        sentSecretsForRequest(requestScope).mintedState(handoff.authorizationUrl);
+                    return toolError({
+                        ...handoff,
+                        code,
+                        message,
+                        retryable: false,
+                        nextAction: {
+                            url,
+                            purpose: refusedPurpose(handoff.authorizationUrl ? "" : "for the operator to open, "),
+                        },
+                    }, { ok: false });
+                }
+                catch {
+                    // A signing or storage failure cannot replace the refusal itself.
+                    return failure(code, message + REFUSED_NO_LINK);
+                }
+            }), this.options.requestSignal).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
+        }, AuthElicitation.prototype.refused);
         registerAuthMethod(AuthElicitation.prototype, "connected", function (id, context) {
             const self = this;
             return authAwait(authFlow(function* () {
@@ -331,29 +395,16 @@ export class AuthElicitation {
                 }
             }), this.options.requestSignal).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
         }, AuthElicitation.prototype.connected);
-        registerAuthMethod(AuthElicitation.prototype, "browserProgress", function (state) {
+        registerAuthMethod(AuthElicitation.prototype, "browserCompleted", function (state) {
             const self = this;
             return authAwait(authFlow(function* () {
-                let started;
-                let claimed;
-                let completed = false;
-                let pending = false;
-                for (const nonce of state.browserNonces) {
-                    const progress = yield* upwardStep(authInvoke(self.options, "linkProgress", [
-                        state.connector,
-                        nonce,
-                    ]));
-                    if (progress === "started")
-                        started = nonce;
-                    if (progress === "claimed")
-                        claimed = nonce;
-                    completed ||= progress === "started";
-                    pending ||= progress === "claimed";
-                }
-                const predecessor = started ?? claimed;
-                return { ...(predecessor ? { predecessor } : {}), completed: completed && !pending };
+                // A reset never leaves "started", so no reset can be running behind this link.
+                for (const nonce of state.browserNonces)
+                    if (yield* upwardStep(authInvoke(self.options, "linkStarted", [state.connector, nonce])))
+                        return true;
+                return false;
             }), this.options.requestSignal).pipe(Effect.provideService(RequestScope, requestOwner(this.options.requestScope)));
-        }, AuthElicitation.prototype.browserProgress);
+        }, AuthElicitation.prototype.browserCompleted);
         registerAuthMethod(AuthElicitation.prototype, "verify", function (wire, context) {
             const self = this;
             return authAwait(authFlow(function* () {
@@ -380,7 +431,13 @@ export class AuthElicitation {
                     !Number.isInteger(state.round) ||
                     state.round < 1 ||
                     state.round > MAX_ROUNDS ||
-                    !["call_tool", "call_destructive_tool", "execute_code", "authorize_connector"].includes(String(state.tool)) ||
+                    ![
+                        "call_tool",
+                        "call_destructive_tool",
+                        "execute_code",
+                        "execute_read_code",
+                        "authorize_connector",
+                    ].includes(String(state.tool)) ||
                     typeof state.wireTool !== "string" ||
                     typeof state.digest !== "string" ||
                     !/^[a-f0-9]{64}$/.test(state.digest) ||

package/dist/authorization-handoff.js

@@ -1,4 +1,4 @@
-import { routePhrases } from "./agent-routes.js";
+import { handoffInHand, routePhrases } from "./agent-routes.js";
 import { upwardStep } from "./upward.js";
 import { authCall, authInvoke, authFlow, registerAuth } from "./auth/native.js";
 import { Context, Deferred, Effect, Scheduler } from "effect";
@@ -15,6 +15,38 @@ function outcomeAware(build) {
     afterUnknownWrite.set(handoff, build(true));
     return handoff;
 }
+/**
+ * What to do with a handoff the error already carries. Passing it on is the
+ * whole step: calling authorize_connector would only return the same thing.
+ * After a write of unknown outcome the follow-up reconciles, never retries.
+ */
+function handoffAction(handoff, unknownWrite) {
+    const then = unknownWrite
+        ? "After they confirm, re-read the write's target before any fresh call."
+        : "Retry after they confirm.";
+    const url = handoff.authorizationUrl ?? handoff.operatorUrl;
+    if (!url)
+        return {
+            action: "contact_operator",
+            purpose: `Tell the user the operator must fix this connector, then stop. ${then}`,
+        };
+    return {
+        url,
+        purpose: `Give this link to the user, unchanged, ${handoff.authorizationUrl ? "" : "for the operator to open, "}then stop. ${then}`,
+    };
+}
+const unknownWriteError = (error) => error.writeOutcome === "unknown" || error.reconciliationRequired === true;
+/**
+ * The fields for an auth error given only a connect link, where a capable host's
+ * prompt could not carry it: the same direct step as a full handoff.
+ */
+export function connectLinkFields(error, connector, authorizationUrl) {
+    return {
+        ...(typeof error.message === "string" ? { message: handoffInHand(error.message, connector) } : {}),
+        authorizationUrl,
+        nextAction: handoffAction({ connector, recovery: "oauth", authorizationUrl }, unknownWriteError(error)),
+    };
+}
 function oauthFollowUp(connectorId, unknownWrite, opts) {
     const then = `Then ${unknownWrite ? RECONCILE : "retry the original call"}`;
     // Without programs, no connecta.search can confirm the catalog.
@@ -95,7 +127,7 @@ const authorizationHandoffNative = /* @__PURE__ */ registerAuth(authorizationHan
             recovery: "oauth",
             status: "auth_required",
             authorizationUrl,
-            instructions: "Copy authorizationUrl exactly as returned; do not decode or re-encode it. Open it in a browser and sign in as the user who requested this connection. Connecta verifies your identity and permission before starting consent. " +
+            instructions: "For the person opening this link: sign in as the user who requested this connection; Connecta verifies identity and permission before starting consent. For the agent: pass authorizationUrl on exactly as returned. " +
                 oauthFollowUp(connector.id, unknownWrite, opts),
         }));
     });
@@ -180,7 +212,8 @@ export function withAuthorizationHandoffEffect(scope, error) {
             return {
                 ...error,
                 ...value,
-                message: error.message,
+                message: handoffInHand(error.message, connector),
+                nextAction: handoffAction(value, unknownWriteError(error)),
                 ...(value.message ? { instructions: value.message } : {}),
             };
         }),