linear-sdk-cli 0.2.4 → 0.3.1

package/src/config.ts

@@ -10,18 +10,23 @@
  *    each directory — every location schpet/linear-cli 2.5 reads (it checks
  *    cwd and the git root; we check every directory between, which is a
  *    superset), in its order.
- *  - The API key has a STRICTER boundary and is never read from a project file
+ *  - Authentication secrets have a STRICTER boundary and are never read from a project file
  *    or from the reference CLI's global file (avoids committing secrets):
- *    flag > LINEAR_API_KEY env > user config (plaintext `api_key`) > OS keyring.
+ *    Explicit `--access-token` / `--api-key` flags override their environment counterparts.
+ *    Invocation OAuth access tokens are stateless (`LINEAR_ACCESS_TOKEN` only). Human browser
+ *    OAuth sessions and API keys may also come from the OS keyring; API keys alone may opt into
+ *    the user config as plaintext.
  *    A project `workspace` may select which already-stored credential to use;
  *    it can never provide or override the secret itself.
  *
  * Multi-workspace credentials live under quoted `[workspaces."<slug>"]` tables
  * in the user config, with an optional top-level `default_workspace`. A table
  * either carries the key itself (`api_key = "…"`, plaintext, 0600 file) or
- * marks the slug as keyring-backed (`keyring = true`), in which case the secret
+ * marks the slug as keyring-backed (`keyring = true`), in which case an API-key secret
  * lives in the OS keyring under service `linear-cli` / account `<slug>` — the
- * reference CLI's convention, so a user migrating from it is authenticated
+ * reference CLI's convention. A browser OAuth session uses the isolated account
+ * `oauth:<slug>` and a non-secret `oauth = true` marker, so its rotating token record
+ * cannot be mistaken for an API key. A user migrating from the reference CLI is authenticated
  * before they run a single command. Its own workspace list
  * (`credentials.toml`, a sibling of our file) is read for slugs and the
  * default, never for keys. Credential selection is lazy: resolution never
@@ -50,18 +55,20 @@ import { execFileSync } from "node:child_process";
 import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
 import { CliError } from "./lib/errors.js";
 import { keyring, KeyringError } from "./lib/keyring.js";
+import type { OAuthUserCredential } from "./oauth.js";
 
 export interface RawSettings {
   team?: string;
   workspace?: string;
   sort?: string;
   apiKey?: string;
+  accessToken?: string;
 }
 
 /**
  * Where a value came from. `user` is our `~/.config/linear/config.toml`;
  * `global` is the reference CLI's `~/.config/linear/linear.toml`, read for
- * non-secret settings only; `keychain` is the OS keyring (API key only).
+ * non-secret settings only; `keychain` is the OS keyring (API key or human OAuth session).
  */
 export type ConfigSource = "flag" | "env" | "project" | "user" | "global" | "keychain" | "none";
 
@@ -82,9 +89,14 @@ export type SettingOrigins = Record<"team" | "workspace" | "sort", SettingOrigin
 export interface ResolvedConfig {
   apiKey?: string;
   apiKeySource: ConfigSource;
+  /** OAuth access token supplied for this invocation; never read from or written to config. */
+  accessToken?: string;
+  accessTokenSource: ConfigSource;
+  /** Keyring-backed human OAuth session. Never serialized outside the keyring. */
+  oauthCredential?: OAuthUserCredential;
   /**
-   * Deferred credential-selection error. Resolution is total (it never throws
-   * for selection problems) so commands that REPAIR auth state — `auth list`,
+   * Deferred credential-resolution error. Resolution is total (it never throws
+   * for selection or ambiguous identity problems) so commands that REPAIR auth state — `auth list`,
    * `auth default`, `auth logout`, `auth login --workspace new-org` — can still
    * build a Context. The error is surfaced only when an API client is actually
    * needed (see createClient / `auth token`).
@@ -160,6 +172,8 @@ export function referenceCredentialsPath(env: NodeJS.ProcessEnv = process.env):
 interface WorkspaceEntry {
   /** Plaintext key from `[workspaces."<slug>"].api_key`; absent → keyring-backed. */
   apiKey?: string;
+  /** This workspace uses the isolated `oauth:<slug>` keyring account. */
+  oauth?: boolean;
 }
 
 /** Parsed view of the user config: top-level settings + nested workspace creds. */
@@ -310,7 +324,11 @@ function readUserConfig(path: string): UserConfig {
       if (val && typeof val === "object") {
         // A table with no api_key is a keyring-backed workspace (whether or
         // not it carries the `keyring = true` marker `auth login` writes).
-        workspaces[slug] = { apiKey: asString((val as Record<string, unknown>).api_key) };
+        const table = val as Record<string, unknown>;
+        workspaces[slug] = {
+          apiKey: asString(table.api_key),
+          oauth: table.oauth === true,
+        };
       }
     }
   }
@@ -335,7 +353,21 @@ function readUserConfig(path: string): UserConfig {
 function lookupCredential(
   user: UserConfig,
   slug: string,
-): { apiKey: string; source: "user" | "keychain" } | { error: CliError } | undefined {
+):
+  | { apiKey: string; source: "user" | "keychain" }
+  | { oauthCredential: OAuthUserCredential; source: "keychain" }
+  | { error: CliError }
+  | undefined {
+  if (user.workspaces[slug]?.oauth) {
+    try {
+      const credential = readOAuthCredential(slug);
+      return credential ? { oauthCredential: credential, source: "keychain" } : undefined;
+    } catch (err) {
+      return {
+        error: err instanceof CliError ? err : new CliError("Could not read OAuth credentials."),
+      };
+    }
+  }
   const plaintext = user.workspaces[slug]?.apiKey;
   if (plaintext) return { apiKey: plaintext, source: "user" };
   const backend = keyring();
@@ -385,6 +417,7 @@ export function findProjectConfig(cwd: string): string | undefined {
 function fromEnv(env: NodeJS.ProcessEnv): RawSettings {
   return {
     apiKey: env.LINEAR_API_KEY || env.LINEAR_API_TOKEN,
+    accessToken: env.LINEAR_ACCESS_TOKEN,
     team: env.LINEAR_TEAM || env.LINEAR_TEAM_ID,
     workspace: env.LINEAR_WORKSPACE,
     sort: env.LINEAR_ISSUE_SORT,
@@ -407,19 +440,38 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
   const globalPath = existsSync(globalCandidate) ? globalCandidate : undefined;
   const global = globalPath ? readTomlFile(globalPath) : { settings: {}, keys: {} };
 
-  // ----- API key resolution (strict trust boundary) -----------------------
+  // ----- Credential resolution (strict trust boundary) --------------------
   // Resolution is TOTAL: selection problems are stashed in `apiKeyError` rather
   // than thrown, so auth-repair commands can still build a Context. The error
   // is surfaced lazily, when an API client is actually needed.
   let apiKey: string | undefined;
   let apiKeySource: ConfigSource = "none";
+  let accessToken: string | undefined;
+  let accessTokenSource: ConfigSource = "none";
+  let oauthCredential: OAuthUserCredential | undefined;
   let credentialWorkspace: string | undefined;
   let apiKeyError: CliError | undefined;
 
-  if (flags.apiKey) {
-    // 1. An explicit flag is absolute: it bypasses all workspace selection.
+  if (flags.apiKey && flags.accessToken) {
+    apiKeyError = new CliError(
+      "Pass only one of --api-key or --access-token; they may identify different Linear actors.",
+      "usage",
+    );
+  } else if (flags.accessToken) {
+    // 1. An explicit credential flag is absolute: it bypasses env and workspace selection.
+    accessToken = flags.accessToken;
+    accessTokenSource = "flag";
+  } else if (flags.apiKey) {
     apiKey = flags.apiKey;
     apiKeySource = "flag";
+  } else if (envSettings.apiKey && envSettings.accessToken) {
+    apiKeyError = new CliError(
+      "Both LINEAR_API_KEY/LINEAR_API_TOKEN and LINEAR_ACCESS_TOKEN are set. Unset one so the Linear actor is unambiguous.",
+      "usage",
+    );
+  } else if (envSettings.accessToken) {
+    accessToken = envSettings.accessToken;
+    accessTokenSource = "env";
   } else if (envSettings.apiKey) {
     // 1. LINEAR_API_KEY/LINEAR_API_TOKEN is absolute too.
     apiKey = envSettings.apiKey;
@@ -448,8 +500,14 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
       } else if ("error" in found) {
         apiKeyError = found.error;
       } else {
-        apiKey = found.apiKey;
-        apiKeySource = found.source;
+        if ("oauthCredential" in found) {
+          oauthCredential = found.oauthCredential;
+          accessToken = found.oauthCredential.accessToken;
+          accessTokenSource = found.source;
+        } else {
+          apiKey = found.apiKey;
+          apiKeySource = found.source;
+        }
         credentialWorkspace = slug;
       }
     };
@@ -504,6 +562,9 @@ export function resolveConfig(inputs: ConfigInputs = {}): ResolvedConfig {
   return {
     apiKey,
     apiKeySource,
+    accessToken,
+    accessTokenSource,
+    oauthCredential,
     apiKeyError,
     credentialWorkspace,
     team: pick("team"),
@@ -761,6 +822,7 @@ function writeUserObject(path: string, obj: Record<string, unknown>): void {
 interface WorkspaceTable {
   api_key?: string;
   keyring?: boolean;
+  oauth?: boolean;
 }
 
 function workspacesTable(obj: Record<string, unknown>): Record<string, WorkspaceTable> {
@@ -777,6 +839,166 @@ export interface WriteCredentialResult {
   keyringLabel?: string;
 }
 
+export const OAUTH_KEYRING_ACCOUNT_PREFIX = "oauth:";
+
+function oauthAccount(slug: string): string {
+  return `${OAUTH_KEYRING_ACCOUNT_PREFIX}${slug}`;
+}
+
+function parseOAuthCredential(slug: string, raw: string): OAuthUserCredential {
+  let value: unknown;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new CliError(
+      `The stored OAuth credential for workspace '${sanitize(slug)}' is malformed. Run \`linear auth logout --workspace ${sanitize(slug)} --local-only\` and sign in again.`,
+      "auth",
+    );
+  }
+  const c = value as Partial<OAuthUserCredential> | null;
+  if (
+    !c ||
+    c.version !== 1 ||
+    c.kind !== "oauth-user" ||
+    c.actor !== "user" ||
+    typeof c.accessToken !== "string" ||
+    !c.accessToken ||
+    typeof c.refreshToken !== "string" ||
+    !c.refreshToken ||
+    typeof c.expiresAt !== "number" ||
+    !Number.isFinite(c.expiresAt) ||
+    !Array.isArray(c.scopes) ||
+    c.scopes.some((scope) => typeof scope !== "string" || !scope) ||
+    c.tokenType !== "Bearer" ||
+    typeof c.clientId !== "string" ||
+    !c.clientId ||
+    !c.workspace ||
+    typeof c.workspace.id !== "string" ||
+    typeof c.workspace.name !== "string" ||
+    c.workspace.urlKey !== slug ||
+    !c.user ||
+    typeof c.user.id !== "string" ||
+    typeof c.user.name !== "string" ||
+    typeof c.user.email !== "string"
+  ) {
+    throw new CliError(
+      `The stored OAuth credential for workspace '${sanitize(slug)}' is invalid. Sign in again.`,
+      "auth",
+    );
+  }
+  return c as OAuthUserCredential;
+}
+
+/** Read one explicitly selected human OAuth session from its isolated keyring account. */
+export function readOAuthCredential(slug: string): OAuthUserCredential | undefined {
+  const backend = keyring();
+  if (!backend) {
+    throw new CliError(
+      `A system keyring is required for OAuth credentials for workspace '${sanitize(slug)}'.`,
+      "runtime",
+    );
+  }
+  let raw: string | null;
+  try {
+    raw = backend.get(oauthAccount(slug));
+  } catch {
+    throw new CliError(
+      `Could not read the ${backend.label} OAuth entry for workspace '${sanitize(slug)}'.`,
+      "runtime",
+    );
+  }
+  return raw ? parseOAuthCredential(slug, raw) : undefined;
+}
+
+export interface WriteOAuthCredentialResult {
+  path: string;
+  storage: "keychain";
+  keyringLabel: string;
+}
+
+/** Store the complete OAuth session in the keyring; the config gets only a non-secret marker. */
+export function writeOAuthCredential(credential: OAuthUserCredential): WriteOAuthCredentialResult {
+  const slug = credential.workspace.urlKey;
+  const path = userConfigPath();
+  const backend = keyring();
+  if (!backend) {
+    throw new CliError(
+      "Browser OAuth requires a usable system keyring; use `linear auth login --key -` on this platform.",
+      "runtime",
+    );
+  }
+  return withUserConfigLock(path, () => {
+    const account = oauthAccount(slug);
+    let previous: string | null;
+    try {
+      previous = backend.get(account);
+      backend.set(account, JSON.stringify(credential));
+    } catch {
+      throw new CliError(
+        `Could not store OAuth credentials for workspace '${sanitize(slug)}' in the ${backend.label}.`,
+        "runtime",
+      );
+    }
+    try {
+      const obj = readUserObject(path);
+      const ws = workspacesTable(obj);
+      const table: WorkspaceTable = { ...(ws[slug] ?? {}) };
+      table.keyring = true;
+      table.oauth = true;
+      ws[slug] = table;
+      if (!asString(obj.default_workspace)) {
+        const reference = readReferenceCredentials(referenceCredentialsPath());
+        if (!reference.defaultWorkspace) obj.default_workspace = slug;
+      }
+      writeUserObject(path, obj);
+    } catch (err) {
+      try {
+        if (previous === null) backend.delete(account);
+        else backend.set(account, previous);
+      } catch {
+        // The primary error is the failed config commit; do not expose secrets from a rollback error.
+      }
+      throw err;
+    }
+    return { path, storage: "keychain", keyringLabel: backend.label };
+  });
+}
+
+/** Compare-and-swap rotating refresh state. A concurrent winner is retained, never overwritten. */
+export function rotateOAuthCredential(
+  slug: string,
+  previousRefreshToken: string,
+  next: OAuthUserCredential,
+): OAuthUserCredential {
+  const path = userConfigPath();
+  return withUserConfigLock(path, () => {
+    const backend = keyring();
+    if (!backend) throw new CliError("A system keyring is required to refresh OAuth credentials.");
+    let raw: string | null;
+    try {
+      raw = backend.get(oauthAccount(slug));
+    } catch {
+      throw new CliError(
+        `Could not read OAuth credentials for workspace '${sanitize(slug)}' from the ${backend.label}.`,
+        "runtime",
+      );
+    }
+    if (!raw)
+      throw new CliError(`No stored OAuth credential for workspace '${sanitize(slug)}'.`, "auth");
+    const current = parseOAuthCredential(slug, raw);
+    if (current.refreshToken !== previousRefreshToken) return current;
+    try {
+      backend.set(oauthAccount(slug), JSON.stringify(next));
+    } catch {
+      throw new CliError(
+        `Could not rotate OAuth credentials for workspace '${sanitize(slug)}' in the ${backend.label}.`,
+        "runtime",
+      );
+    }
+    return next;
+  });
+}
+
 /** A single, explicitly named credential found in the shared OS keyring. */
 export interface KeyringCredentialProbe {
   /** Kept in memory only; callers must never print it or pass it on argv. */
@@ -880,6 +1102,7 @@ export function writeCredential(
   const path = userConfigPath();
   return withUserConfigLock(path, () => {
     const backend = opts.plaintext ? null : keyring();
+    const systemBackend = keyring();
     const obj = readUserObject(path);
     const ws = workspacesTable(obj);
     const table: WorkspaceTable = { ...(ws[slug] ?? {}) };
@@ -889,12 +1112,15 @@ export function writeCredential(
       backend.set(slug, apiKey);
       delete table.api_key;
       table.keyring = true;
+      delete table.oauth;
       storage = "keychain";
     } else {
       delete table.keyring;
+      delete table.oauth;
       table.api_key = apiKey;
       storage = "file";
     }
+    systemBackend?.delete(oauthAccount(slug));
     ws[slug] = table;
     if (!asString(obj.default_workspace)) {
       // Leave the reference CLI's default in charge if it has one; writing ours
@@ -956,7 +1182,10 @@ export function removeCredential(slug: string): boolean {
     let removed = false;
 
     const backend = keyring();
-    if (backend && backend.delete(slug)) removed = true;
+    if (backend) {
+      if (backend.delete(slug)) removed = true;
+      if (backend.delete(oauthAccount(slug))) removed = true;
+    }
     if (removeFromReferenceCredentials(slug)) removed = true;
 
     if (!existsSync(path)) return removed;
@@ -981,6 +1210,78 @@ export function removeCredential(slug: string): boolean {
   });
 }
 
+export interface RemoveOAuthCredentialResult {
+  removed: boolean;
+  fallbackCredentialType: "api-key" | null;
+}
+
+/** Remove only the human OAuth lifecycle, restoring a pre-existing API-key profile if present. */
+export function removeOAuthCredential(slug: string): RemoveOAuthCredentialResult {
+  const path = userConfigPath();
+  return withUserConfigLock(path, () => {
+    const backend = keyring();
+    let oauthRaw: string | null = null;
+    let keyringApiKey = false;
+    let removed = false;
+    if (backend) {
+      try {
+        oauthRaw = backend.get(oauthAccount(slug));
+        keyringApiKey = backend.get(slug) !== null;
+        if (oauthRaw && backend.delete(oauthAccount(slug))) removed = true;
+      } catch {
+        throw new CliError(
+          `Could not remove OAuth credentials for workspace '${sanitize(slug)}' from the ${backend.label}.`,
+          "runtime",
+        );
+      }
+    }
+
+    if (!existsSync(path)) {
+      return { removed, fallbackCredentialType: keyringApiKey ? "api-key" : null };
+    }
+    try {
+      const obj = readUserObject(path);
+      const ws = workspacesTable(obj);
+      const table = ws[slug];
+      const hadOAuthMarker = table?.oauth === true;
+      if (hadOAuthMarker) removed = true;
+      const reference = readReferenceCredentials(referenceCredentialsPath());
+      const apiKeyFallback = Boolean(asString(table?.api_key)) || keyringApiKey;
+
+      if (apiKeyFallback) {
+        const fallback: WorkspaceTable = { ...(table ?? {}) };
+        delete fallback.oauth;
+        if (asString(fallback.api_key)) delete fallback.keyring;
+        else fallback.keyring = true;
+        ws[slug] = fallback;
+      } else if (table) {
+        delete ws[slug];
+      }
+      if (Object.keys(ws).length === 0) delete obj.workspaces;
+
+      if (!apiKeyFallback && asString(obj.default_workspace) === slug) {
+        const remaining = obj.workspaces ? Object.keys(obj.workspaces as object) : [];
+        const referenceFallback = reference.workspaces.find((candidate) => candidate !== slug);
+        if (remaining.length > 0) obj.default_workspace = remaining[0]!;
+        else if (referenceFallback) obj.default_workspace = referenceFallback;
+        else delete obj.default_workspace;
+      }
+      if (hadOAuthMarker || apiKeyFallback) writeUserObject(path, obj);
+      return {
+        removed,
+        fallbackCredentialType: apiKeyFallback ? "api-key" : null,
+      };
+    } catch (err) {
+      try {
+        if (backend && oauthRaw) backend.set(oauthAccount(slug), oauthRaw);
+      } catch {
+        // Preserve the primary config error without exposing keyring or credential details.
+      }
+      throw err;
+    }
+  });
+}
+
 export interface MigrateResult {
   /** Slugs whose keys moved from the file into the keyring. */
   migrated: string[];
@@ -1042,6 +1343,7 @@ export interface CredentialEntry {
   isDefault: boolean;
   /** Where the secret is kept. */
   storage: CredentialStorage;
+  credentialType: "api-key" | "oauth-user";
 }
 
 /** List configured credentials: one entry per stored workspace. */
@@ -1052,6 +1354,7 @@ export function listCredentials(env: NodeJS.ProcessEnv = process.env): Credentia
     slug,
     isDefault: user.defaultWorkspace === slug,
     storage: entry.apiKey ? "file" : "keychain",
+    credentialType: entry.oauth ? "oauth-user" : "api-key",
   }));
 }
 
@@ -1088,7 +1391,7 @@ const KEY_ALIASES: Record<SettableKey, readonly string[]> = {
 };
 
 /** Keys that must never be written to a project file, and why. */
-const SECRET_KEYS = new Set(["api_key", "workspaces", "default_workspace", "keyring"]);
+const SECRET_KEYS = new Set(["api_key", "workspaces", "default_workspace", "keyring", "oauth"]);
 
 /**
  * Where `config init` writes and `config set` falls back to when no project

package/src/context.ts

@@ -28,6 +28,7 @@ export interface GlobalOptions {
   /** `--no-input`. Present (true) only when passed. */
   noInput?: boolean;
   apiKey?: string;
+  accessToken?: string;
   /** A key, or several — `issue list`/`mine`/`search` make `--team` repeatable. */
   team?: string | string[];
   workspace?: string;
@@ -60,6 +61,7 @@ export class Context {
       // and the config sees the first key.
       flags: {
         apiKey: options.apiKey,
+        accessToken: options.accessToken,
         team: firstTeam(options.team),
         workspace: options.workspace,
       },

package/src/index.ts

@@ -6,5 +6,24 @@ export { createProgram, VERSION } from "./cli.js";
 export { Context } from "./context.js";
 export { resolveConfig, type ResolvedConfig } from "./config.js";
 export { createClient } from "./client.js";
+export {
+  DEFAULT_OAUTH_CALLBACK_TIMEOUT_MS,
+  DEFAULT_OAUTH_REFRESH_SKEW_MS,
+  DEFAULT_OAUTH_SCOPES,
+  ClientCredentialsTokenProvider,
+  OAuthUserTokenProvider,
+  OAuthTokenError,
+  buildAuthorizationUrl,
+  createPkceRequest,
+  exchangeAuthorizationCode,
+  revokeOAuthToken,
+  startLoopbackCallback,
+  type ClientCredentialsTokenProviderOptions,
+  type GetAccessTokenOptions,
+  type OAuthAccessToken,
+  type OAuthUserCredential,
+  type OAuthUserTokenProviderOptions,
+  type PkceRequest,
+} from "./oauth.js";
 export { CliError, ExitCode, normalizeError } from "./lib/errors.js";
 export { branchToIssueId, currentIssueId } from "./git.js";

package/src/lib/introspect.ts

@@ -123,6 +123,7 @@ const GLOBAL_LONGS = new Set([
   "--json",
   "--no-ansi",
   "--api-key",
+  "--access-token",
   "--workspace",
   "--team",
   "--limit",

package/src/lib/options.ts

@@ -263,6 +263,7 @@ function globalOptions(): Option[] {
     // spellings cannot drift apart.
     new NoFlagOption("--no-color", "alias of --no-ansi", "noAnsi").hideHelp(),
     new Option("--api-key <key>", "Linear API key (overrides env/config)"),
+    new Option("--access-token <token>", "Linear OAuth access token (overrides env/config)"),
     new Option("--workspace <slug>", "select workspace credential profile"),
     new Option("-t, --team <key>", "default team key (e.g. TES)"),
     new Option("-n, --limit <n>", "max results (positive integer; 0 = all)").argParser(

package/src/lib/output-shapes.ts

@@ -160,6 +160,8 @@ const SETTING_ORIGINS_SHAPE = shape<SettingOrigins>({
 const CONFIG_SHOW_SHAPE: ObjectFields = {
   apiKey: "string",
   apiKeySource: "string",
+  accessToken: "string",
+  accessTokenSource: "string",
   credentialWorkspace: "string|null",
   team: "string|null",
   workspace: "string|null",
@@ -262,22 +264,39 @@ export const OUTPUT_SHAPES: Record<string, OutputShape | null> = {
     path: "string",
   }),
   "auth default": receipt({ success: "boolean", default_workspace: "string", path: "string" }),
-  "auth list": list({ slug: "string", isDefault: "boolean", storage: "string" }),
+  "auth list": list({
+    slug: "string",
+    isDefault: "boolean",
+    credentialType: "string",
+    storage: "string",
+  }),
   "auth login": receipt({
     success: "boolean",
+    credentialType: "string",
     workspace: "string",
     user: { id: "string", name: "string", email: "string" },
     storage: "string",
+    "scopes?": ["string"],
+    "expiresAt?": "string",
     path: "string",
   }),
-  "auth logout": receipt({ success: "boolean", workspace: "string", removed: "boolean" }),
+  "auth logout": receipt({
+    success: "boolean",
+    workspace: "string",
+    removed: "boolean",
+    revocation: "string",
+    fallbackCredentialType: "string|null",
+  }),
   "auth migrate": receipt({ success: "boolean", migrated: ["string"], path: "string" }),
   "auth status": object({
     authenticated: "boolean",
+    credentialType: "string|null",
     source: "string",
     workspace: "string|null",
     key: "string",
     keyring: "string|null",
+    scopes: { nullable: ["string"] },
+    expiresAt: "string|null",
   }),
   "auth token": object({ apiKey: "string", workspace: "string|null" }),
   "auth whoami": WHOAMI,