@zackbart/connecta 0.28.0 → 0.29.0

package/dist/routes/oauth-client-metadata.js

@@ -0,0 +1,15 @@
+import { selfHostedClientDocument } from "../auth/downstream-client-metadata.js";
+/** Public OAuth client metadata, without auth, storage, discovery, or request-host input. */
+export function routeOAuthClientMetadata(context) {
+    if (!context.path.startsWith("/oauth/client-metadata/"))
+        return null;
+    const id = context.path.slice("/oauth/client-metadata/".length);
+    const connector = context.opts.registry.getConnector(id);
+    const document = connector &&
+        selfHostedClientDocument(connector, context.opts.config.publicUrl, context.opts.config.serverInfo.name);
+    if (!document)
+        return new Response(null, { status: 404 });
+    if (context.request.method !== "GET")
+        return new Response(null, { status: 405, headers: { Allow: "GET" } });
+    return Response.json(document, { headers: { "Cache-Control": "public, max-age=300" } });
+}

package/dist/routes/oauth-management.js

@@ -1,28 +1,17 @@
+import { OAuthRevocationError } from "../auth/downstream-revocation.js";
 import { Effect, Result } from "effect";
-import { drainOAuthStartResets } from "../auth/oauth-start-reset.js";
 import { closeScope } from "../runtime/connector-scope.js";
-import { withDeadlineEffect } from "../runtime/run.js";
-import { isSafeHttpUrl } from "../ui.js";
-import { authorizedPerson, refuse, serveOperator, visibleRegistry, } from "./operator.js";
-import { mayManageConnector, isSameOrigin, msg, privateJson, } from "./shared.js";
-/** Bounds the start and its handoff; invalidation and scope close finish after it. */
-const OAUTH_START_TIMEOUT_MS = 30_000;
-/**
- * How a POST starts authorization, from its `mode` query parameter:
- * `restart` (the default) resets the connector to a fresh epoch — wiping the
- * grant, the client registration, and discovery — before starting over;
- * `continue` hands back a recent pending authorization URL when one exists
- * and otherwise starts a flow in the current epoch, keeping the stored
- * registration. `null` is a malformed request.
- */
+import { oauthConnectUrl, oauthConnectUnavailable } from "../oauth-handoff.js";
+import { authorizedPerson, refuse, serveOperator, visibleRegistry, Answer } from "./operator.js";
+import { failureRecord, logFailure } from "../operator-record.js";
+import { mayManageConnector, isSameOrigin, privateJson } from "./shared.js";
+/** A UI action signs its requested mode; the verified /connect visit applies it. */
 function startMode(url) {
     const modes = url.searchParams.getAll("mode");
     if (modes.length === 0)
         return "restart";
     const [mode] = modes;
-    return modes.length === 1 && (mode === "continue" || mode === "restart")
-        ? mode
-        : null;
+    return modes.length === 1 && (mode === "continue" || mode === "restart") ? mode : null;
 }
 function oauthManagementRequest(context, connectorId) {
     const { request, baseUrl, defer, opts } = context;
@@ -52,101 +41,50 @@ function oauthManagementRequest(context, connectorId) {
         if (mode === null) {
             return yield* refuse('mode must be "continue" or "restart"', 400);
         }
+        if (!disconnecting) {
+            const unavailable = oauthConnectUnavailable(opts);
+            if (unavailable)
+                return yield* refuse(unavailable, 403);
+            const authorizationUrl = yield* Effect.tryPromise({
+                try: () => oauthConnectUrl(opts, baseUrl, connectorId, authz.principalKey, mode === "restart"),
+                catch: () => new Answer(privateJson({ error: "OAuth connection link could not be created" }, { status: 502 })),
+            });
+            // This POST is already an explicit connect action; the browser visit
+            // verifies the signed initiator and applies it without another UI hand-off.
+            const target = new URL(authorizationUrl);
+            if (opts.config.ui)
+                target.searchParams.set("start", "1");
+            return privateJson({ state: "auth_required", authorizationUrl: target.href });
+        }
         let ctx;
         // The connector scope this request opened ends with it, however it ends.
-        yield* Effect.addFinalizer(() => ctx ? closeScope(connector, ctx, defer) : Effect.void);
-        const timeoutError = new Error("OAuth authorization start timed out");
-        const operation = yield* Effect.result(withDeadlineEffect((signal) => Effect.tryPromise({
-            try: async () => {
-                ctx = registry.contextFor(connectorId, baseUrl, {}, { signal });
-                if (disconnecting) {
-                    await disconnectAuth(ctx);
-                    return undefined;
-                }
-                const started = await startAuth(ctx, { force: mode === "restart" });
-                if (signal.aborted)
-                    throw signal.reason;
-                if (started.authorizationUrl) {
-                    await registry.bindOAuthHandoff(connectorId, started.authorizationUrl);
-                }
-                return started;
-            },
+        yield* Effect.addFinalizer(() => (ctx ? closeScope(connector, ctx, defer) : Effect.void));
+        // A disconnect commits through invalidation even if its hook rejects or
+        // the browser leaves. It has no start deadline or request signal.
+        ctx = registry.contextFor(connectorId, baseUrl);
+        const operation = yield* Effect.result(Effect.tryPromise({
+            try: () => disconnectAuth(ctx),
             catch: (error) => error,
-        }), {
-            // A disconnect deliberately ignores both browser cancellation and
-            // this start deadline so its reset reaches invalidation.
-            ...(disconnecting ? {} : { timeoutMs: OAUTH_START_TIMEOUT_MS }),
-            ...(disconnecting ? {} : { signal: request.signal }),
-            timeoutError,
         }));
-        const opened = ctx;
-        if (Result.isFailure(operation) && opened) {
-            // Storage has no abort contract. If a reset's generation write is still
-            // pending, answering now would let it publish over a newer flow.
-            yield* Effect.promise(() => drainOAuthStartResets(opened.requestScope ?? opened));
-        }
-        // A disconnect or a restart invalidates the old grant and its cached
-        // catalog, even when a partially failed physical cleanup left its epoch
-        // fence standing. So does a continued start that had to begin a new flow:
-        // the grant it found was missing or refused. A continued start that
-        // reused a pending URL or found the connection healthy changed nothing,
-        // so the catalog stays. (A continue does reset a disconnected connector,
-        // but the disconnect already invalidated that catalog.)
-        const started = Result.isSuccess(operation) ? operation.success : undefined;
-        const reused = mode === "continue" && started?.authorizationReused === true;
-        const unchanged = mode === "continue" && (reused || started?.state === "ok");
-        const invalidated = unchanged
-            ? Result.succeed(undefined)
-            : yield* Effect.result(Effect.tryPromise({
-                try: () => registry.invalidateStored(connectorId),
-                catch: (error) => error,
-            }));
-        // Every failure below answers in the route's own fixed words. A hook's
-        // rejection and a status message can quote a token endpoint's error body
-        // or a provider's refusal, either of which can quote the secret it was
-        // sent, so that text goes to the deployment's log and nowhere else.
-        const failed = (detail, fixed, status) => {
-            opts.logger.warn(`[connecta] connector "${connectorId}" OAuth ${disconnecting ? "disconnect" : mode} failed: ${detail}`);
-            return refuse(fixed, status);
-        };
-        const couldNot = disconnecting
-            ? "OAuth disconnect failed"
-            : "OAuth authorization could not start";
-        // A Result, not a caught value, decides whether it failed: a hook that
-        // rejects with no reason at all still failed.
-        if (Result.isFailure(operation)) {
-            if (operation.failure === timeoutError) {
-                return yield* failed(`start exceeded ${OAUTH_START_TIMEOUT_MS} ms`, "OAuth authorization start timed out", 504);
+        const invalidated = yield* Effect.result(Effect.tryPromise({
+            try: () => registry.invalidateStored(connectorId),
+            catch: (error) => error,
+        }));
+        if (Result.isFailure(operation) || Result.isFailure(invalidated)) {
+            const error = Result.isFailure(operation)
+                ? operation.failure
+                : Result.isFailure(invalidated)
+                    ? invalidated.failure
+                    : undefined;
+            logFailure(opts.config.logger, "OAuth disconnect failed", failureRecord({ connector: connectorId }, error));
+            if (error instanceof OAuthRevocationError && !Result.isFailure(invalidated)) {
+                return privateJson({ state: "auth_required", code: "oauth_revocation_failed" });
             }
-            return yield* failed(msg(operation.failure), couldNot, 400);
-        }
-        if (Result.isFailure(invalidated)) {
-            return yield* failed(`stored-state invalidation: ${msg(invalidated.failure)}`, couldNot, 400);
-        }
-        const result = operation.success;
-        if (!result) {
-            return new Response(null, {
-                status: 204,
-                headers: {
-                    "Cache-Control": "no-store",
-                    "Referrer-Policy": "no-referrer",
-                },
-            });
-        }
-        const authorizationUrl = isSafeHttpUrl(result.authorizationUrl)
-            ? result.authorizationUrl
-            : undefined;
-        if (result.state === "error") {
-            return yield* failed(result.message || "the connector reported an error state", couldNot, 502);
-        }
-        if (result.state === "auth_required" && !authorizationUrl) {
-            return yield* failed(result.message || "consent is required but no safe authorization URL was returned", "OAuth authorization requires consent but no safe URL is available", 502);
+            return yield* refuse("OAuth disconnect failed", 400);
         }
-        // No message: a status message is the same text the Connections page
-        // stopped shipping, and the state and the link are the whole answer.
-        return privateJson({
-            state: result.state,
-            ...(authorizationUrl ? { authorizationUrl, reused } : {}),
+        return new Response(null, {
+            status: 204,
+            headers: { "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" },
         });
     }).pipe(Effect.scoped);
 }

package/dist/routes/oauth.js

@@ -1,9 +1,13 @@
 import { Effect } from "effect";
+import { htmlSecurityHeaders } from "../html-security.js";
+import { authorizationCredential } from "../inbound-credential.js";
 import { closeConnectorScope } from "../connector-scope.js";
-import { oauthValueStorageKey } from "../auth/downstream-oauth.js";
+import { OAuthCallbackClaimedError, oauthStateDigest } from "../auth/downstream-oauth.js";
+import { failureRecord, logFailure } from "../operator-record.js";
+import { oauthFlowKeys } from "../storage/keys.js";
 import { escapeHtml, renderPage, resolveBranding, STATUS_ICONS } from "../branding.js";
-import { oauthCallbackOutcome, providerErrorReason, } from "../oauth-callback-outcome.js";
-import { authorizeUiIdentity, mayManageConnector, validateAuthPermissions, loggableValue, msg, } from "./shared.js";
+import { oauthCallbackOutcome, providerErrorReason } from "../oauth-callback-outcome.js";
+import { authorizeUiIdentity, withSessionCookies, mayManageConnector, validateAuthPermissions, loggableValue, } from "./shared.js";
 const TONE_MARKS = {
     ok: { className: " ok", icon: STATUS_ICONS.ok, label: "Connected" },
     declined: { className: "", icon: STATUS_ICONS.declined, label: "Not connected" },
@@ -24,10 +28,10 @@ const TONE_MARKS = {
  * under a quiet disclosure rather than in the message.
  */
 function html(reason, opts, connector) {
-    const brand = resolveBranding(opts.branding);
+    const brand = resolveBranding(opts.config.ui?.branding);
     const outcome = oauthCallbackOutcome(reason, connector, brand.productName);
     const mark = TONE_MARKS[outcome.tone];
-    const uiMounted = Boolean(opts.ui);
+    const uiMounted = Boolean(opts.config.ui);
     const home = uiMounted
         ? `<div class="status-actions"><a class="btn${outcome.tone === "ok" ? "" : " primary"}" href="/">Return to ${escapeHtml(brand.productName)}</a></div>`
         : "";
@@ -50,23 +54,23 @@ function html(reason, opts, connector) {
     ${details}
   </section>
 </main>`;
-    return new Response(renderPage(opts.branding, {
+    return new Response(renderPage(opts.config.ui?.branding, {
         title: `${outcome.heading} — ${brand.pageTitle}`,
         uiMounted,
         body,
-    }), { status: outcome.status, headers: { "Content-Type": "text/html; charset=utf-8" } });
+    }), { status: outcome.status, headers: htmlSecurityHeaders({ "Content-Type": "text/html; charset=utf-8" }) });
 }
 /**
  * Pay the storage read a real downstream-OAuth refusal pays, on the refusal
  * paths that would otherwise pay nothing.
  *
  * Identical bodies do not hide a connector id if the clock still sorts them.
- * `KvOAuthProvider.verifyState` reads `oauth:state` and its generation before
- * it can reject a mismatched value, so a configured id costs two storage round
- * trips on the ordinary path while an id naming nothing used to touch no I/O.
- * That gap is an oracle: sample the two and a wordlist recovers the connector
- * list the flat 400 was meant to withhold. So zero-I/O refusals read the same
- * keys in the same `conn:<id>:` namespace, where an unconfigured id gets misses.
+ * `KvOAuthProvider.verifyState` reads the consent the state names before it
+ * can reject it, so a configured id costs a storage round trip on the
+ * ordinary path while an id naming nothing used to touch no I/O. That gap is
+ * an oracle: sample the two and a wordlist recovers the connector list the
+ * flat 400 was meant to withhold. So zero-I/O refusals read the same key in
+ * the same `conn:<id>:` namespace, where an unconfigured id gets a miss.
  *
  * This is deliberately *not* a constant-time claim: a hit and a miss are not
  * identical in a KV store, and a connector shipping its own `verifyState` may
@@ -78,10 +82,9 @@ function html(reason, opts, connector) {
  * turning it into a 500 would hand back exactly the distinguishable response
  * this whole path exists to deny.
  */
-async function equalizeRefusalCost(context) {
+async function equalizeRefusalCost(context, state) {
     try {
-        const generation = await context.storage.get("oauth:generation");
-        await context.storage.get(oauthValueStorageKey("oauth:state", generation));
+        await context.storage.get(oauthFlowKeys.flow(await oauthStateDigest(state ?? "")));
     }
     catch {
         // Deliberately ignored — see above.
@@ -100,16 +103,50 @@ async function equalizeRefusalCost(context) {
 export function routeOAuthCallback(context) {
     if (!context.path.startsWith("/oauth/callback/"))
         return Effect.succeed(null);
+    // Downstream OAuth uses query-mode redirects; form_post is not supported.
+    if (context.request.method !== "GET")
+        return Effect.succeed(new Response(null, {
+            status: 405,
+            headers: { Allow: "GET" },
+        }));
     return Effect.uninterruptible(Effect.promise(() => finishOAuthCallback(context)));
 }
+/**
+ * RFC 6749's error codes (sections 4.1.2.1 and 5.2) and RFC 8707's
+ * `invalid_target`. Only a code on this list is logged: the `code` an OAuth
+ * error carries is the provider's own text.
+ */
+const TOKEN_ERROR_CODES = new Set([
+    "invalid_request",
+    "invalid_client",
+    "invalid_grant",
+    "unauthorized_client",
+    "unsupported_grant_type",
+    "invalid_scope",
+    "invalid_target",
+    "access_denied",
+    "server_error",
+    "temporarily_unavailable",
+]);
+/** ` with OAuth error <code>` for a known code; nothing for anything else. */
+function exchangeErrorCode(err) {
+    const code = err?.code;
+    return typeof code === "string" && TOKEN_ERROR_CODES.has(code) ? ` with OAuth error ${code}` : "";
+}
+/** The provider's own refusal of a duplicate callback, wherever it is wrapped. */
+function claimedByAnotherCallback(err) {
+    const seen = new Set();
+    for (let current = err; current instanceof Error && !seen.has(current); current = current.cause) {
+        if (current instanceof OAuthCallbackClaimedError)
+            return true;
+        seen.add(current);
+    }
+    return false;
+}
 async function finishOAuthCallback(context) {
     const { path, url, baseUrl, opts } = context;
     const error = url.searchParams.get("error");
-    if (error)
-        return html(providerErrorReason(error), opts);
     const code = url.searchParams.get("code");
-    if (!code)
-        return html("invalid_callback", opts);
     const id = path.slice("/oauth/callback/".length);
     const state = url.searchParams.get("state");
     const callbackTarget = await opts.registry.oauthCallbackView(id, state);
@@ -121,38 +158,40 @@ async function finishOAuthCallback(context) {
     // nor touches storage for an unknown id, which is what lets the refusals
     // below borrow it to equalize their cost.
     const connectorContext = callbackRegistry
-        ? callbackRegistry.contextFor(id, baseUrl)
-        : opts.registry.contextFor(id, baseUrl);
+        ? callbackRegistry.contextFor(id, baseUrl, {}, context.defer ? { defer: context.defer } : {})
+        : opts.registry.contextFor(id, baseUrl, {}, context.defer ? { defer: context.defer } : {});
     const refused = () => html("invalid_callback", opts);
     if (!connector || !connector.finishAuth) {
-        await equalizeRefusalCost(connectorContext);
+        await equalizeRefusalCost(connectorContext, state);
         return refused();
     }
     try {
         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 {
-                validateAuthPermissions(browserIdentity, opts.registry);
-            }
-            catch {
-                return refused();
-            }
-            if (!mayManageConnector(browserIdentity, connector) || (expectedPrincipalKey && browserIdentity.principalKey !== expectedPrincipalKey))
-                return refused();
+        const browserIdentity = await authorizeUiIdentity(context.request, baseUrl, opts.config.auth, "OAuth callback", context.runtimeContext, opts.config.identity);
+        if (!browserIdentity.ok) {
+            if (browserIdentity.response.status === 401 && authorizationCredential(context.request).kind !== "absent")
+                return browserIdentity.response;
+            // A Clerk browser handshake refreshes its session and returns to this
+            // exact callback. It grants no identity and exchanges no code yet.
+            if (browserIdentity.response.status === 307 && browserIdentity.response.headers.has("location"))
+                return browserIdentity.response;
+            return refused();
+        }
+        if (!expectedPrincipalKey || browserIdentity.principalKey !== expectedPrincipalKey)
+            return refused();
+        try {
+            validateAuthPermissions(browserIdentity, opts.registry);
         }
-        else if (browserIdentity.response.status === 403 && opts.auth.some(provider => provider.interactiveOperator)) {
+        catch {
             return refused();
         }
+        if (!mayManageConnector(browserIdentity, connector))
+            return refused();
         // CSRF / login-fixation guard: this route is intentionally public, so verify
         // the `state` matches the flow connecta started BEFORE exchanging the code.
         if (!connector.verifyState) {
-            await equalizeRefusalCost(connectorContext);
-            opts.logger.warn(`[connecta] refused an OAuth callback for connector ` +
+            await equalizeRefusalCost(connectorContext, state);
+            opts.config.logger.warn(`[connecta] refused an OAuth callback for connector ` +
                 `${loggableValue(id)} with 400: it implements finishAuth but no ` +
                 "verifyState, so connecta cannot establish that it started this flow. " +
                 "No authorization code was exchanged. Implement verifyState before " +
@@ -164,15 +203,11 @@ async function finishOAuthCallback(context) {
             stateMatches = await connector.verifyState(state, connectorContext);
         }
         catch (err) {
-            opts.logger.warn(`[connecta] refused an OAuth callback for connector ` +
-                `${loggableValue(id)} with 400: verifyState threw ` +
-                `${loggableValue(msg(err))}. No authorization code was exchanged. ` +
-                "Re-run authorization from connecta and check the verifier if it " +
-                "fails again.");
+            logFailure(opts.config.logger, "OAuth callback verifyState threw; no authorization code was exchanged", failureRecord({ connector: id }, err));
             return refused();
         }
         if (!stateMatches) {
-            opts.logger.warn(`[connecta] refused an OAuth callback for connector ` +
+            opts.config.logger.warn(`[connecta] refused an OAuth callback for connector ` +
                 `${loggableValue(id)} with 400: ` +
                 (state === null
                     ? "the state parameter was missing"
@@ -181,28 +216,72 @@ async function finishOAuthCallback(context) {
                 "connecta and try again.");
             return refused();
         }
-        if (connector.authScope === "personal") {
+        // Error responses are callbacks too: neither their code nor their copy is
+        // interpreted until the state and the consent's issuer have been validated.
+        if (["state", "iss", "code", "error"].some((name) => url.searchParams.getAll(name).length > 1))
+            return refused();
+        try {
+            const issuer = url.searchParams.get("iss");
+            if (connector.verifyCallbackIssuer) {
+                if (!(await connector.verifyCallbackIssuer(issuer, connectorContext)))
+                    return refused();
+            }
+            else if (issuer !== null) {
+                // A custom connector with no issuer validator cannot vouch for this response.
+                return refused();
+            }
+        }
+        catch {
+            return refused();
+        }
+        if (error === null && !code)
+            return refused();
+        if (error !== null && !connector.consumeAuthError)
+            return refused();
+        {
             try {
-                await opts.registry.clearOAuthHandoff(id, state);
+                if (!(await opts.registry.consumeOAuthHandoff(id, state, expectedPrincipalKey)))
+                    return refused();
             }
             catch (err) {
-                opts.logger.warn(`[connecta] refused an OAuth callback for connector ` +
-                    `${loggableValue(id)} with 500: its principal handoff could not be ` +
-                    `consumed (${loggableValue(msg(err))}). No authorization code was exchanged.`);
+                logFailure(opts.config.logger, "OAuth callback handoff could not be consumed; no authorization code was exchanged", failureRecord({ connector: id }, err));
                 return html("handoff_failed", opts, connector);
             }
         }
+        if (error !== null) {
+            try {
+                await connector.consumeAuthError(connectorContext);
+            }
+            catch (err) {
+                if (claimedByAnotherCallback(err))
+                    return refused();
+                logFailure(opts.config.logger, "OAuth error callback consent could not be consumed; no authorization code was exchanged", failureRecord({ connector: id }, err));
+                return withSessionCookies(html("handoff_failed", opts, connector), browserIdentity.sessionCookies);
+            }
+            return withSessionCookies(html(providerErrorReason(error), opts), browserIdentity.sessionCookies);
+        }
         try {
             await connector.finishAuth(code, connectorContext, url.searchParams);
             await callbackRegistry.invalidateStored(id);
-            return html("connected", opts, connector);
+            return withSessionCookies(html("connected", opts, connector), browserIdentity.sessionCookies);
         }
         catch (err) {
-            // The page names the reason and nothing else; what the exchange threw can
-            // quote a token endpoint's body, so it goes only to the operator log.
-            opts.logger.warn(`[connecta] OAuth callback for connector ${loggableValue(id)} failed ` +
-                `with 500: the authorization code exchange threw ${loggableValue(msg(err))}.`);
-            return html("exchange_failed", opts, connector);
+            // A duplicate of a callback that already claimed this consent sent
+            // nothing: it is the already-used link the flat refusal describes, not
+            // an exchange the provider rejected.
+            if (claimedByAnotherCallback(err)) {
+                opts.config.logger.warn(`[connecta] refused an OAuth callback for connector ` +
+                    `${loggableValue(id)} with 400: another callback had already ` +
+                    "claimed its state. No authorization code was exchanged.");
+                return refused();
+            }
+            // Neither the page nor the log repeats what the exchange threw: the SDK
+            // quotes the token endpoint's error_description or raw body, and a
+            // provider echoing a client_secret_post request puts the secret there.
+            opts.config.logger.warn(`[connecta] OAuth callback for connector ${loggableValue(id)} failed ` +
+                `with 500: the authorization code exchange failed${exchangeErrorCode(err)}. ` +
+                "Check the connector's client configuration and re-run authorization.");
+            return withSessionCookies(html("exchange_failed", opts, connector), browserIdentity.sessionCookies);
         }
     }
     finally {

package/dist/routes/operator.js

@@ -36,15 +36,15 @@ export function refuse(error, status) {
     return Effect.fail(new Answer(privateJson({ error }, { status })));
 }
 function admitted(result) {
-    return Effect.flatMap(Effect.promise(() => result), (authz) => authz.ok ? Effect.succeed(authz) : Effect.fail(new Answer(authz.response)));
+    return Effect.flatMap(Effect.promise(() => result), (authz) => (authz.ok ? Effect.succeed(authz) : Effect.fail(new Answer(authz.response))));
 }
 /** Any configured caller. The gate's refusal, challenge headers and all, is the answer. */
 export function authorized({ request, baseUrl, opts, runtimeContext }, partitionIdentity = true) {
-    return Effect.suspend(() => admitted(authorize(request, baseUrl, opts.auth, runtimeContext, opts.identity, partitionIdentity)));
+    return Effect.suspend(() => admitted(authorize(request, baseUrl, opts.config.auth, runtimeContext, opts.config.identity, partitionIdentity)));
 }
 /** A signed-in person, for a route that changes how a connector authenticates. */
 export function authorizedPerson({ request, baseUrl, opts, runtimeContext }, purpose) {
-    return Effect.suspend(() => admitted(authorizeUiIdentity(request, baseUrl, opts.auth, purpose, runtimeContext, opts.identity)));
+    return Effect.suspend(() => admitted(authorizeUiIdentity(request, baseUrl, opts.config.auth, purpose, runtimeContext, opts.config.identity)));
 }
 /** The partition and tool grants an identity carries into a registry view. */
 export function scopeFor(authz, connectorIds = authz.connectorIds) {

package/dist/routes/shared.d.ts

@@ -1,66 +1,30 @@
-import type { Implementation } from "@modelcontextprotocol/server";
-import type { AccessTokensModule, ActivityModule, ArtifactsModule, OperatorSurface } from "../module-contracts.js";
-import type { ActivityActor, ActivityReadGate, ActivityStore } from "../activity.js";
-import type { CredentialVault } from "../credential-contract.js";
+import type { ActivityActor } from "../activity.js";
 import type { DeferredWork } from "../connector-scope.js";
 import type { AdmissionController } from "../executor-admission.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 { ApprovalPolicy } from "../tool-safety.js";
-import type { ConnectorPermission, ConnectaIdentityConfig } from "../index.js";
+import type { AuthenticatedIdentity, Executor, InboundAuth, InboundAuthRuntimeContext } from "../types.js";
+import type { ConnectorPermission, ConnectaIdentityConfig, ResolvedConfig } from "../config.js";
 export { msg } from "../errors.js";
 export interface ServerOptions {
+    /**
+     * Everything createConnecta resolved from configuration: auth, identity,
+     * URLs, modules, logger, and every limit with its default applied. Routes
+     * read it here rather than from fields copied out of it one by one.
+     */
+    config: ResolvedConfig;
+    /** Construction-time allowlisted snapshot, frozen by describeConfig. */
+    configDescription: import("../describe-config.js").ConnectaConfigDescription;
+    configValueSources?: Readonly<Record<string, "default" | "config">>;
     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;
-    artifactOrigin?: string | undefined;
-    allowedOrigins?: readonly string[] | "*" | undefined;
-    serverInfo: Implementation;
-    logger: Logger;
-    activity?: ActivityStore | undefined;
-    activityReadGate?: ActivityReadGate | undefined;
-    activityDeploymentId?: string | undefined;
-    deploymentInfo?: Record<string, unknown> | undefined;
-    /** Deadline for call_tool/call_destructive_tool calls that pass no timeoutMs. Off when unset. */
-    defaultToolTimeoutMs?: number | undefined;
-    /** Per-connector deadline for the search/describe probe fan-out. Default 30_000. */
-    probeTimeoutMs?: number | undefined;
-    /** Maximum simultaneous connector discovery operations. Default 4. */
-    discoveryConcurrency?: number | undefined;
-    /** Aggregate serialized-byte budget for connecta.emit per run. Default 4_000_000. */
-    maxEmittedBytes?: number | undefined;
-    /** Block-count budget for connecta.emit per run. Default 32. */
-    maxEmittedBlocks?: number | undefined;
-    /** Host calls one execute_code program may make. Default 20. */
-    maxHostCalls?: number | undefined;
-    /** Deadline per execute_code host call. Default 15_000. */
-    hostCallTimeoutMs?: number | undefined;
-    /** Hard ceiling on one execute_code run, outside the sandbox. Default 120_000. */
-    watchdogMs?: number | undefined;
-    /** Config approval exemptions (`execute.approval`), resolved at construction. */
-    approval?: ApprovalPolicy | undefined;
-    /** Exempt writes one program may send (`execute.maxWrites`). */
-    maxWrites?: number | undefined;
-    /** Required sandbox backing the execute_code meta-tool. */
+    pools: ReadonlyMap<string, ResolvedPool>;
+    /** Required sandbox backing execute_code, wrapped in fallback admission if needed. */
     executor: Executor;
     /** Sanitized identity of the configured sandbox, when it has one. */
     executorName?: string | undefined;
     /** Global FIFO boundary for all non-preflight `/mcp` requests. */
     requestAdmission: AdmissionController;
-    /** Encrypted connector-credential storage backing the Credentials page. */
-    credentialVault?: CredentialVault | undefined;
-    /** Optional browser routes, with no implementation import in core. */
-    ui?: OperatorSurface | undefined;
-    activityModule?: ActivityModule | undefined;
-    /** Optional team pages; their routes mount only beside `ui`. */
-    artifactsModule?: ArtifactsModule | undefined;
-    accessTokens?: AccessTokensModule | undefined;
-    /** Optional browser UI and OAuth result-page labels. */
-    branding?: ConnectaBranding | undefined;
 }
 export interface RuntimeExecutionContext extends InboundAuthRuntimeContext {
     waitUntil(promise: Promise<unknown>): void;
@@ -86,10 +50,16 @@ export declare function privateJson(body: unknown, init?: ResponseInit): Respons
  */
 export declare function loggableValue(requested: string): string;
 export declare function activityActorNamespace(provider: InboundAuth): string | undefined;
-export declare function authorize(request: Request, baseUrl: string, auth: InboundAuth[], runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig, partitionIdentity?: boolean): Promise<{
+/** Metadata routing and challenge selection use the same first actual answer. */
+export declare function authMetadata(request: Request, baseUrl: string, auth: readonly InboundAuth[]): Promise<{
+    provider: InboundAuth;
+    response: Response;
+} | null>;
+export declare function authorize(request: Request, baseUrl: string, auth: readonly InboundAuth[], runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig, partitionIdentity?: boolean, interactiveOnly?: boolean): Promise<{
     ok: true;
     actor: ActivityActor;
     identity: AuthenticatedIdentity;
+    sessionCookies?: readonly string[];
     subjectKey?: string;
     principalKey?: string;
     connectorIds: "all" | readonly string[];
@@ -107,12 +77,8 @@ export declare function authorize(request: Request, baseUrl: string, auth: Inbou
     ok: false;
     response: Response;
 }>;
-export declare function authorizeUiIdentity(request: Request, baseUrl: string, auth: InboundAuth[], purpose: string, runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig): Promise<Extract<Awaited<ReturnType<typeof authorize>>, {
-    ok: true;
-}> | {
-    ok: false;
-    response: Response;
-}>;
+/** Human routes reject machine credentials before any verification or storage I/O. */
+export declare function authorizeUiIdentity(request: Request, baseUrl: string, auth: readonly InboundAuth[], purpose: string, runtimeContext?: RuntimeExecutionContext, identityConfig?: ConnectaIdentityConfig): Promise<Awaited<ReturnType<typeof authorize>>>;
 export declare function isSameOrigin(request: Request, baseUrl: string): boolean;
 export declare function withSecurityHeaders(response: Response, requestUrl: URL, _path: string): Response;
 type AuthorizedIdentity = Extract<Awaited<ReturnType<typeof authorize>>, {
@@ -120,14 +86,9 @@ type AuthorizedIdentity = Extract<Awaited<ReturnType<typeof authorize>>, {
 }>;
 /** Unknown configured ids refuse the complete view, including management rights. */
 export declare function validateAuthPermissions(authz: AuthorizedIdentity, registry: Registry): void;
-/**
- * Whether this identity may open artifact pages: exactly whoever may read the
- * `artifacts` connector — it is visible to them and `get_artifact` is among
- * its tools they were granted. Viewing grants nothing a program could not
- * already read (ethos, "Human routes manage auth, never capability").
- */
-export declare function mayViewArtifacts(authz: AuthorizedIdentity, registry: Registry): boolean;
 export declare function mayManageConnector(authz: AuthorizedIdentity, connector: {
     id: string;
     authScope?: "shared" | "personal";
 }): boolean;
+/** Preserve refreshed browser cookies on the redirect or completion page. */
+export declare function withSessionCookies(response: Response, cookies?: readonly string[]): Response;