@corenel/mcp 0.1.0

package/dist/oauth/discovery.d.ts

@@ -0,0 +1,55 @@
+export interface AuthMetadata {
+    authorizationEndpoint: string;
+    tokenEndpoint: string;
+    registrationEndpoint?: string;
+    scopesSupported?: string[];
+}
+/** Shape of a fetch Response this module actually uses -- narrow on purpose
+ *  so the injected fetch in tests can return a minimal stub. */
+type MinimalResponse = {
+    ok: boolean;
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    json(): Promise<unknown>;
+};
+type FetchLike = (url: string, init?: {
+    headers?: Record<string, string>;
+}) => Promise<MinimalResponse>;
+/**
+ * Discover the authorization server an MCP server trusts.
+ *
+ * Tries, in order:
+ *   1. GET `<origin>/.well-known/oauth-protected-resource` directly.
+ *   2. GET the MCP URL itself; if it 401s with a `WWW-Authenticate:
+ *      Bearer resource_metadata="<url>"` header, follow that URL instead --
+ *      this is the MORE RELIABLE path when present, since it is the server
+ *      naming its own document rather than us guessing the well-known path
+ *      relative to its origin.
+ *
+ * Returns `null` when NEITHER path yields a document. That is not an error:
+ * it means the server takes a static token (headers credential), which is a
+ * fully supported configuration -- see McpHeadersCredential in ../types.ts.
+ * Callers must not report a null return as a failure.
+ */
+export interface DiscoveredAuthServer {
+    authServer: string;
+    resource: string;
+    /** The RESOURCE's `scopes_supported` (RFC 9728 s2) -- authoritative for this
+     *  resource, and not the same list as the authorization server's own. */
+    scopes?: string[];
+}
+export declare function discoverAuthServer(mcpUrl: string, fetchImpl?: FetchLike): Promise<DiscoveredAuthServer | null>;
+/**
+ * Fetch and validate an authorization server's own metadata (RFC 8414).
+ *
+ * A document missing `authorization_endpoint` or `token_endpoint` is rejected
+ * outright, naming `authServer` in the error, rather than returned as a
+ * partial `AuthMetadata` -- an authorization server we cannot get a token
+ * from is useless, and failing here with a clear message beats failing later
+ * inside a token exchange with no context about which server was at fault.
+ */
+export declare function discoverAuthMetadata(authServer: string, fetchImpl?: FetchLike): Promise<AuthMetadata>;
+export {};
+//# sourceMappingURL=discovery.d.ts.map

package/dist/oauth/discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/oauth/discovery.ts"],"names":[],"mappings":"AAmBA,MAAM,WAAW,YAAY;IAC3B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;gEACgE;AAChE,KAAK,eAAe,GAAG;IACrB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;IAC9C,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1B,CAAC;AAEF,KAAK,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AA8ExG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB;6EACyE;IACzE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,SAAS,GAAE,SAAyC,GACnD,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA4CtC;AAiCD;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,SAAS,GAAE,SAAyC,GACnD,OAAO,CAAC,YAAY,CAAC,CAmCvB"}

package/dist/oauth/discovery.js

@@ -0,0 +1,211 @@
+/* FINDING AN MCP SERVER'S AUTHORIZATION SERVER, AND THAT SERVER'S ENDPOINTS.
+ *
+ * This is discovery ONLY -- it answers "who do I ask for a token, and where".
+ * It does not register a client, run PKCE, or exchange/refresh a token; those
+ * are later tasks that consume `AuthMetadata`'s `authorizationEndpoint` /
+ * `tokenEndpoint`. Keeping this module to just the two GETs means a later
+ * change to the login flow never has to touch the part that already works.
+ *
+ * `fetch` is injected (last parameter, default global fetch) so tests never
+ * open a socket -- see discovery.test.ts.
+ */
+/** RFC 9728 well-known path, resolved against the MCP server's own origin. */
+const PROTECTED_RESOURCE_PATH = '/.well-known/oauth-protected-resource';
+/** RFC 8414 well-known path, resolved against the authorization server's
+ *  issuer URL. */
+const AUTH_SERVER_METADATA_PATH = '/.well-known/oauth-authorization-server';
+/** GET `url` as JSON, or null on any failure (network error, non-2xx, not
+ *  JSON, not an object). Discovery documents are best-effort by design --
+ *  everywhere this is called, a missing document is a legitimate outcome
+ *  (see the design note on `discoverAuthServer`), not a bug to surface. */
+async function tryFetchJson(url, fetchImpl) {
+    let res;
+    try {
+        res = await fetchImpl(url);
+    }
+    catch {
+        return null;
+    }
+    if (!res.ok)
+        return null;
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch {
+        return null;
+    }
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        return null;
+    return body;
+}
+/** Pull the first `authorization_servers` entry out of a parsed protected-
+ *  resource document, or null if the document doesn't have one. */
+function firstAuthServer(doc) {
+    const list = doc.authorization_servers;
+    if (!Array.isArray(list) || list.length === 0)
+        return null;
+    const first = list[0];
+    return typeof first === 'string' && first.length > 0 ? first : null;
+}
+/** A discovery document's `scopes_supported`, or undefined unless it is a
+ *  non-empty list of strings.
+ *
+ *  Undefined rather than `[]` on purpose: callers distinguish "this resource
+ *  advertises no scopes" (monday, legitimately) from "it advertises these",
+ *  and an empty array would make the first look like the second and put an
+ *  empty `scope=` on the authorization URL. */
+function scopesFrom(doc) {
+    const list = doc.scopes_supported;
+    if (!Array.isArray(list) || list.length === 0)
+        return undefined;
+    return list.every((s) => typeof s === 'string') ? list : undefined;
+}
+/** Build the discovery result, carrying the resource's own scope list. */
+function resourceResult(doc, authServer, mcpUrl) {
+    const scopes = scopesFrom(doc);
+    return { authServer, resource: resourceFor(doc, mcpUrl), ...(scopes ? { scopes } : {}) };
+}
+/** Extract the `resource_metadata` URL from a `WWW-Authenticate: Bearer
+ *  resource_metadata="..."` header value, or null if the header is absent or
+ *  doesn't carry that parameter. RFC 9728 section 5.1. */
+function resourceMetadataUrlFromHeader(headerValue) {
+    if (!headerValue)
+        return null;
+    const match = /resource_metadata="([^"]+)"/.exec(headerValue);
+    return match ? match[1] : null;
+}
+/**
+ * The RFC 8707 resource indicator to bind a token to -- NEVER the address of
+ * the metadata document that was just fetched.
+ *
+ * A protected-resource document may name itself via its own `resource` field
+ * (RFC 9728 section 2, the canonical identifier for the resource server).
+ * When it does, that value wins. When it doesn't, `mcpUrl` -- the MCP server
+ * address `discoverAuthServer` was actually asked about -- is the only other
+ * value that identifies the resource server itself; the `.well-known`
+ * document URL identifies the METADATA, not the resource, and a token bound
+ * to it is a token the resource server has no reason to recognize as its
+ * own.
+ */
+function resourceFor(doc, mcpUrl) {
+    return typeof doc.resource === 'string' && doc.resource.length > 0 ? doc.resource : mcpUrl;
+}
+export async function discoverAuthServer(mcpUrl, fetchImpl = fetch) {
+    const origin = new URL(mcpUrl).origin;
+    const wellKnownUrl = new URL(PROTECTED_RESOURCE_PATH, origin).toString();
+    const direct = await tryFetchJson(wellKnownUrl, fetchImpl);
+    if (direct) {
+        const authServer = firstAuthServer(direct);
+        if (authServer)
+            return resourceResult(direct, authServer, mcpUrl);
+    }
+    // No document at the well-known path (or it didn't name an auth server) --
+    // fall back to asking the MCP endpoint itself and reading the 401 hint.
+    const viaHint = await hintedResource(mcpUrl, fetchImpl);
+    if (viaHint) {
+        const authServer = firstAuthServer(viaHint);
+        if (authServer)
+            return resourceResult(viaHint, authServer, mcpUrl);
+    }
+    /* LAST RESORT: the resource may BE its own authorization server.
+     *
+     * Nothing above found a protected-resource document, which used to end the
+     * search and report null -- and a null return means "static token only", so
+     * the user was told the service has no automatic sign-in. Measured
+     * 2026-09-14, that was false for two of our catalogue: Atlassian and
+     * Intercom publish no RFC 9728 document and hint at none on their 401, yet
+     * both serve RFC 8414 metadata at their own origin complete with a
+     * registration_endpoint.
+     *
+     * Tried ONLY here, after both RFC 9728 routes have failed, so a server that
+     * names its authorization server is always believed over this guess. That
+     * ordering is load-bearing: Trello's issuer is a per-tenant path on
+     * auth.atlassian.com, and that host ALSO answers the bare root well-known
+     * with a different issuer carrying no registration_endpoint. Letting this
+     * pre-empt a named authorization server would cost Trello its DCR.
+     *
+     * The origin is used as the issuer only when the document actually proves
+     * itself one, by carrying an authorization_endpoint. */
+    const own = await tryFetchJson(authServerMetadataUrl(origin), fetchImpl);
+    if (own && typeof own.authorization_endpoint === 'string' && own.authorization_endpoint.length > 0) {
+        const issuer = typeof own.issuer === 'string' && own.issuer.length > 0 ? own.issuer : origin;
+        return resourceResult(own, issuer, mcpUrl);
+    }
+    return null;
+}
+/** The protected-resource document an MCP endpoint points at from its own 401
+ *  (RFC 9728 s5.1), or null if it does not 401, does not carry the hint, or
+ *  the hinted document cannot be read. */
+async function hintedResource(mcpUrl, fetchImpl) {
+    let probe;
+    try {
+        probe = await fetchImpl(mcpUrl);
+    }
+    catch {
+        return null;
+    }
+    if (probe.status !== 401)
+        return null;
+    const hinted = resourceMetadataUrlFromHeader(probe.headers.get('www-authenticate'));
+    if (!hinted)
+        return null;
+    return tryFetchJson(hinted, fetchImpl);
+}
+/**
+ * The RFC 8414 metadata URL for an issuer, with the well-known segment inserted
+ * ahead of the issuer's path.
+ *
+ * `https://host`      -> `https://host/.well-known/oauth-authorization-server`
+ * `https://host/mcp`  -> `https://host/.well-known/oauth-authorization-server/mcp`
+ */
+function authServerMetadataUrl(authServer) {
+    const u = new URL(authServer);
+    // Trailing slashes are not part of the issuer's path for this purpose; a
+    // doubled slash in the result is a 404 on servers that route strictly.
+    const issuerPath = u.pathname.replace(/\/+$/, '');
+    return `${u.origin}${AUTH_SERVER_METADATA_PATH}${issuerPath}`;
+}
+/**
+ * Fetch and validate an authorization server's own metadata (RFC 8414).
+ *
+ * A document missing `authorization_endpoint` or `token_endpoint` is rejected
+ * outright, naming `authServer` in the error, rather than returned as a
+ * partial `AuthMetadata` -- an authorization server we cannot get a token
+ * from is useless, and failing here with a clear message beats failing later
+ * inside a token exchange with no context about which server was at fault.
+ */
+export async function discoverAuthMetadata(authServer, fetchImpl = fetch) {
+    /* RFC 8414 section 3.1: the well-known segment is INSERTED between the
+     * issuer's host and its path, not appended and not substituted. For issuer
+     * `https://auth.monday.com/mcp` the document is at
+     * `https://auth.monday.com/.well-known/oauth-authorization-server/mcp`.
+     *
+     * `new URL('/.well-known/...', issuer)` gets this wrong in the quiet way: a
+     * LEADING SLASH is root-relative, so the issuer's own `/mcp` is discarded and
+     * we ask the root for a document scoped to something else. monday serves both
+     * with identical endpoints, so it resolved by luck; a host serving per-tenant
+     * documents would have sent the user to another tenant's authorize endpoint.
+     *
+     * The root form is still tried second, because an issuer with no path
+     * produces the same URL either way and some servers only publish there. */
+    const doc = await tryFetchJson(authServerMetadataUrl(authServer), fetchImpl)
+        ?? await tryFetchJson(new URL(AUTH_SERVER_METADATA_PATH, authServer).toString(), fetchImpl);
+    if (!doc) {
+        throw new Error(`No OAuth authorization server metadata found at ${authServer}`);
+    }
+    const authorizationEndpoint = doc.authorization_endpoint;
+    const tokenEndpoint = doc.token_endpoint;
+    if (typeof authorizationEndpoint !== 'string' || authorizationEndpoint.length === 0) {
+        throw new Error(`Authorization server ${authServer} metadata is missing authorization_endpoint`);
+    }
+    if (typeof tokenEndpoint !== 'string' || tokenEndpoint.length === 0) {
+        throw new Error(`Authorization server ${authServer} metadata is missing token_endpoint`);
+    }
+    const registrationEndpoint = typeof doc.registration_endpoint === 'string' ? doc.registration_endpoint : undefined;
+    const scopesSupported = Array.isArray(doc.scopes_supported) && doc.scopes_supported.every((s) => typeof s === 'string')
+        ? doc.scopes_supported
+        : undefined;
+    return { authorizationEndpoint, tokenEndpoint, registrationEndpoint, scopesSupported };
+}
+//# sourceMappingURL=discovery.js.map

package/dist/oauth/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/oauth/discovery.ts"],"names":[],"mappings":"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"}

package/dist/oauth/login.d.ts

@@ -0,0 +1,41 @@
+import type { McpServer } from '../types';
+/** Why a sign-in did not happen, when it did not. */
+export type McpLoginOutcome = {
+    ok: true;
+}
+/** The server advertises no authorization server: it wants a static token. */
+ | {
+    ok: false;
+    reason: 'no-oauth';
+    message: string;
+    authServer?: undefined;
+}
+/** It advertises one, but that server will not register a client for us. */
+ | {
+    ok: false;
+    reason: 'no-dcr';
+    message: string;
+    authServer: string;
+}
+/** Something broke mid-flow. */
+ | {
+    ok: false;
+    reason: 'failed';
+    message: string;
+    authServer?: undefined;
+};
+export interface McpLoginDeps {
+    fetchImpl?: typeof fetch;
+    openBrowser?: (url: string) => void | Promise<void>;
+    now?: () => number;
+    /** The consent URL, as soon as it is built and before the browser opens.
+     *
+     *  Safe to show in full: it carries a client id, a redirect URI, a code
+     *  CHALLENGE (never the verifier) and a one-time state. Callers surface it so
+     *  a user whose browser did not open has something to click -- and so a user
+     *  driving a REMOTE daemon can see the address they must open on THAT
+     *  machine, since the redirect lands on its loopback and nowhere else. */
+    onAuthUrl?: (url: string) => void;
+}
+export declare function loginToMcpServer(stateDir: string, server: McpServer, deps?: McpLoginDeps): Promise<McpLoginOutcome>;
+//# sourceMappingURL=login.d.ts.map

package/dist/oauth/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/oauth/login.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAuB1C,qDAAqD;AACrD,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE;AACd,8EAA8E;GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,CAAA;CAAE;AAC5E,4EAA4E;GAC1E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE;AACtE,gCAAgC;GAC9B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,CAAA;CAAE,CAAC;AAE7E,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;;;8EAM0E;IAC1E,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,EACjB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,eAAe,CAAC,CAiN1B"}

package/dist/oauth/login.js

@@ -0,0 +1,206 @@
+import { writeMcpCredential, readMcpClient, writeMcpClient, clearMcpClient } from '../config.js';
+import { discoverAuthServer, discoverAuthMetadata } from './discovery.js';
+import { registerClient } from './register.js';
+import { makePkce, makeState, authorizationUrl } from './pkce.js';
+import { awaitRedirect, getFreePort, portFree } from './loopback.js';
+import { exchangeCode } from './tokens.js';
+/* IMPORTED LAZILY, AND THAT IS LOAD-BEARING. This module is reached from
+ * wirePort.ts, which the DAEMON constructs at startup -- so a module-scope
+ * `import ... from '@corenel/tools-node'` puts node:child_process into the
+ * daemon's startup graph, for a function only ever called once a human clicks
+ * Sign in.
+ *
+ * Measured, not assumed: adding it at module scope took p2c.e2e from 3/3 to
+ * 1/3 on this machine. The daemon is transpiled on the fly, so every module on
+ * the boot path costs real milliseconds, and a timing-sensitive e2e is the
+ * thing that notices first. */
+const defaultOpenBrowser = async (url) => {
+    const { openBrowser } = await import('@corenel/tools-node');
+    await openBrowser(url);
+};
+export async function loginToMcpServer(stateDir, server, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const openBrowserFn = deps.openBrowser ?? defaultOpenBrowser;
+    const now = deps.now ?? Date.now;
+    /* Tears the redirect listener down on every exit path that is NOT a
+     * completed redirect -- see the catch block below, and loopback.ts's
+     * `signal` doc. Aborting before `awaitRedirect` is ever called (nothing
+     * has listened yet) or after it has already settled (the listener is
+     * already closed) is a harmless no-op either way. */
+    const redirectAbort = new AbortController();
+    /* SIGN-IN ADDRESS, which is not always the call address. For a relayed
+     * server, `url` points at the Corenel relay -- a POST-only route whose
+     * upstream answers 405 to the GET that discovery probes with, so probing it
+     * concludes the server offers no OAuth at all. `authUrl` is the hosted
+     * service's own endpoint, whose gate leaves the OAuth paths public precisely
+     * so this can happen directly. Every other server has one address and this
+     * falls back to it. */
+    const signInUrl = server.authUrl ?? server.url;
+    try {
+        const discovered = await discoverAuthServer(signInUrl, fetchImpl);
+        if (!discovered) {
+            return {
+                ok: false,
+                reason: 'no-oauth',
+                message: `"${server.name}" does not advertise an OAuth authorization server. If it takes a static token instead, store that as a header.`,
+            };
+        }
+        const asMeta = await discoverAuthMetadata(discovered.authServer, fetchImpl);
+        /* THE RESOURCE'S SCOPE LIST WINS over the authorization server's.
+         *
+         * RFC 9728 s2: a protected-resource document's `scopes_supported` is the
+         * list for THAT resource. RFC 8414's is everything the authorization
+         * server offers across every resource it fronts. Reading only the latter
+         * was wrong in both directions at once -- Trello, Canva, PayPal and Asana
+         * advertise scopes only on the resource, so they were sent to consent with
+         * NO scope at all, while Dropbox's authorization server lists 39 and we
+         * asked for all of them.
+         *
+         * The empty-list case is already excluded upstream (`scopes` is undefined,
+         * never `[]`), so a resource that genuinely advertises none -- monday --
+         * still falls through to the authorization server's list and then to no
+         * `scope` parameter, which is what it had before. */
+        const meta = discovered.scopes
+            ? { ...asMeta, scopesSupported: discovered.scopes }
+            : asMeta;
+        /* The port must be known BEFORE the authorization URL is built:
+         * `redirect_uri` has to name the exact address the listener will bind, and
+         * the authorization server will refuse a mismatch. */
+        /* A PINNED port when the stored client carries one, an ephemeral port
+         * otherwise. RFC 8252 s7.3 obliges an authorization server to accept any
+         * port here, and most do -- Entra ignores it entirely, which is why one
+         * registered `http://localhost` covers every attempt. Slack matches
+         * redirect URLs exactly, so an operator who registered one URL needs the
+         * daemon to keep landing on that exact port. */
+        const cached = await readMcpClient(stateDir, server.name);
+        const port = cached?.redirectPort ?? await getFreePort();
+        /* A pinned port that something else already holds cannot be quietly swapped
+         * for a free one: the whole reason it is pinned is that a server matches the
+         * redirect URI exactly, so a different port fails the same way, one step
+         * later and less legibly. Say which port and why, rather than letting the
+         * listener reject with a bare EADDRINUSE from inside the flow. */
+        if (cached?.redirectPort !== undefined && !(await portFree(cached.redirectPort))) {
+            return {
+                ok: false,
+                reason: 'failed',
+                message: `the redirect port ${cached.redirectPort} is in use, and "${server.name}" is registered against exactly that port `
+                    + '-- free it and sign in again',
+            };
+        }
+        /* `localhost`, NOT `127.0.0.1`, and the difference is entirely about what
+         * authorization servers will let you register.
+         *
+         * Entra's portal REFUSES to add an `http://127.0.0.1` reply URL at all --
+         * it can only be added by hand-editing the application manifest's
+         * `replyUrlsWithType`. `http://localhost` it accepts directly, and it
+         * IGNORES THE PORT when matching, so a single registered
+         * `http://localhost` covers every ephemeral port this picks. Sending
+         * 127.0.0.1 meant every user had to do manifest surgery before a sign-in
+         * could work, and a mismatch there bounces the browser back to the account
+         * picker with nothing explaining why.
+         *
+         * The listener still binds loopback and nothing else -- see loopback.ts,
+         * which now answers on BOTH 127.0.0.1 and ::1 so it does not matter which
+         * one the browser resolves `localhost` to. */
+        const redirectUri = `http://localhost:${port}/callback`;
+        /* REUSE THE CLIENT WE ALREADY REGISTERED, if any.
+         *
+         * This used to mint a brand-new OAuth client on EVERY sign-in, so each
+         * click on Sign in created another client at the vendor. Servers rate-limit
+         * that -- Figma starts answering 403 after a few -- and the refusal arrives
+         * as a sign-in failure on a service that works perfectly, with nothing to
+         * suggest our own retrying caused it.
+         *
+         * Safe across the random loopback port picked per attempt: RFC 8252 s7.3
+         * requires an authorization server to accept ANY port for a loopback
+         * redirect URI. The stored `authServer` guards the one case where reuse
+         * would be wrong -- a server that later points somewhere else, where a
+         * cached client_id would be presented to something that never issued it. */
+        const registered = cached && cached.authServer === discovered.authServer
+            ? { clientId: cached.clientId, ...(cached.clientSecret ? { clientSecret: cached.clientSecret } : {}) }
+            : await registerClient(meta, redirectUri, fetchImpl);
+        if (registered && !cached) {
+            await writeMcpClient(stateDir, server.name, {
+                clientId: registered.clientId,
+                ...(registered.clientSecret ? { clientSecret: registered.clientSecret } : {}),
+                authServer: discovered.authServer,
+                /* PIN THE PORT WE JUST REGISTERED WITH.
+                 *
+                 * RFC 8252 s7.3 obliges an authorization server to accept any port on a
+                 * loopback redirect, and most do -- but not all, and the ones that do
+                 * not fail in the worst possible way. Atlassian's `auth.atlassian.com`
+                 * (Trello's authorization server, distinct from `mcp.atlassian.com`)
+                 * matches the redirect URI exactly. Registering with one ephemeral port
+                 * and then authorizing with a fresh one on the next sign-in produced
+                 * "The app's callback URL is invalid", from the vendor's own page,
+                 * BEFORE any token exchange -- so nothing came back for the
+                 * invalid_client recovery below to catch, and the flow simply timed out
+                 * waiting for a redirect that was never going to arrive.
+                 *
+                 * Persisting it costs nothing where the port is ignored, and is the
+                 * whole difference where it is not. The field already existed for
+                 * operator-set ports (`corenel mcp set-client --redirect-port`); it was
+                 * read here and never written by this path. */
+                redirectPort: port,
+            });
+        }
+        if (!registered) {
+            return {
+                ok: false,
+                reason: 'no-dcr',
+                authServer: discovered.authServer,
+                message: `"${server.name}"'s authorization server (${discovered.authServer}) supports OAuth but not dynamic client registration, so no client can be created on demand. Store a static token as a header instead -- a server in this position normally issues one from its own settings.`,
+            };
+        }
+        const pkce = makePkce();
+        const state = makeState();
+        const authUrl = authorizationUrl(meta, {
+            clientId: registered.clientId,
+            redirectUri,
+            codeChallenge: pkce.challenge,
+            state,
+            resource: discovered.resource,
+        });
+        deps.onAuthUrl?.(authUrl);
+        const redirectP = awaitRedirect(port, state, { signal: redirectAbort.signal });
+        /* A passive handler attached immediately: `openBrowserFn` below (a real
+         * browser, or a test's stand-in) can settle -- and reject -- this promise
+         * before the `await redirectP` subscribes to it, which Node otherwise
+         * flags as an unhandled rejection even though that later await consumes
+         * it. */
+        redirectP.catch(() => { });
+        await openBrowserFn(authUrl);
+        const { code } = await redirectP;
+        const cred = await exchangeCode(meta, {
+            clientId: registered.clientId,
+            ...(registered.clientSecret ? { clientSecret: registered.clientSecret } : {}),
+            code,
+            verifier: pkce.verifier,
+            redirectUri,
+            resource: discovered.resource,
+            authServer: discovered.authServer,
+        }, fetchImpl, now);
+        await writeMcpCredential(stateDir, server.name, cred);
+        return { ok: true };
+    }
+    catch (e) {
+        /* Whatever failed -- the browser never opened, the user closed the tab,
+         * the token exchange rejected -- the redirect listener must not be left
+         * bound. It is what a pinned `redirectPort` (persisted above) would find
+         * "in use" on the very next sign-in, mistaking our own leaked listener
+         * for a foreign process and refusing a retry that should just work. */
+        redirectAbort.abort();
+        const message = e instanceof Error ? e.message : String(e);
+        /* A REJECTED CLIENT is the one failure a stored registration can cause, and
+         * it would otherwise be permanent: the server has forgotten (or revoked)
+         * the client we keep presenting, so every future attempt reproduces this.
+         * Dropping it means the next sign-in registers afresh. Not retried inline --
+         * the browser consent has already happened by this point and cannot be
+         * replayed without the user. */
+        if (/invalid_client|unauthorized_client|client.{0,20}not.{0,10}found/i.test(message)) {
+            await clearMcpClient(stateDir, server.name).catch(() => { });
+        }
+        return { ok: false, reason: 'failed', message };
+    }
+}
+//# sourceMappingURL=login.js.map

package/dist/oauth/login.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.js","sourceRoot":"","sources":["../../src/oauth/login.ts"],"names":[],"mappings":"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"}

package/dist/oauth/loopback.d.ts

@@ -0,0 +1,58 @@
+export interface RedirectResult {
+    code: string;
+}
+export interface AwaitRedirectOptions {
+    timeoutMs?: number;
+    /** Test-only hook: called with the address/port the listener actually
+     *  bound, before any redirect arrives. `awaitRedirect`'s return value
+     *  never exposes this (a caller has no legitimate need to learn the bind
+     *  address after the fact), so a test that must assert "bound to
+     *  127.0.0.1, not 0.0.0.0" has no way to observe it otherwise. */
+    onListening?: (address: string, port: number) => void;
+    /** Lets a caller tear the listener down when IT gives up -- the browser
+     *  never opened, the user closed the tab, anything after `openBrowser`
+     *  threw. Without this the two servers below stay bound until their own
+     *  five-minute timeout, and the next sign-in on the same (now-pinned, see
+     *  login.ts) port finds ITS OWN orphaned listener sitting on it and
+     *  refuses, mistaking itself for a foreign process.
+     *
+     *  Aborting after the promise has already settled is a no-op -- `finish`
+     *  is idempotent -- so a caller can always abort on the way out without
+     *  checking whether the redirect already landed. */
+    signal?: AbortSignal;
+}
+/**
+ * Listen on 127.0.0.1:`port` for exactly one OAuth redirect, and resolve
+ * with its authorization code -- or reject. Either way the listener closes
+ * before the returned promise settles.
+ *
+ * `expectedState` must equal the redirect's `state` query parameter or the
+ * request is refused and the promise rejects, with the `code` parameter
+ * never read into a variable that could be exchanged. Without this check the
+ * listener would accept a code from anyone who can reach the port, which on
+ * a shared machine is everyone with a login shell.
+ */
+export declare function awaitRedirect(port: number, expectedState: string, opts?: AwaitRedirectOptions): Promise<RedirectResult>;
+/**
+ * A free ephemeral port on 127.0.0.1, for a caller to build a `redirect_uri`
+ * from before starting `awaitRedirect` on the same port -- the authorization
+ * URL needs the real port before the browser opens.
+ *
+ * There is an inherent, unavoidable race between this probe closing and the
+ * listener re-binding the same port: any "find a free port, then use it"
+ * strategy on a shared loopback interface has it. Acceptable here because
+ * this is a local, single-user, one-shot login flow, not a long-lived
+ * service placing a hard dependency on the exact port.
+ */
+/**
+ * Whether `port` can be bound on 127.0.0.1 right now.
+ *
+ * Only meaningful for a PINNED port -- one an operator registered with a
+ * service, or one a previous registration named. An ephemeral port comes from
+ * `getFreePort` and is free by construction. The same inherent race as
+ * `getFreePort` applies and is acceptable for the same reason: this answers
+ * "is something already sitting on it", not "reserve it for me".
+ */
+export declare function portFree(port: number): Promise<boolean>;
+export declare function getFreePort(): Promise<number>;
+//# sourceMappingURL=loopback.d.ts.map

package/dist/oauth/loopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../src/oauth/loopback.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;CACd;AAcD,MAAM,WAAW,oBAAoB;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;sEAIkE;IAClE,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtD;;;;;;;;;wDASoD;IACpD,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,MAAM,EACrB,IAAI,GAAE,oBAAyB,GAC9B,OAAO,CAAC,cAAc,CAAC,CA2FzB;AAED;;;;;;;;;;GAUG;AACH;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAQvD;AAED,wBAAgB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAS7C"}