@ory/argus 0.13.9 → 1.0.0

package/dist/auth-store.d.ts

@@ -18,6 +18,41 @@ export declare function loadTokens(): OryOAuth2Tokens | undefined;
 export declare function saveTokens(tokens: OryOAuth2Tokens): void;
 /** Remove the user's persisted OAuth2 tokens. */
 export declare function clearTokens(): void;
+/**
+ * A user credential supplied out-of-band through the environment (CI, scripted
+ * runs, a harness launched by a wrapper that already authenticated).
+ */
+export interface EnvUserCredential {
+    /** The bearer, if any of the four accepted variables is set. */
+    token?: string;
+    /** `ORY_USER_SUBJECT_ID`, when the operator pinned the subject. */
+    subject?: string;
+}
+/**
+ * Read the pre-supplied user credential from the environment.
+ *
+ * **`ORY_USER_OAUTH2_TOKEN` is the only accepted variable**, because an OAuth2
+ * access token is the only thing the credential is ever used as. All three
+ * consumers of `userPrincipal.token` demand one: broker delegation
+ * authentication and the agent + sub-agent DCR bootstraps (which send it as a
+ * bearer to `/oauth2/register`). Nothing calls `verifySession`, so a Kratos
+ * session token is never consumed as a session token.
+ *
+ * Three variables used to be accepted alongside it and have been removed:
+ * `ORY_USER_SESSION_TOKEN` (plus its legacy alias `ORY_SESSION_TOKEN`) named a
+ * Kratos session token and took *first* precedence, so supplying the credential
+ * its name asked for made every permission check fail `session_inactive` — and
+ * beat the variable that would have worked. `ORY_OAUTH2_TOKEN` was a redundant
+ * legacy alias. Pin the subject with `ORY_USER_SUBJECT_ID`.
+ *
+ * This lives here, and only here, because two call sites depend on agreeing:
+ * the login gate's `env_token` short-circuit (which runs on `SessionStart`) and
+ * the per-client rehydration in `OryAgentClient.fromEnv` (which runs on *every*
+ * lifecycle event, including the subprocess tool-call events where the gate
+ * never runs). If those disagreed, an env-supplied token would authenticate the
+ * session and then silently stop authenticating the permission checks.
+ */
+export declare function readEnvUserCredential(env?: NodeJS.ProcessEnv): EnvUserCredential;
 /** Number of seconds before nominal expiry that we consider tokens stale. */
 export declare const TOKEN_EXPIRY_SKEW_SEC = 60;
 /** Returns true if the access token is missing or within the skew window of expiry. */
@@ -55,8 +90,8 @@ export interface PkceFlightLock {
 export declare function tryAcquirePkceFlightLock(): PkceFlightLock | null;
 /**
  * Unconditionally remove the pkce-flight lock, if any. Use this from
- * single-owner contexts (e.g. the dev launcher at startup) where you
- * know no peer is mid-flow. Returns true when a lock was removed.
+ * single-owner maintenance contexts where no peer is mid-flow. Returns true
+ * when a lock was removed.
  */
 export declare function clearPkceFlightLock(): boolean;
 /**

package/dist/auth-store.js

@@ -50,6 +50,7 @@ exports.TOKEN_EXPIRY_SKEW_SEC = void 0;
 exports.loadTokens = loadTokens;
 exports.saveTokens = saveTokens;
 exports.clearTokens = clearTokens;
+exports.readEnvUserCredential = readEnvUserCredential;
 exports.isExpired = isExpired;
 exports.refreshAndSave = refreshAndSave;
 exports.tryAcquirePkceFlightLock = tryAcquirePkceFlightLock;
@@ -73,9 +74,10 @@ function loadTokens() {
 }
 /** Persist the user's OAuth2 tokens. Existing tokens are replaced atomically. */
 function saveTokens(tokens) {
+    const { idToken: _discardedIdToken, ...persistedTokens } = tokens;
     (0, config_js_1.mutateConfig)((current) => ({
         ...current,
-        user: { ...(current.user ?? {}), oauth2: tokens },
+        user: { ...(current.user ?? {}), oauth2: persistedTokens },
     }));
 }
 /** Remove the user's persisted OAuth2 tokens. */
@@ -93,6 +95,38 @@ function clearTokens() {
         return next;
     });
 }
+/**
+ * Read the pre-supplied user credential from the environment.
+ *
+ * **`ORY_USER_OAUTH2_TOKEN` is the only accepted variable**, because an OAuth2
+ * access token is the only thing the credential is ever used as. All three
+ * consumers of `userPrincipal.token` demand one: broker delegation
+ * authentication and the agent + sub-agent DCR bootstraps (which send it as a
+ * bearer to `/oauth2/register`). Nothing calls `verifySession`, so a Kratos
+ * session token is never consumed as a session token.
+ *
+ * Three variables used to be accepted alongside it and have been removed:
+ * `ORY_USER_SESSION_TOKEN` (plus its legacy alias `ORY_SESSION_TOKEN`) named a
+ * Kratos session token and took *first* precedence, so supplying the credential
+ * its name asked for made every permission check fail `session_inactive` — and
+ * beat the variable that would have worked. `ORY_OAUTH2_TOKEN` was a redundant
+ * legacy alias. Pin the subject with `ORY_USER_SUBJECT_ID`.
+ *
+ * This lives here, and only here, because two call sites depend on agreeing:
+ * the login gate's `env_token` short-circuit (which runs on `SessionStart`) and
+ * the per-client rehydration in `OryAgentClient.fromEnv` (which runs on *every*
+ * lifecycle event, including the subprocess tool-call events where the gate
+ * never runs). If those disagreed, an env-supplied token would authenticate the
+ * session and then silently stop authenticating the permission checks.
+ */
+function readEnvUserCredential(env = process.env) {
+    const token = env.ORY_USER_OAUTH2_TOKEN || undefined;
+    const subject = env.ORY_USER_SUBJECT_ID || undefined;
+    return {
+        ...(token ? { token } : {}),
+        ...(subject ? { subject } : {}),
+    };
+}
 /** Number of seconds before nominal expiry that we consider tokens stale. */
 exports.TOKEN_EXPIRY_SKEW_SEC = 60;
 /** Returns true if the access token is missing or within the skew window of expiry. */
@@ -203,8 +237,8 @@ function isLockStale(file) {
 }
 /**
  * Unconditionally remove the pkce-flight lock, if any. Use this from
- * single-owner contexts (e.g. the dev launcher at startup) where you
- * know no peer is mid-flow. Returns true when a lock was removed.
+ * single-owner maintenance contexts where no peer is mid-flow. Returns true
+ * when a lock was removed.
  */
 function clearPkceFlightLock() {
     try {

package/dist/auth.d.ts

@@ -14,14 +14,31 @@
 import { OryOAuth2Tokens } from "./config.js";
 /** Loopback ports tried in order. All must be registered as redirect URIs on the Ory OAuth2 client. */
 export declare const LOOPBACK_PORTS: readonly [47823, 47824, 47825, 47826];
-/** Hard timeout if the user never returns to the browser. */
-export declare const DEFAULT_LOGIN_TIMEOUT_MS = 120000;
+/**
+ * Hard timeout if the user never returns to the browser.
+ *
+ * Sized to fit **inside** the tightest session-start hook window any harness
+ * will accept, so the login always gives up on its own terms and records a
+ * `timeout` decline the user can act on. Being SIGKILLed by the harness
+ * instead surfaces nothing at all: the session proceeds with no user identity,
+ * and under `enforce` every subsequent tool is denied for a reason nothing
+ * explains (#220).
+ *
+ * The binding constraint is Antigravity, which validates its hook timeout to
+ * `5..120` seconds — so 120s is the ceiling, and this leaves headroom for the
+ * agent DCR registration and delegation record that run after the login inside
+ * the same hook invocation. See `hook-timeout.ts`, which derives every
+ * harness's declared window and asserts it outlasts this value.
+ */
+export declare const DEFAULT_LOGIN_TIMEOUT_MS = 90000;
 export interface PkceLoginOptions {
     /** Ory project URL (e.g. https://your-project.projects.oryapis.com). */
     projectUrl: string;
     /** Public OAuth2 client id registered with the loopback redirect URIs. */
     clientId: string;
-    /** Scopes to request. Defaults to `openid offline_access`. */
+    /** Scopes to request. Defaults to `openid offline_access profile email`
+     *  — `profile` / `email` populate the id_token's name/username/email
+     *  claims so the signed-in user can be shown by name, not just subject id. */
     scope?: string;
     /** Audience to request, if any. */
     audience?: string;
@@ -42,8 +59,20 @@ export type PkceLoginOutcome = {
 } | {
     kind: "declined";
     reason: PkceDeclineReason;
+    /**
+     * Concise, secret-free diagnostic for the failure, surfaced in the
+     * `user.auth` audit event and the operator message. Populated for
+     * `token_exchange_failed` (the underlying HTTP status / OAuth2 error,
+     * or a fetch cause code such as `UNABLE_TO_GET_ISSUER_CERT_LOCALLY` /
+     * `ECONNREFUSED`). Never contains the authorization code or a token.
+     */
+    detail?: string;
 };
-export type PkceDeclineReason = "headless" | "timeout" | "user_denied" | "state_mismatch" | "no_port" | "browser_launch_failed" | "aborted" | "token_exchange_failed";
+export type PkceDeclineReason = "headless" | "timeout" | "user_denied" | "state_mismatch" | "no_port" | "browser_launch_failed" | "aborted" | "token_exchange_failed"
+/** The authorization server rejected the requested scope (`invalid_scope`). */
+ | "invalid_scope"
+/** The authorization server returned some other `error` on the redirect. */
+ | "oauth_error";
 /**
  * Default headless heuristic. Returns true only for unattended runs
  * (CI=true / CI=1) so {@link pkceLogin} can short-circuit instead of
@@ -91,3 +120,10 @@ export declare function refreshAccessToken(args: {
     clientId: string;
     refreshToken: string;
 }): Promise<OryOAuth2Tokens>;
+/**
+ * Best-effort human-readable name for the signed-in user, pulled from the
+ * id_token's identity claims — `email`, then `name`, then `preferred_username`.
+ * Returns undefined when the token carries none of them (e.g. an `openid`-only
+ * token), so callers fall back to the opaque subject id.
+ */
+export declare function displayNameFromIdToken(idToken: string | undefined): string | undefined;

package/dist/auth.js

@@ -12,6 +12,39 @@
  * package via dynamic import so the CJS-emitted core stays compatible
  * with its ESM-only export shape.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_LOGIN_TIMEOUT_MS = exports.LOOPBACK_PORTS = void 0;
 exports.detectHeadless = detectHeadless;
@@ -20,13 +53,40 @@ exports.generateCodeVerifier = generateCodeVerifier;
 exports.sha256Base64Url = sha256Base64Url;
 exports.buildAuthorizeUrl = buildAuthorizeUrl;
 exports.refreshAccessToken = refreshAccessToken;
+exports.displayNameFromIdToken = displayNameFromIdToken;
 const node_crypto_1 = require("node:crypto");
 const node_http_1 = require("node:http");
 const node_url_1 = require("node:url");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const branding_js_1 = require("./branding.js");
 /** Loopback ports tried in order. All must be registered as redirect URIs on the Ory OAuth2 client. */
 exports.LOOPBACK_PORTS = [47823, 47824, 47825, 47826];
-/** Hard timeout if the user never returns to the browser. */
-exports.DEFAULT_LOGIN_TIMEOUT_MS = 120_000;
+/**
+ * Hard timeout if the user never returns to the browser.
+ *
+ * Sized to fit **inside** the tightest session-start hook window any harness
+ * will accept, so the login always gives up on its own terms and records a
+ * `timeout` decline the user can act on. Being SIGKILLed by the harness
+ * instead surfaces nothing at all: the session proceeds with no user identity,
+ * and under `enforce` every subsequent tool is denied for a reason nothing
+ * explains (#220).
+ *
+ * The binding constraint is Antigravity, which validates its hook timeout to
+ * `5..120` seconds — so 120s is the ceiling, and this leaves headroom for the
+ * agent DCR registration and delegation record that run after the login inside
+ * the same hook invocation. See `hook-timeout.ts`, which derives every
+ * harness's declared window and asserts it outlasts this value.
+ */
+exports.DEFAULT_LOGIN_TIMEOUT_MS = 90_000;
+/**
+ * Login scopes, derived from the single source of truth in branding so the
+ * PKCE request can never drift from what the install registers the client
+ * with. `WIDE` (with profile/email) is requested by default and dropped to
+ * `BASE` if the client isn't allowed those scopes (see {@link pkceLogin}).
+ */
+const BASE_LOGIN_SCOPE = branding_js_1.USER_LOGIN_BASE_SCOPES.join(" ");
+const WIDE_LOGIN_SCOPE = branding_js_1.USER_LOGIN_SCOPE_OAUTH;
 /**
  * Default headless heuristic. Returns true only for unattended runs
  * (CI=true / CI=1) so {@link pkceLogin} can short-circuit instead of
@@ -51,12 +111,40 @@ function detectHeadless(env = process.env) {
  */
 async function pkceLogin(options) {
     const isHeadless = options.isHeadless ?? detectHeadless;
-    const headless = isHeadless();
-    if (headless) {
+    if (isHeadless()) {
         // Unattended environment (CI). No human to follow the URL, so we
         // skip the loopback listener entirely instead of timing out.
         return { kind: "declined", reason: "headless" };
     }
+    // An explicit scope is honored verbatim. The default asks for `profile` and
+    // `email` (so the id_token carries the signed-in user's name) but falls back
+    // to the base scope when the login client isn't allowed them — otherwise a
+    // client not configured for those scopes could never complete login
+    // (`invalid_scope`). The fallback costs one extra redirect, no user action.
+    const scopes = options.scope ? [options.scope] : [WIDE_LOGIN_SCOPE, BASE_LOGIN_SCOPE];
+    let outcome = { kind: "declined", reason: "user_denied" };
+    for (let i = 0; i < scopes.length; i++) {
+        const scopeFallbackPending = i < scopes.length - 1;
+        outcome = await runPkceAttempt(options, scopes[i], scopeFallbackPending);
+        if (outcome.kind === "ok")
+            return outcome;
+        if (outcome.reason === "invalid_scope" && scopeFallbackPending) {
+            process.stderr.write("The sign-in client isn't allowed the requested profile/email scopes; " +
+                "retrying with basic scopes (your name may not be shown in status).\n\n");
+            continue;
+        }
+        return outcome;
+    }
+    return outcome;
+}
+/**
+ * One PKCE attempt with a specific scope string: bind a loopback port, open the
+ * browser, wait for the callback, and exchange the code. `scopeFallbackPending`
+ * is true when {@link pkceLogin} will retry with a narrower scope if this
+ * attempt is rejected for `invalid_scope`, so the browser page can say
+ * "reconnecting" instead of showing a hard failure.
+ */
+async function runPkceAttempt(options, scope, scopeFallbackPending) {
     const { server, port } = await listenOnFirstAvailablePort(options.ports ?? exports.LOOPBACK_PORTS);
     if (!server || port === null) {
         return { kind: "declined", reason: "no_port" };
@@ -65,7 +153,6 @@ async function pkceLogin(options) {
     const codeChallenge = sha256Base64Url(codeVerifier);
     const state = (0, node_crypto_1.randomBytes)(16).toString("base64url");
     const redirectUri = `http://127.0.0.1:${port}/callback`;
-    const scope = options.scope ?? "openid offline_access";
     const authorizeUrl = buildAuthorizeUrl({
         projectUrl: options.projectUrl,
         clientId: options.clientId,
@@ -87,6 +174,7 @@ async function pkceLogin(options) {
         expectedState: state,
         timeoutMs,
         signal: options.signal,
+        scopeFallbackPending,
     });
     // Browser launch is best-effort. If `open` throws or the platform has
     // no usable browser, we keep the callback server alive and rely on the
@@ -117,10 +205,35 @@ async function pkceLogin(options) {
         });
         return { kind: "ok", tokens };
     }
-    catch {
-        return { kind: "declined", reason: "token_exchange_failed" };
+    catch (err) {
+        // Surface the underlying cause (HTTP status + OAuth2 error, or a fetch
+        // cause code like a TLS-trust failure) instead of swallowing it — this
+        // is the difference between a diagnosable failure and a bare
+        // "exchange failed" message. The detail is secret-free.
+        return {
+            kind: "declined",
+            reason: "token_exchange_failed",
+            detail: describeExchangeError(err),
+        };
     }
 }
+/**
+ * Render an error thrown by {@link exchangeCodeForTokens} into a concise,
+ * secret-free detail string. For a failed `fetch` the useful signal is the
+ * low-level cause code (`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, `ECONNREFUSED`,
+ * …); for a non-2xx response the message already carries the HTTP status and
+ * the OAuth2 `error`. Neither includes the authorization code or any token.
+ */
+function describeExchangeError(err) {
+    if (err instanceof Error) {
+        const cause = err.cause;
+        const code = cause && typeof cause === "object" && "code" in cause
+            ? String(cause.code)
+            : undefined;
+        return code ? `${err.message} (${code})` : err.message;
+    }
+    return String(err);
+}
 // ─── PKCE primitives ──────────────────────────────────────────────────
 /** Generate a 64-byte (≈86-char base64url) code verifier per RFC 7636. */
 function generateCodeVerifier() {
@@ -201,14 +314,37 @@ function waitForCallback(server, opts) {
                 return;
             }
             const url = new node_url_1.URL(req.url ?? "/", `http://127.0.0.1`);
+            if (url.pathname === "/favicon.ico") {
+                respondFavicon(res);
+                return;
+            }
             if (url.pathname !== "/callback") {
                 respond(res, 404, "Not Found");
                 return;
             }
             const error = url.searchParams.get("error");
             if (error) {
-                respondHtml(res, 400, resultPage("cancelled"));
-                settle({ kind: "declined", reason: "user_denied" });
+                const description = url.searchParams.get("error_description") ?? undefined;
+                // `access_denied` is the user clicking "cancel" — not an error to alarm
+                // them with. Everything else is a real authorization-server rejection
+                // (misconfigured client, unsupported scope, …); show the actual reason
+                // so it can be acted on rather than a generic "cancelled".
+                if (error === "access_denied") {
+                    respondHtml(res, 400, resultPage("cancelled"));
+                    settle({ kind: "declined", reason: "user_denied" });
+                }
+                else if (error === "invalid_scope") {
+                    // A pending scope fallback will retry immediately with fewer scopes,
+                    // so don't flash a hard failure — say we're reconnecting.
+                    respondHtml(res, 400, opts.scopeFallbackPending
+                        ? resultPage("reconnecting")
+                        : resultPage("error", { code: error, description }));
+                    settle({ kind: "declined", reason: "invalid_scope" });
+                }
+                else {
+                    respondHtml(res, 400, resultPage("error", { code: error, description }));
+                    settle({ kind: "declined", reason: "oauth_error" });
+                }
                 return;
             }
             const state = url.searchParams.get("state");
@@ -238,18 +374,40 @@ function respondHtml(res, status, html) {
     res.writeHead(status, { "content-type": "text/html; charset=utf-8" });
     res.end(html);
 }
+/**
+ * Serve the shared Ory favicon (identical to console.ory.com's) so the sign-in
+ * result page carries the same tab icon as the Console, when a bundled
+ * `dist/webapp/favicon.ico` is present. It normally isn't, so this falls back
+ * to a 404 — the page still renders, just without a favicon. Same-origin on the
+ * loopback server, so no external request is made.
+ */
+function respondFavicon(res) {
+    // Compiled to dist/auth.js; look for an optional favicon under dist/webapp.
+    const file = path.join(__dirname, "webapp", "favicon.ico");
+    try {
+        const buf = fs.readFileSync(file);
+        res.writeHead(200, {
+            "content-type": "image/x-icon",
+            "cache-control": "no-store",
+        });
+        res.end(buf);
+    }
+    catch {
+        respond(res, 404, "Not Found");
+    }
+}
 /**
  * The page the browser lands on after the OAuth2 redirect. The whole point is
  * to make the next action unambiguous: on success it tells the user, in plain
  * words, that they can close the tab and return to the terminal (the #1
- * source of "is it done? do I close this?" confusion). Self-contained HTML —
- * inline styles only, Ory-branded (Indigo #4F46E5), no external requests — so
- * it renders identically offline and on the loopback origin.
+ * source of "is it done? do I close this?" confusion). Inline styles only, no
+ * external requests — the only asset is the same-origin Ory favicon the
+ * loopback server serves — so it renders identically offline.
  */
-function resultPage(kind) {
+function resultPage(kind, detail) {
     const view = {
         success: {
-            accent: "#4F46E5", // Ory Indigo
+            accent: "#22C55E", // green — a positive "done" check
             icon: "&#10003;", // ✓
             title: "Signed in to Ory",
             body: "You can <strong>close this tab</strong> and return to your terminal — setup continues automatically.",
@@ -266,12 +424,30 @@ function resultPage(kind) {
             title: "Sign-in could not be verified",
             body: "The login response failed a security check. <strong>Close this tab</strong> and re-run the login from your terminal.",
         },
+        error: {
+            accent: "#F43F5E",
+            icon: "!",
+            title: "Sign-in failed",
+            body: "Ory rejected the sign-in request. <strong>Close this tab</strong> and return to your terminal — the details below say why.",
+        },
+        reconnecting: {
+            accent: "#6366F1", // indigo — a neutral "in progress"
+            icon: "&#8635;", // ↻
+            title: "Reconnecting…",
+            body: "Re-opening sign-in with basic permissions. You can <strong>close this tab</strong>; a new one will open to continue.",
+        },
     }[kind];
+    // The authorization server's own `error` / `error_description`, shown verbatim
+    // (escaped) so a misconfiguration is actionable instead of opaque.
+    const detailBlock = detail && (detail.code || detail.description)
+        ? `\n    <pre class="detail">${escapeHtml([detail.code, detail.description].filter(Boolean).join("\n"))}</pre>`
+        : "";
     return `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
+<link rel="icon" href="/favicon.ico">
 <title>${view.title}</title>
 <style>
   :root { color-scheme: light dark; }
@@ -291,18 +467,32 @@ function resultPage(kind) {
   h1 { font-size: 1.35rem; margin: 0 0 .5rem; color: #F8FAFC; }
   p { margin: 0; line-height: 1.55; color: #94A3B8; }
   strong { color: #E2E8F0; font-weight: 600; }
+  .detail {
+    margin: 1.25rem 0 0; padding: .75rem 1rem; text-align: left;
+    border-radius: .5rem; background: #1E293B; color: #CBD5E1;
+    font-size: .8rem; line-height: 1.5; white-space: pre-wrap; word-break: break-word;
+  }
 </style>
 </head>
 <body>
   <div class="card">
     <div class="badge">${view.icon}</div>
     <h1>${view.title}</h1>
-    <p>${view.body}</p>
+    <p>${view.body}</p>${detailBlock}
   </div>
 </body>
 </html>
 `;
 }
+/** Minimal HTML-entity escape for untrusted text interpolated into the page. */
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
 // ─── Browser launch ───────────────────────────────────────────────────
 async function launchBrowser(url, override) {
     if (override) {
@@ -332,7 +522,23 @@ async function exchangeCodeForTokens(args) {
         body: body.toString(),
     });
     if (!res.ok) {
-        throw new Error(`Token exchange failed: HTTP ${res.status}`);
+        // Include the OAuth2 error from the body when present. `error` /
+        // `error_description` are standard OAuth2 diagnostics (e.g.
+        // `invalid_client`, `invalid_grant`), not secrets — they turn an opaque
+        // 400/401 into an actionable message.
+        let suffix = "";
+        try {
+            const body = (await res.json());
+            const error = typeof body.error === "string" ? body.error : undefined;
+            if (error) {
+                const desc = typeof body.error_description === "string" ? body.error_description : undefined;
+                suffix = desc ? `: ${error} — ${desc}` : `: ${error}`;
+            }
+        }
+        catch {
+            // Non-JSON body; the status alone is the diagnostic.
+        }
+        throw new Error(`Token exchange failed: HTTP ${res.status}${suffix}`);
     }
     const json = (await res.json());
     return tokensFromTokenResponse(json, args.clientId);
@@ -369,18 +575,23 @@ function tokensFromTokenResponse(json, clientId, fallbackRefreshToken) {
         throw new Error("Token response missing access_token");
     const expiresIn = typeof json.expires_in === "number" ? json.expires_in : 3600;
     const refreshToken = typeof json.refresh_token === "string" ? json.refresh_token : fallbackRefreshToken;
+    const idToken = typeof json.id_token === "string" ? json.id_token : undefined;
     return {
         accessToken,
         refreshToken,
         expiresAt: Math.floor(Date.now() / 1000) + expiresIn,
         clientId,
-        idToken: typeof json.id_token === "string" ? json.id_token : undefined,
+        displayName: displayNameFromIdToken(idToken),
         scope: typeof json.scope === "string" ? json.scope : undefined,
-        subject: subjectFromIdToken(typeof json.id_token === "string" ? json.id_token : undefined),
+        subject: subjectFromIdToken(idToken),
     };
 }
 /** Best-effort sub-claim extraction from a JWT id_token. Returns undefined on any failure. */
 function subjectFromIdToken(idToken) {
+    return claimsFromIdToken(idToken)?.sub;
+}
+/** Best-effort JWT id_token payload decode. Returns undefined on any failure. */
+function claimsFromIdToken(idToken) {
     if (!idToken)
         return undefined;
     const parts = idToken.split(".");
@@ -388,9 +599,26 @@ function subjectFromIdToken(idToken) {
         return undefined;
     try {
         const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
-        return typeof payload.sub === "string" ? payload.sub : undefined;
+        return payload && typeof payload === "object" ? payload : undefined;
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Best-effort human-readable name for the signed-in user, pulled from the
+ * id_token's identity claims — `email`, then `name`, then `preferred_username`.
+ * Returns undefined when the token carries none of them (e.g. an `openid`-only
+ * token), so callers fall back to the opaque subject id.
+ */
+function displayNameFromIdToken(idToken) {
+    const claims = claimsFromIdToken(idToken);
+    if (!claims)
+        return undefined;
+    for (const key of ["email", "name", "preferred_username"]) {
+        const v = claims[key];
+        if (typeof v === "string" && v.trim())
+            return v.trim();
+    }
+    return undefined;
+}