@cjhyy/code-shell-server 0.9.44 → 0.9.47

package/dist/links/service.js

@@ -1,7 +1,9 @@
+import { linkConnectionMetadata } from "@cjhyy/code-shell-link";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { CredentialStore, beginRemoteLinkAuthorization, completeRemoteLinkAuthorization, revokeRemoteLinkAuthorization, isRemoteLinkCredential, connectCliLink, getCliLinkStatus, isCliLinkProvider, isCredentialSecretAvailable, summarizeOAuthCredentialSecret, validateLocalLinkToken, } from "@cjhyy/code-shell-core";
 import { listDesktopLinkProviders } from "./catalog.js";
-import { readRemoteProviderCapabilities, REMOTE_LINK_ADAPTERS, } from "./remote-catalog.js";
+import { authorizationDiagnosticFailure, authorizationDiagnosticIdentity, authorizationDiagnosticStage, withLinkAuthorizationTrace, } from "./diagnostics.js";
+import { readRemoteProviderCapabilities, RemoteLinkCatalogError, REMOTE_LINK_ADAPTERS, } from "./remote-catalog.js";
 import { LinkDeviceOAuthBroker, isLocalBrowserLinkProvider, } from "./device-oauth.js";
 const messages = {
     invalid_request: "Link 请求参数无效。",
@@ -27,6 +29,64 @@ export class LinkServiceError extends Error {
         this.name = "LinkServiceError";
     }
 }
+/** Trusted Host adapters use this to expose reviewed failure stages, never raw provider text. */
+export class HostLinkOAuthError extends LinkServiceError {
+    failure;
+    constructor(failure) {
+        super(422, "authorization_failed");
+        this.name = "HostLinkOAuthError";
+        if (![
+            "invalid_request",
+            "access_denied",
+            "timeout",
+            "network_error",
+            "server_error",
+            "protocol_error",
+        ].includes(failure.code) ||
+            ![
+                "validation",
+                "authorization",
+                "discovery_registration",
+                "authorization_callback",
+                "token_exchange",
+                "credential_verification",
+            ].includes(failure.stage) ||
+            (failure.verificationStage !== undefined &&
+                ![
+                    "credential_binding",
+                    "mcp_initialize",
+                    "tool_discovery",
+                    "account_verification",
+                    "capability_verification",
+                ].includes(failure.verificationStage)) ||
+            (failure.reason !== undefined &&
+                ![
+                    "binding_mismatch",
+                    "cancelled",
+                    "network_error",
+                    "http_error",
+                    "protocol_error",
+                    "tool_unavailable",
+                    "invalid_pagination",
+                    "response_too_large",
+                    "account_tool_error",
+                    "account_identity_unavailable",
+                    "no_read_capabilities",
+                ].includes(failure.reason)) ||
+            (failure.httpStatus !== undefined &&
+                (!Number.isInteger(failure.httpStatus) ||
+                    failure.httpStatus < 400 ||
+                    failure.httpStatus > 599)))
+            throw new LinkServiceError(400, "invalid_request");
+        this.failure = Object.freeze({
+            code: failure.code,
+            stage: failure.stage,
+            ...(failure.verificationStage ? { verificationStage: failure.verificationStage } : {}),
+            ...(failure.reason ? { reason: failure.reason } : {}),
+            ...(failure.httpStatus !== undefined ? { httpStatus: failure.httpStatus } : {}),
+        });
+    }
+}
 export function publicLinkError(error) {
     if (error instanceof LinkServiceError)
         return error;
@@ -51,8 +111,20 @@ export function createLinkService(options = {}) {
     const jobs = new Map();
     const remoteJobs = new Map();
     const interactiveJobs = new Map();
+    const hostOAuthJobs = new Map();
+    const hostOAuthAdapters = options.hostOAuthAdapters ?? [];
     let remoteCatalog;
-    let catalogPending;
+    const catalogPending = new Map();
+    const catalogCodes = new Map([
+        ["network", "catalog_network"],
+        ["timeout", "catalog_timeout"],
+        ["http_status", "catalog_http_status"],
+        ["invalid_json", "catalog_invalid_json"],
+        ["invalid_schema", "catalog_invalid_schema"],
+        ["unreviewed_capability", "catalog_unreviewed_capability"],
+        ["unsupported_auth", "catalog_unsupported_auth"],
+        ["response_limit", "catalog_response_limit"],
+    ]);
     const revokedOwners = new Set();
     let closed = false;
     let snapshotSignature = "";
@@ -105,16 +177,54 @@ export function createLinkService(options = {}) {
             throw new LinkServiceError(401, "login_required");
     }
     async function authorize(context) {
-        unavailable(context);
-        if (!(await context.authorize()))
+        try {
+            unavailable(context);
+            if (!(await context.authorize()))
+                throw new LinkServiceError(401, "login_required");
+            unavailable(context);
+        }
+        catch (error) {
+            authorizationDiagnosticFailure("authorization", "authorization_check_failed");
+            throw error;
+        }
+    }
+    function remoteAuthority(context) {
+        if (!options.captureRemoteAuthority)
+            return context;
+        let lease;
+        try {
+            lease = options.captureRemoteAuthority();
+            lease.signal.throwIfAborted();
+            lease.current();
+        }
+        catch {
+            authorizationDiagnosticFailure("authorization", "authorization_check_failed");
             throw new LinkServiceError(401, "login_required");
-        unavailable(context);
+        }
+        const signal = context.signal ? AbortSignal.any([context.signal, lease.signal]) : lease.signal;
+        const current = () => {
+            try {
+                signal.throwIfAborted();
+                lease.current();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        return {
+            ownerId: context.ownerId,
+            signal,
+            authorize: async () => current() && (await context.authorize()) && current(),
+        };
     }
     function begin(context) {
         unavailable(context);
         if (operations.size >= 8 ||
-            [...operations].filter((operation) => operation.ownerId === context.ownerId).length >= 2)
+            [...operations].filter((operation) => operation.ownerId === context.ownerId).length >= 2) {
+            authorizationDiagnosticFailure("job_creation", "job_capacity_exceeded");
             throw new LinkServiceError(409, "busy");
+        }
         const operation = { ownerId: context.ownerId, controller: new AbortController() };
         operations.add(operation);
         return operation;
@@ -132,31 +242,46 @@ export function createLinkService(options = {}) {
         return current.revision;
     }
     function records() {
-        const current = store.listWithStatus("full");
-        if (!current.readable)
-            throw new LinkServiceError(503, "unavailable");
-        return {
-            credentials: current.credentials,
-            projectIds: new Set(store.list("project").map((c) => c.id)),
-        };
+        authorizationDiagnosticStage("host_store_read");
+        try {
+            const current = store.listWithStatus("full");
+            if (!current.readable) {
+                authorizationDiagnosticFailure("host_store_read", "host_store_unreadable");
+                throw new LinkServiceError(503, "unavailable");
+            }
+            return {
+                credentials: current.credentials,
+                projectIds: new Set(store.list("project").map((c) => c.id)),
+            };
+        }
+        catch (error) {
+            if (!(error instanceof LinkServiceError))
+                authorizationDiagnosticFailure("host_store_read", "host_store_read_failed");
+            throw error;
+        }
     }
     function isLink(credential) {
         return (isRemoteLinkCredential(credential) ||
             (credential.type === "link" &&
-                credential.meta?.linkExecutionRuntime === "local" &&
+                linkConnectionMetadata(credential.meta).linkExecutionRuntime === "local" &&
+                providers.some((provider) => provider.id === credential.meta?.linkProvider)) ||
+            (credential.type === "oauth" &&
+                linkConnectionMetadata(credential.meta).linkExecutionBackend === "mcp" &&
+                linkConnectionMetadata(credential.meta).linkExecutionRuntime === "local" &&
                 providers.some((provider) => provider.id === credential.meta?.linkProvider)));
     }
     function masked(credential, scope) {
-        const meta = credential.meta;
-        const oauth = meta.linkAuthSource === "browser-oauth"
+        const meta = linkConnectionMetadata(credential.meta);
+        const oauth = meta.linkAuthSource === "browser-oauth" || meta.linkAuthSource === "mcp-oauth"
             ? summarizeOAuthCredentialSecret(credential.secret)
             : undefined;
         const remote = isRemoteLinkCredential(credential);
         const status = (remote && meta.linkRemoteState !== "connected") ||
-            (meta.linkAuthSource === "browser-oauth" &&
+            ((meta.linkAuthSource === "browser-oauth" || meta.linkAuthSource === "mcp-oauth") &&
                 meta.linkOAuthState &&
                 meta.linkOAuthState !== "connected") ||
-            (meta.linkAuthSource === "browser-oauth" && meta.linkCapabilityIds?.length === 0)
+            ((meta.linkAuthSource === "browser-oauth" || meta.linkAuthSource === "mcp-oauth") &&
+                meta.linkCapabilityIds?.length === 0)
             ? "unavailable"
             : !isCredentialSecretAvailable(credential.secret)
                 ? "unavailable"
@@ -175,10 +300,29 @@ export function createLinkService(options = {}) {
                 ? "remote-link"
                 : meta.linkExecutionBackend === "cli"
                     ? "cli-session"
-                    : meta.linkAuthSource === "browser-oauth"
-                        ? "browser-oauth"
-                        : "manual-token",
+                    : meta.linkAuthSource === "mcp-oauth"
+                        ? "mcp-oauth"
+                        : meta.linkAuthSource === "browser-oauth"
+                            ? "browser-oauth"
+                            : "manual-token",
             status,
+            recipeId: meta.linkRecipeId,
+            connectionState: {
+                authorization: {
+                    state: status === "connected"
+                        ? "authorized"
+                        : status === "expired" ||
+                            status === "invalid" ||
+                            meta.linkRemoteState === "reconnect" ||
+                            meta.linkOAuthState === "reconnect"
+                            ? "reauthorization_required"
+                            : "unknown",
+                },
+                // Compatibility is operation-specific. A saved grant or a successful
+                // account check cannot prove the contract required by a future task.
+                compatibility: { state: "unknown" },
+                observation: { state: "unchecked" },
+            },
             scope,
             editable: scope === "user",
             revision: revision(credential),
@@ -208,19 +352,38 @@ export function createLinkService(options = {}) {
         for (const id of revisions.keys())
             if (!ids.has(id))
                 revisions.delete(id);
-        const remoteConfig = options.remoteLink?.();
+        const remoteConfig = remoteConfiguration();
         const remoteProviders = remoteConfig
             ? remoteCatalog?.issuer === remoteConfig.issuer
                 ? remoteCatalog.providers
                 : []
             : [];
+        const catalogHealth = !remoteConfig
+            ? { state: "unconfigured" }
+            : remoteCatalog?.issuer === remoteConfig.issuer
+                ? { ...remoteCatalog.health }
+                : { state: "unknown" };
+        const remoteReady = catalogHealth.state === "ready";
         const result = {
             providers: providers.map((provider) => {
                 const deviceAuth = isLocalBrowserLinkProvider(provider.id)
                     ? createBroker().status(provider.id)
                     : undefined;
                 const authModes = [];
+                for (const adapter of hostOAuthAdapters.filter((entry) => entry.providerId === provider.id))
+                    authModes.push({
+                        id: adapter.authModeId,
+                        methodId: adapter.methodId,
+                        kind: "redirect",
+                        label: adapter.label,
+                        preferred: true,
+                        available: true,
+                    });
                 for (const method of provider.connectionMethods) {
+                    if (hostOAuthAdapters.some((adapter) => adapter.providerId === provider.id && adapter.methodId === method.id))
+                        continue;
+                    if (method.oauthProfileId && method.browserAuth?.flow === "authorization-code-pkce")
+                        continue;
                     if (method.executionRuntime !== "local" || method.availability !== "available")
                         continue;
                     if (method.browserAuth?.flow === "device-code")
@@ -253,7 +416,10 @@ export function createLinkService(options = {}) {
                     });
                 }
                 const remote = REMOTE_LINK_ADAPTERS.find((adapter) => adapter.id === provider.id &&
-                    remoteProviders.some((remote) => remote.id === adapter.id));
+                    (remoteProviders.some((remote) => remote.id === adapter.id) ||
+                        current.credentials.some((credential) => isRemoteLinkCredential(credential) &&
+                            credential.meta?.linkProvider === provider.id)));
+                const remoteAvailable = remoteReady && remoteProviders.some((candidate) => candidate.id === provider.id);
                 return {
                     ...provider,
                     connectionMethods: [
@@ -280,7 +446,16 @@ export function createLinkService(options = {}) {
                                     kind: "redirect",
                                     label: "网页授权",
                                     preferred: true,
-                                    available: true,
+                                    available: remoteAvailable,
+                                    ...(!remoteAvailable
+                                        ? {
+                                            unavailableReason: !remoteConfig
+                                                ? "当前未配置 Link 服务。已有账号仍可管理。"
+                                                : remoteReady
+                                                    ? "当前 Link 服务未提供此连接方式。已有账号仍可管理。"
+                                                    : "连接目录暂时不可用。已有账号仍可管理，请稍后重试。",
+                                        }
+                                        : {}),
                                 },
                             ]
                             : []),
@@ -296,10 +471,11 @@ export function createLinkService(options = {}) {
                 token: true,
                 cliBinding: true,
                 deviceAuth: true,
-                remoteAuth: remoteProviders.length > 0,
+                remoteAuth: remoteReady && remoteProviders.length > 0,
                 authorizationSteps: 1,
             },
             ...(remoteConfig ? { remoteServer: { issuer: remoteConfig.issuer } } : {}),
+            remoteCatalog: catalogHealth,
             remoteCleanupPending: store.remoteLinkRetirementCount(),
         };
         const signature = JSON.stringify(result);
@@ -309,14 +485,29 @@ export function createLinkService(options = {}) {
         }
         return { ...result, revision: snapshotRevision };
     }
-    async function refreshRemoteCatalog(context) {
+    function remoteConfiguration() {
+        authorizationDiagnosticStage("remote_configuration");
+        try {
+            return options.remoteLink?.();
+        }
+        catch (error) {
+            authorizationDiagnosticFailure("remote_configuration", "remote_configuration_invalid");
+            throw error;
+        }
+    }
+    async function refreshRemoteCatalogWithDiagnostic(context, force = false) {
         await authorize(context);
-        const config = options.remoteLink?.();
-        if (!config || (remoteCatalog?.issuer === config.issuer && remoteCatalog.expiresAt > now()))
+        const config = remoteConfiguration();
+        if (!config ||
+            (!force && remoteCatalog?.issuer === config.issuer && remoteCatalog.expiresAt > now()))
             return;
-        if (!catalogPending) {
-            catalogPending = (async () => {
-                let available;
+        authorizationDiagnosticStage("remote_catalog");
+        if (!catalogPending.has(config.issuer)) {
+            const pending = (async () => {
+                const previous = remoteCatalog?.issuer === config.issuer ? remoteCatalog : undefined;
+                let available = previous?.providers ?? [];
+                let health;
+                let diagnostic;
                 try {
                     available = options.readRemoteCatalog
                         ? (await options.readRemoteCatalog(config)).flatMap((id) => {
@@ -326,23 +517,54 @@ export function createLinkService(options = {}) {
                                 : [];
                         })
                         : await readRemoteProviderCapabilities(config);
+                    const checkedAt = new Date(now()).toISOString();
+                    health = { state: "ready", checkedAt, lastSuccessAt: checkedAt };
                 }
-                catch {
-                    // Preserve the reviewed v1 behavior during temporary service/network failures.
-                    available = remoteCatalog?.issuer === config.issuer ? remoteCatalog.providers : [];
+                catch (error) {
+                    diagnostic = {
+                        internalCode: error instanceof RemoteLinkCatalogError
+                            ? (catalogCodes.get(error.reason) ?? "catalog_unexpected_error")
+                            : "catalog_unexpected_error",
+                        ...(error instanceof RemoteLinkCatalogError
+                            ? { upstreamStatus: error.httpStatus }
+                            : {}),
+                    };
+                    // A failed discovery does not revoke saved accounts or erase the last good catalog.
+                    health = {
+                        state: previous?.health.lastSuccessAt ? "stale" : "unavailable",
+                        checkedAt: new Date(now()).toISOString(),
+                        ...(previous?.health.lastSuccessAt
+                            ? { lastSuccessAt: previous.health.lastSuccessAt }
+                            : {}),
+                        errorCode: error instanceof RemoteLinkCatalogError ? error.code : "network_error",
+                        ...(error instanceof RemoteLinkCatalogError && error.httpStatus !== undefined
+                            ? { httpStatus: error.httpStatus }
+                            : {}),
+                    };
                 }
                 if (!closed && options.remoteLink?.()?.issuer === config.issuer)
                     remoteCatalog = {
                         issuer: config.issuer,
-                        expiresAt: now() + 60_000,
+                        expiresAt: now() + (health.state === "ready" ? 60_000 : 15_000),
                         providers: available,
+                        health,
                     };
+                return diagnostic;
             })().finally(() => {
-                catalogPending = undefined;
+                if (catalogPending.get(config.issuer) === pending)
+                    catalogPending.delete(config.issuer);
             });
+            catalogPending.set(config.issuer, pending);
         }
-        await catalogPending;
+        // The shared request performs no trace writes. Every waiter owns its failure correlation.
+        const diagnostic = await catalogPending.get(config.issuer);
+        if (diagnostic)
+            authorizationDiagnosticFailure("remote_catalog", diagnostic.internalCode, diagnostic.upstreamStatus);
         await authorize(context);
+        return diagnostic;
+    }
+    async function refreshRemoteCatalog(context, force = false) {
+        await refreshRemoteCatalogWithDiagnostic(context, force);
     }
     function string(value, max = 200) {
         if (typeof value !== "string" ||
@@ -359,7 +581,9 @@ export function createLinkService(options = {}) {
         return id;
     }
     function reviewed(id, expectedRevision) {
+        authorizationDiagnosticStage("connection_review");
         const current = records();
+        authorizationDiagnosticStage("connection_review");
         const credential = current.credentials.find((entry) => entry.id === id);
         if (!credential || !isLink(credential))
             throw new LinkServiceError(409, "conflict");
@@ -369,7 +593,8 @@ export function createLinkService(options = {}) {
             throw new LinkServiceError(409, "conflict");
         return credential;
     }
-    function prepare(raw) {
+    function prepare(raw, hostAdapter) {
+        authorizationDiagnosticStage("input_validation");
         if (!raw || typeof raw !== "object")
             throw new LinkServiceError(400, "invalid_request");
         const input = {
@@ -384,11 +609,27 @@ export function createLinkService(options = {}) {
             ?.connectionMethods.find((candidate) => candidate.id === input.methodId);
         if (!method || method.executionRuntime !== "local" || method.availability !== "available")
             throw new LinkServiceError(400, "invalid_request");
-        const id = input.connectionId ?? `link-${input.providerId}-${input.methodId}`;
+        if (method.oauthProfileId &&
+            method.browserAuth?.flow === "authorization-code-pkce" &&
+            (!hostAdapter ||
+                hostAdapter.providerId !== input.providerId ||
+                hostAdapter.methodId !== input.methodId))
+            throw new LinkServiceError(400, "invalid_request");
+        const id = input.connectionId ?? `link-${randomUUID()}`;
+        authorizationDiagnosticStage("connection_review");
         let expected = null;
+        let knownConnectionIds;
         if (input.expectedRevision === null) {
-            if (records().credentials.some((credential) => credential.id === id))
+            const current = records();
+            authorizationDiagnosticStage("connection_review");
+            if (current.credentials.some((credential) => credential.id === id))
                 throw new LinkServiceError(409, "conflict");
+            if (!input.connectionId)
+                knownConnectionIds = current.credentials
+                    .filter((credential) => credential.meta?.linkProvider === input.providerId &&
+                    credential.meta?.linkConnectionMethod === input.methodId)
+                    .map((credential) => credential.id)
+                    .sort();
         }
         else {
             expected = reviewed(id, input.expectedRevision);
@@ -396,7 +637,7 @@ export function createLinkService(options = {}) {
                 expected.meta.linkConnectionMethod !== input.methodId)
                 throw new LinkServiceError(409, "conflict");
         }
-        return { input, id, expected };
+        return { input, id, expected, ...(knownConnectionIds ? { knownConnectionIds } : {}) };
     }
     async function change(context, write, bypassBusy = false) {
         const action = async () => {
@@ -413,6 +654,15 @@ export function createLinkService(options = {}) {
         const current = records();
         if (current.projectIds.has(prepared.id))
             throw new LinkServiceError(403, "read_only");
+        if (prepared.knownConnectionIds) {
+            const currentIds = current.credentials
+                .filter((credential) => credential.meta?.linkProvider === prepared.input.providerId &&
+                credential.meta?.linkConnectionMethod === prepared.input.methodId)
+                .map((credential) => credential.id)
+                .sort();
+            if (JSON.stringify(currentIds) !== JSON.stringify(prepared.knownConnectionIds))
+                throw new LinkServiceError(409, "conflict");
+        }
         if (!store.compareAndSwap("user", prepared.id, prepared.expected, next, retirement))
             throw new LinkServiceError(409, "conflict");
     }
@@ -426,9 +676,12 @@ export function createLinkService(options = {}) {
             meta: {
                 linkProvider: prepared.input.providerId,
                 linkConnectionMethod: prepared.input.methodId,
-                linkExecutionRuntime: "local",
-                linkAuthSource: authSource,
-                linkExecutionBackend: authSource === "cli-session" ? "cli" : "http-token",
+                recordSchemaVersion: 2,
+                linkRecipeId: authSource === "cli-session"
+                    ? "cli-session"
+                    : authSource === "browser-oauth"
+                        ? "api-oauth"
+                        : "api-token",
                 agentExposable: false,
                 linkAccountId: validation.identity.externalAccountId,
                 linkAccountLabel: validation.identity.label,
@@ -554,6 +807,7 @@ export function createLinkService(options = {}) {
                 installed: result.installed,
                 authenticated: result.authenticated,
                 ...(result.account ? { account: result.account } : {}),
+                ...(result.accountId ? { accountId: result.accountId } : {}),
             };
         }
         finally {
@@ -572,6 +826,14 @@ export function createLinkService(options = {}) {
     async function disconnect(context, id, expectedRevision) {
         await authorize(context);
         const credential = reviewed(safeId(id), expectedRevision);
+        if (linkConnectionMetadata(credential.meta).linkExecutionBackend === "mcp") {
+            const adapter = hostOAuthAdapters.find((entry) => entry.providerId === credential.meta?.linkProvider &&
+                entry.methodId === credential.meta?.linkConnectionMethod);
+            await change(context, () => swap({ id: credential.id, expected: credential, input: {} }, null), true);
+            // Local authority is already gone. Cleanup never deletes a new connection with this ID.
+            await adapter?.disconnect?.(credential).catch(() => { });
+            return;
+        }
         if (isRemoteLinkCredential(credential)) {
             // Disable local use before external I/O. Retain the disabled record if remote revocation
             // fails so the user can retry; never report successful remote revocation on a timeout.
@@ -669,19 +931,237 @@ export function createLinkService(options = {}) {
         }
         return cliStep(job, job.public.expiresAt, status.installed, validation);
     }
+    async function startHostOAuth(context, input, adapter) {
+        authorizationDiagnosticStage("job_creation");
+        for (const [id, job] of hostOAuthJobs)
+            if (job.retireAt !== undefined && job.retireAt <= now())
+                hostOAuthJobs.delete(id);
+        if (hostOAuthJobs.size >= 32) {
+            authorizationDiagnosticFailure("job_creation", "job_capacity_exceeded");
+            throw new LinkServiceError(409, "busy");
+        }
+        const prepared = prepare(input, adapter);
+        authorizationDiagnosticStage("job_creation");
+        const operation = begin(context);
+        const expiresAt = new Date(now() + 10 * 60_000).toISOString();
+        const job = {
+            context,
+            adapter,
+            prepared,
+            operation,
+            public: {
+                id: randomUUID(),
+                providerId: input.providerId,
+                methodId: input.methodId,
+                authModeId: adapter.authModeId,
+                state: "pending",
+                expiresAt,
+                step: { id: randomUUID(), kind: "processing", expiresAt },
+            },
+        };
+        hostOAuthJobs.set(job.public.id, job);
+        let ready;
+        const preparedStep = new Promise((resolve) => {
+            ready = resolve;
+        });
+        const end = (code) => {
+            if (job.public.state !== "pending")
+                return;
+            operation.controller.abort();
+            job.public = terminal(job.public, code === "cancelled" ? "cancelled" : "failed", {
+                errorCode: code,
+            });
+            job.retireAt = now() + 5 * 60_000;
+            clearTimeout(job.timer);
+            ready();
+        };
+        job.cancel = end;
+        const onAbort = () => end("cancelled");
+        context.signal?.addEventListener("abort", onAbort, { once: true });
+        job.timer = setTimeout(() => end("authorization_expired"), 10 * 60_000);
+        job.timer.unref?.();
+        if (context.signal?.aborted)
+            end("cancelled");
+        void (async () => {
+            let candidate;
+            let committed = false;
+            try {
+                operation.controller.signal.throwIfAborted();
+                candidate = await adapter.authorize({
+                    id: prepared.id,
+                    label: prepared.input.label,
+                    previous: prepared.expected,
+                    signal: operation.controller.signal,
+                    onAuthorizationUrl: async (url, expiry) => {
+                        await authorize(context);
+                        operation.controller.signal.throwIfAborted();
+                        const target = new URL(url);
+                        const time = Date.parse(expiry);
+                        if (target.protocol !== "https:" ||
+                            target.username ||
+                            target.password ||
+                            target.hash ||
+                            !Number.isFinite(time) ||
+                            time <= now() ||
+                            time > now() + 10 * 60_000 + 1_000)
+                            throw new LinkServiceError(422, "authorization_failed");
+                        if (job.public.state !== "pending")
+                            throw new LinkServiceError(409, "cancelled");
+                        job.public.expiresAt = expiry;
+                        clearTimeout(job.timer);
+                        job.timer = setTimeout(() => end("authorization_expired"), Math.max(1, time - now()));
+                        job.timer.unref?.();
+                        job.public.step = {
+                            id: randomUUID(),
+                            kind: "redirect",
+                            expiresAt: expiry,
+                            authorizationUrl: target.href,
+                        };
+                        ready();
+                    },
+                });
+                await authorize(context);
+                operation.controller.signal.throwIfAborted();
+                if (job.public.state !== "pending" ||
+                    candidate.id !== prepared.id ||
+                    candidate.type !== "oauth" ||
+                    candidate.meta?.linkProvider !== input.providerId ||
+                    candidate.meta.linkConnectionMethod !== input.methodId ||
+                    linkConnectionMetadata(candidate.meta).linkExecutionBackend !== "mcp" ||
+                    candidate.meta.agentExposable !== false)
+                    throw new LinkServiceError(422, "provider_rejected");
+                // Host adapters may still return legacy routing fields. The installed
+                // connection keeps only its reviewed recipe; presentation derives axes.
+                const { linkExecutionRuntime: _runtime, linkExecutionBackend: _backend, linkAuthSource: _source, ...candidateMeta } = candidate.meta;
+                candidate = {
+                    ...candidate,
+                    meta: { ...candidateMeta, recordSchemaVersion: 2, linkRecipeId: "mcp-oauth" },
+                };
+                await change(context, () => {
+                    operation.controller.signal.throwIfAborted();
+                    if (job.public.state !== "pending")
+                        throw new LinkServiceError(409, "cancelled");
+                    swap(prepared, candidate);
+                    committed = true;
+                    job.public = terminal(job.public, "connected", {
+                        connection: masked(candidate, "user"),
+                    });
+                });
+            }
+            catch (error) {
+                if (job.public.state === "pending") {
+                    end(operation.controller.signal.aborted
+                        ? "cancelled"
+                        : error instanceof LinkServiceError
+                            ? error.code
+                            : "authorization_failed");
+                    if (job.public.state === "failed" &&
+                        error instanceof HostLinkOAuthError)
+                        job.public = { ...job.public, failure: { ...error.failure } };
+                }
+            }
+            finally {
+                if (candidate?.secret && !committed) {
+                    try {
+                        const saved = store.resolve(candidate.id, "full");
+                        if (candidate.secret !== prepared.expected?.secret &&
+                            candidate.secret !== saved?.secret)
+                            await adapter.disconnect?.(candidate);
+                    }
+                    catch {
+                        /* Detached cleanup cannot change the original authorization result. */
+                    }
+                }
+                clearTimeout(job.timer);
+                context.signal?.removeEventListener("abort", onAbort);
+                job.retireAt = now() + 5 * 60_000;
+                finish(operation);
+                ready();
+            }
+        })();
+        await preparedStep;
+        return structuredClone(job.public);
+    }
+    async function openHostAuthorization(context, id) {
+        await authorize(context);
+        const job = hostOAuthJobs.get(safeId(id));
+        if (!job)
+            return false;
+        if (job.context.ownerId !== context.ownerId ||
+            job.public.state !== "pending" ||
+            job.operation.controller.signal.aborted ||
+            job.public.step?.kind !== "redirect" ||
+            Date.parse(job.public.step.expiresAt) <= now())
+            throw new LinkServiceError(409, "conflict");
+        const target = new URL(job.public.step.authorizationUrl);
+        if (target.protocol !== "https:" || target.username || target.password || target.hash)
+            throw new LinkServiceError(400, "invalid_request");
+        await job.adapter.openAuthorizationUrl(target.href);
+        await authorize(context);
+        return true;
+    }
+    function diagnosticIdentity(input, authModeId) {
+        const provider = providers.find((candidate) => candidate.id === input?.providerId);
+        if (!provider)
+            return;
+        const remote = REMOTE_LINK_ADAPTERS.find((adapter) => adapter.id === provider.id && adapter.methodId === input.methodId);
+        const method = provider.connectionMethods.find((candidate) => candidate.id === input.methodId);
+        const modes = remote
+            ? [remote.authModeId]
+            : method
+                ? [
+                    "token",
+                    ...(method.quickAuth ? ["cli-session"] : []),
+                    ...(method.browserAuth?.flow === "device-code" ? ["browser-oauth"] : []),
+                    ...(method.oauthProfileId ? ["mcp-oauth"] : []),
+                ]
+                : [];
+        authorizationDiagnosticIdentity({
+            providerId: provider.id,
+            ...(remote || method ? { methodId: remote?.methodId ?? method.id } : {}),
+            ...(modes.includes(authModeId) ? { authModeId: authModeId } : {}),
+        });
+    }
     async function startAuthorization(context, input, rawAuthModeId) {
+        return withLinkAuthorizationTrace(options.onAuthorizationDiagnostic, () => startAuthorizationWithinTrace(context, input, rawAuthModeId), publicLinkError);
+    }
+    async function startAuthorizationWithinTrace(context, input, rawAuthModeId) {
         await authorize(context);
+        diagnosticIdentity(input, rawAuthModeId);
+        authorizationDiagnosticStage("input_validation");
         const authModeId = string(rawAuthModeId, 80);
-        if (input?.resourceUrl !== undefined && authModeId !== "remote-link")
+        const hostAdapter = hostOAuthAdapters.find((adapter) => adapter.providerId === input?.providerId &&
+            adapter.methodId === input.methodId &&
+            adapter.authModeId === authModeId);
+        if (input?.resourceUrl !== undefined && authModeId !== "remote-link" && !hostAdapter)
             throw new LinkServiceError(400, "invalid_request");
-        if (authModeId === "remote-link")
-            await refreshRemoteCatalog(context);
+        if (authModeId === "remote-link") {
+            context = remoteAuthority(context);
+            const diagnostic = await refreshRemoteCatalogWithDiagnostic(context, true);
+            const state = snapshot().remoteCatalog?.state;
+            if (state !== "ready") {
+                if (state === "unconfigured")
+                    authorizationDiagnosticFailure("remote_configuration", "remote_configuration_missing");
+                else
+                    authorizationDiagnosticFailure("remote_catalog", diagnostic?.internalCode ?? "catalog_unavailable", diagnostic?.upstreamStatus);
+                throw new LinkServiceError(503, "unavailable");
+            }
+        }
         const provider = snapshot().providers.find((candidate) => candidate.id === input?.providerId);
+        authorizationDiagnosticStage("mode_selection");
         const mode = provider?.authModes?.find((candidate) => candidate.id === authModeId && candidate.methodId === input.methodId && candidate.available);
-        if (!mode)
+        if (!mode) {
+            authorizationDiagnosticFailure("mode_selection", authModeId === "remote-link" &&
+                REMOTE_LINK_ADAPTERS.some((adapter) => adapter.id === input?.providerId) &&
+                !remoteCatalog?.providers.some((candidate) => candidate.id === input.providerId)
+                ? "provider_capability_missing"
+                : "auth_mode_unavailable");
             throw new LinkServiceError(400, "invalid_request");
+        }
+        if (hostAdapter)
+            return startHostOAuth(context, input, hostAdapter);
         if (mode.kind === "redirect") {
-            const result = await startRemoteAuth(context, input);
+            const result = await startRemoteAuthAfterCatalog(context, input);
             const job = remoteJobs.get(result.id);
             job.public.methodId = input.methodId;
             job.public.authModeId = authModeId;
@@ -691,10 +1171,14 @@ export function createLinkService(options = {}) {
         }
         if (mode.kind === "device-code")
             return startDeviceAuth(context, input);
+        authorizationDiagnosticStage("job_creation");
         pruneInteractive();
-        if (interactiveJobs.size >= 32)
+        if (interactiveJobs.size >= 32) {
+            authorizationDiagnosticFailure("job_creation", "job_capacity_exceeded");
             throw new LinkServiceError(409, "busy");
+        }
         const prepared = prepare(input);
+        authorizationDiagnosticStage("job_creation");
         const operation = begin(context);
         const expiresAt = now() + 10 * 60_000;
         const base = { id: randomUUID(), expiresAt: new Date(expiresAt).toISOString() };
@@ -954,14 +1438,18 @@ export function createLinkService(options = {}) {
         }
     }
     async function startDeviceAuth(context, input) {
+        authorizationDiagnosticStage("job_creation");
         pruneJobs();
-        if (jobs.size >= 32)
+        if (jobs.size >= 32) {
+            authorizationDiagnosticFailure("job_creation", "job_capacity_exceeded");
             throw new LinkServiceError(409, "busy");
+        }
         const operation = begin(context);
         let job;
         try {
             await authorize(context);
             const prepared = prepare(input);
+            authorizationDiagnosticStage("job_creation");
             const providerId = prepared.input.providerId;
             if (!isLocalBrowserLinkProvider(providerId))
                 throw new LinkServiceError(400, "invalid_request");
@@ -1029,14 +1517,23 @@ export function createLinkService(options = {}) {
         }
     }
     async function startRemoteAuth(context, input) {
+        context = remoteAuthority(context);
+        await refreshRemoteCatalog(context, true);
+        return startRemoteAuthAfterCatalog(context, input);
+    }
+    async function startRemoteAuthAfterCatalog(context, input) {
         await authorize(context);
+        authorizationDiagnosticStage("job_creation");
         const checkCapacity = () => {
             pruneRemoteJobs();
             if (remoteJobs.size >= 32 ||
-                [...remoteJobs.values()].filter((job) => job.context.ownerId === context.ownerId && job.public.state === "pending").length >= 2)
+                [...remoteJobs.values()].filter((job) => job.context.ownerId === context.ownerId && job.public.state === "pending").length >= 2) {
+                authorizationDiagnosticFailure("job_creation", "job_capacity_exceeded");
                 throw new LinkServiceError(409, "busy");
+            }
         };
         checkCapacity();
+        authorizationDiagnosticStage("input_validation");
         if (!input ||
             input.methodId !== "remote-link" ||
             !REMOTE_LINK_ADAPTERS.some((adapter) => adapter.id === input.providerId) ||
@@ -1045,22 +1542,27 @@ export function createLinkService(options = {}) {
                     typeof input.resourceUrl !== "string" ||
                     !input.resourceUrl)))
             throw new LinkServiceError(400, "invalid_request");
-        const config = options.remoteLink?.();
-        if (!config)
+        const config = remoteConfiguration();
+        if (!config) {
+            authorizationDiagnosticFailure("remote_configuration", "remote_configuration_missing");
             throw new LinkServiceError(503, "unavailable");
-        await refreshRemoteCatalog(context);
-        // Discovery awaits must not bypass owner revocation or the pending-job limit.
-        await authorize(context);
-        checkCapacity();
-        const capabilities = remoteCatalog?.issuer === config.issuer
+        }
+        // No await between selecting the deployment and creating its authorization URL.
+        authorizationDiagnosticStage("remote_catalog");
+        const capabilities = remoteCatalog?.issuer === config.issuer && remoteCatalog.health.state === "ready"
             ? remoteCatalog.providers.find((provider) => provider.id === input.providerId)
             : undefined;
-        if (!capabilities)
+        if (!capabilities) {
+            authorizationDiagnosticFailure("remote_catalog", "provider_capability_missing");
             throw new LinkServiceError(503, "unavailable");
+        }
+        authorizationDiagnosticStage("connection_review");
         const id = input.connectionId === undefined ? `link-remote-${randomUUID()}` : safeId(input.connectionId);
         let expected = null;
         if (input.expectedRevision === null) {
-            if (records().credentials.some((credential) => credential.id === id))
+            const current = records();
+            authorizationDiagnosticStage("connection_review");
+            if (current.credentials.some((credential) => credential.id === id))
                 throw new LinkServiceError(409, "conflict");
         }
         else {
@@ -1069,6 +1571,7 @@ export function createLinkService(options = {}) {
                 throw new LinkServiceError(409, "conflict");
         }
         const prepared = { id, expected, input: { ...input, label: string(input.label) } };
+        authorizationDiagnosticStage("job_creation");
         let attempt;
         try {
             let resourceFiles;
@@ -1089,6 +1592,7 @@ export function createLinkService(options = {}) {
             });
         }
         catch {
+            authorizationDiagnosticFailure("job_creation", "remote_authorization_invalid");
             throw new LinkServiceError(400, "invalid_request");
         }
         const publicJob = {
@@ -1246,6 +1750,12 @@ export function createLinkService(options = {}) {
         pruneJobs();
         pruneRemoteJobs();
         pruneInteractive();
+        const host = hostOAuthJobs.get(safeId(id));
+        if (host) {
+            if (host.context.ownerId !== context.ownerId)
+                throw new LinkServiceError(404, "not_found");
+            return structuredClone(host.public);
+        }
         const interactive = interactiveJobs.get(safeId(id));
         if (interactive) {
             if (interactive.context.ownerId !== context.ownerId)
@@ -1258,6 +1768,8 @@ export function createLinkService(options = {}) {
         if (remote) {
             if (remote.context.ownerId !== context.ownerId)
                 throw new LinkServiceError(404, "not_found");
+            if (options.captureRemoteAuthority && remote.public.state === "pending")
+                await authorize(remote.context);
             return structuredClone(remote.public);
         }
         const job = jobs.get(safeId(id));
@@ -1268,11 +1780,16 @@ export function createLinkService(options = {}) {
     async function cancelAuthorization(context, id) {
         await authorize(context);
         safeId(id);
-        const ownerId = remoteJobs.get(id)?.context.ownerId ??
+        const ownerId = hostOAuthJobs.get(id)?.context.ownerId ??
+            remoteJobs.get(id)?.context.ownerId ??
             interactiveJobs.get(id)?.context.ownerId ??
             jobs.get(id)?.ownerId;
         if (!ownerId || ownerId !== context.ownerId)
             throw new LinkServiceError(404, "not_found");
+        const host = hostOAuthJobs.get(id);
+        if (host?.public.state === "pending") {
+            host.cancel?.("cancelled");
+        }
         const remote = remoteJobs.get(id);
         if (remote?.public.state === "pending") {
             remote.public = terminal(remote.public, "cancelled", { errorCode: "cancelled" });
@@ -1288,6 +1805,13 @@ export function createLinkService(options = {}) {
     }
     function cancelOwner(ownerId) {
         revokedOwners.add(ownerId);
+        for (const [id, job] of hostOAuthJobs)
+            if (job.context.ownerId === ownerId) {
+                job.cancel?.("cancelled");
+                job.operation.controller.abort();
+                clearTimeout(job.timer);
+                hostOAuthJobs.delete(id);
+            }
         for (const [id, job] of interactiveJobs)
             if (job.context.ownerId === ownerId) {
                 endInteractive(job, "cancelled");
@@ -1312,6 +1836,12 @@ export function createLinkService(options = {}) {
         clearInterval(cleanupTimer);
         clearTimeout(cleanupStartup);
         remoteJobs.clear();
+        for (const job of hostOAuthJobs.values()) {
+            job.cancel?.("cancelled");
+            job.operation.controller.abort();
+            clearTimeout(job.timer);
+        }
+        hostOAuthJobs.clear();
         for (const job of interactiveJobs.values())
             endInteractive(job, "cancelled");
         interactiveJobs.clear();
@@ -1333,6 +1863,7 @@ export function createLinkService(options = {}) {
         disconnect,
         startDeviceAuth,
         startAuthorization,
+        openHostAuthorization,
         respondAuthorization,
         refreshRemoteCatalog,
         startRemoteAuth,