@owlmeans/cli-auth 0.1.18-rc.1

package/build/lock.js

@@ -0,0 +1,49 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export const lockPathFor = (credentialsPath) => `${credentialsPath}.lock`;
+export const readLock = async (path) => {
+    try {
+        return JSON.parse(await readFile(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+};
+const isAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Become the one process driving this API URL's sign-in, or find out somebody else already is.
+ *
+ * Best-effort, not a mutual-exclusion guarantee: two processes racing this at the exact same
+ * instant can both conclude they are the owner, and each then drives its own independent device
+ * authorization. That costs an extra browser tab, never a corrupted file or a double-spent code —
+ * this is a convenience for the ordinary case (a person running two terminal tabs), not a
+ * correctness boundary.
+ */
+export const claimOrJoinLock = async (path, apiUrl, info) => {
+    const existing = await readLock(path);
+    if (existing != null && existing.apiUrl === apiUrl && existing.expiresAt > Date.now() && isAlive(existing.pid)) {
+        return { owner: false, info: existing };
+    }
+    const mine = { ...info, apiUrl, pid: process.pid, nonce: randomBytes(8).toString('hex') };
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify(mine), { mode: 0o600 });
+    return { owner: true, info: mine };
+};
+/** Clear the lock, but only the copy of it this process itself wrote — a stale read after
+ * somebody else has already reclaimed the same path must never delete THEIR lock instead. */
+export const releaseLock = async (path, nonce) => {
+    const existing = await readLock(path);
+    if (existing?.nonce === nonce) {
+        await unlink(path).catch(() => undefined);
+    }
+};
+//# sourceMappingURL=lock.js.map

package/build/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAuBnC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,eAAuB,EAAU,EAAE,CAAC,GAAG,eAAe,OAAO,CAAA;AAEzF,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAE,IAAY,EAAkC,EAAE;IAC7E,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAmB,CAAA;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAA;AAED,MAAM,OAAO,GAAG,CAAC,GAAW,EAAW,EAAE;IACvC,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QAEpB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,KAAK,EAClC,IAAY,EAAE,MAAc,EAAE,IAAsD,EACjC,EAAE;IACrD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAA;IACrC,IAAI,QAAQ,IAAI,IAAI,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,IAAI,QAAQ,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/G,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;IACzC,CAAC;IAED,MAAM,IAAI,GAAmB,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAA;IACzG,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IAC/C,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAA;IAE5D,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAA;AACpC,CAAC,CAAA;AAED;6FAC6F;AAC7F,MAAM,CAAC,MAAM,WAAW,GAAG,KAAK,EAAE,IAAY,EAAE,KAAa,EAAiB,EAAE;IAC9E,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAA;IACrC,IAAI,QAAQ,EAAE,KAAK,KAAK,KAAK,EAAE,CAAC;QAC9B,MAAM,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC3C,CAAC;AACH,CAAC,CAAA"}

package/build/open-browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Best-effort: open `url` in the person's default browser. `false` on any failure — a CLI whose
+ * whole job is print-a-URL-and-poll must still work over SSH, in a container, or on a platform
+ * this never learned to open a browser on, so a failure here is never fatal to the caller.
+ *
+ * Spawned detached and with every std stream ignored, because this process's stdout may be
+ * carrying a protocol (an MCP server's JSON-RPC stream) that nothing the opened program writes may
+ * ever reach.
+ */
+export declare const openBrowser: (url: string, env?: NodeJS.ProcessEnv) => boolean;
+//# sourceMappingURL=open-browser.d.ts.map

package/build/open-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-browser.d.ts","sourceRoot":"","sources":["../src/open-browser.ts"],"names":[],"mappings":"AAQA;;;;;;;;GAQG;AACH,eAAO,MAAM,WAAW,QAAS,MAAM,QAAO,MAAM,CAAC,UAAU,KAAiB,OAsB/E,CAAA"}

package/build/open-browser.js

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process';
+const COMMAND_BY_PLATFORM = {
+    darwin: 'open',
+    win32: 'start',
+    linux: 'xdg-open',
+};
+/**
+ * Best-effort: open `url` in the person's default browser. `false` on any failure — a CLI whose
+ * whole job is print-a-URL-and-poll must still work over SSH, in a container, or on a platform
+ * this never learned to open a browser on, so a failure here is never fatal to the caller.
+ *
+ * Spawned detached and with every std stream ignored, because this process's stdout may be
+ * carrying a protocol (an MCP server's JSON-RPC stream) that nothing the opened program writes may
+ * ever reach.
+ */
+export const openBrowser = (url, env = process.env) => {
+    const platform = process.platform;
+    const command = COMMAND_BY_PLATFORM[platform];
+    if (command == null)
+        return false;
+    // `BROWSER=none` is the convention other CLIs already honour; the dedicated variable is for
+    // automation (an end-to-end run drives the page itself and must not pop a window on a desktop).
+    if (env.OWLMEANS_NO_BROWSER === '1' || env.BROWSER === 'none')
+        return false;
+    // A Linux session with no display (SSH, a container) has nothing for `xdg-open` to talk to.
+    if (platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY)
+        return false;
+    try {
+        const child = platform === 'win32'
+            ? spawn('cmd', ['/c', 'start', '""', url], { detached: true, stdio: 'ignore', windowsHide: true })
+            : spawn(command, [url], { detached: true, stdio: 'ignore' });
+        child.on('error', () => undefined); // a listener is required or Node throws on the next tick
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+//# sourceMappingURL=open-browser.js.map

package/build/open-browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-browser.js","sourceRoot":"","sources":["../src/open-browser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAA;AAE1C,MAAM,mBAAmB,GAA2B;IAClD,MAAM,EAAE,MAAM;IACd,KAAK,EAAE,OAAO;IACd,KAAK,EAAE,UAAU;CAClB,CAAA;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAW,EAAE,GAAG,GAAsB,OAAO,CAAC,GAAG,EAAW,EAAE;IACxF,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAA;IACjC,MAAM,OAAO,GAAG,mBAAmB,CAAC,QAAQ,CAAC,CAAA;IAC7C,IAAI,OAAO,IAAI,IAAI;QAAE,OAAO,KAAK,CAAA;IACjC,4FAA4F;IAC5F,gGAAgG;IAChG,IAAI,GAAG,CAAC,mBAAmB,KAAK,GAAG,IAAI,GAAG,CAAC,OAAO,KAAK,MAAM;QAAE,OAAO,KAAK,CAAA;IAC3E,4FAA4F;IAC5F,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe;QAAE,OAAO,KAAK,CAAA;IAE9E,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,QAAQ,KAAK,OAAO;YAChC,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;YAClG,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,CAAA;QAE9D,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA,CAAC,yDAAyD;QAC5F,KAAK,CAAC,KAAK,EAAE,CAAA;QAEb,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@owlmeans/cli-auth",
+  "version": "0.1.18-rc.1",
+  "license": "MIT",
+  "description": "OAuth device-authorization sign-in for a command-line tool: a dotenv-style ~/.owlmeans credentials file (overridable, environment always wins), a cross-process sign-in lock so several invocations converge on one browser round trip, a browser opener, and a small credential holder a CLI wraps its API calls with.",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 2 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@owlmeans/error": "^0.1.18-rc.27",
+    "@owlmeans/oauth": "^0.1.18-rc.1"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/bun": "^1.4.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,12 @@
+/** Overrides where the credentials file lives. Unset means `~/.owlmeans`. */
+export const ENV_CREDENTIALS_FILE = 'OWLMEANS_CREDENTIALS'
+
+export const DEFAULT_CREDENTIALS_FILENAME = '.owlmeans'
+
+/** How long `require()` waits for a sign-in this call itself started before returning
+ * `SignInRequired` and letting the sign-in continue in the background. */
+export const DEFAULT_WAIT_MS = 20_000
+
+/** RFC 8628's own ceiling is whatever the server answered with; this is the poller's OWN patience
+ * before it gives up entirely, independent of `expires_in`. */
+export const MAX_SIGN_IN_WAIT_MS = 15 * 60 * 1000

package/src/env-file.ts

@@ -0,0 +1,123 @@
+import { randomBytes } from 'node:crypto'
+import { chmod, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { DEFAULT_CREDENTIALS_FILENAME, ENV_CREDENTIALS_FILE } from './consts.js'
+
+/**
+ * Where the credentials file lives: `OWLMEANS_CREDENTIALS`, or `~/.owlmeans`.
+ *
+ * A CLI that talks to more than one deployment (a staging environment, a self-hosted instance)
+ * points this at a different file per deployment — the file is never merged with another one, and
+ * a token it holds is meaningless anywhere but the API URL it was signed in against.
+ */
+export const resolveEnvFile = (env: NodeJS.ProcessEnv = process.env): string =>
+  env[ENV_CREDENTIALS_FILE] != null && env[ENV_CREDENTIALS_FILE] !== ''
+    ? env[ENV_CREDENTIALS_FILE]
+    : join(homedir(), DEFAULT_CREDENTIALS_FILENAME)
+
+/**
+ * Parse a dotenv-shaped body: `KEY=value`, an optional `export ` prefix, `#` comments, one level
+ * of quoting. Deliberately small — a dotenv library would add a dependency for a format this
+ * package itself writes, and this is the one shape it ever needs to read back.
+ */
+export const parseEnv = (content: string): Record<string, string> => {
+  const values: Record<string, string> = {}
+  for (const raw of content.split('\n')) {
+    const line = raw.trim()
+    if (line === '' || line.startsWith('#')) continue
+
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line)
+    if (match == null) continue
+
+    let value = match[2].trim()
+    if ((value.startsWith('"') && value.endsWith('"') && value.length > 1)
+      || (value.startsWith("'") && value.endsWith("'") && value.length > 1)) {
+      value = value.slice(1, -1)
+    }
+    values[match[1]] = value
+  }
+
+  return values
+}
+
+const readFileIfPresent = async (path: string): Promise<string> =>
+  await readFile(path, 'utf-8').catch(() => '')
+
+/**
+ * The credentials file's values alone, with no environment overlay — what a token is bound to.
+ */
+export const readCredentialsFile = async (env: NodeJS.ProcessEnv = process.env): Promise<Record<string, string>> =>
+  parseEnv(await readFileIfPresent(resolveEnvFile(env)))
+
+/**
+ * The file, with the process environment layered over it — environment wins, but an environment
+ * value that is the EMPTY STRING is treated as unset.
+ *
+ * The empty-string rule exists because a harness config commonly expands an unset shell variable
+ * to `''` (`${VIABLE_API_TOKEN:-}`), and a literal empty override must not shadow a real value the
+ * file holds — that would make "I have not set this" indistinguishable from "I am overriding this
+ * to nothing", and the file is always the more deliberate of the two.
+ */
+export const loadOwlmeansEnv = async (env: NodeJS.ProcessEnv = process.env): Promise<Record<string, string>> => {
+  const file = await readCredentialsFile(env)
+  const fromEnv: Record<string, string> = {}
+  Object.entries(env).forEach(([key, value]) => {
+    if (value != null && value !== '') fromEnv[key] = value
+  })
+
+  return { ...file, ...fromEnv }
+}
+
+/**
+ * Replace the named keys in the credentials file, keeping every other line — comments, a key this
+ * call did not touch, blank lines — exactly where they were.
+ *
+ * Written atomically (a temp file in the same directory, then a rename) so a process killed
+ * mid-write never leaves a half-written credentials file behind, and created with mode `0600`
+ * because this file can hold a live access token. An existing file that is readable by anyone but
+ * its owner is reported back rather than silently tightened — permissions someone else set on
+ * purpose are theirs to change.
+ */
+export const setEnvValues = async (
+  path: string, values: Record<string, string | undefined>
+): Promise<{ insecurePermissions: boolean }> => {
+  const existing = await readFileIfPresent(path)
+  const lines = existing === '' ? [] : existing.split('\n')
+  const claimed = new Set<string>()
+
+  const rewritten = lines.map(line => {
+    const trimmed = line.trim()
+    const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(trimmed)
+    if (match == null || !(match[1] in values)) return line
+
+    claimed.add(match[1])
+    const value = values[match[1]]
+
+    return value == null ? null : `${match[1]}=${value}`
+  }).filter((line): line is string => line != null)
+
+  Object.entries(values).forEach(([key, value]) => {
+    if (claimed.has(key) || value == null) return
+    rewritten.push(`${key}=${value}`)
+  })
+
+  const body = `${rewritten.join('\n').replace(/\n+$/, '')}\n`
+
+  await mkdir(dirname(path), { recursive: true })
+  const tmp = join(dirname(path), `.${DEFAULT_CREDENTIALS_FILENAME}.${randomBytes(6).toString('hex')}.tmp`)
+  await writeFile(tmp, body, { mode: 0o600 })
+  await rename(tmp, path)
+  await chmod(path, 0o600).catch(() => undefined)
+
+  let insecurePermissions = false
+  try {
+    const info = await stat(path)
+    insecurePermissions = (info.mode & 0o077) !== 0
+  } catch {
+    // Nothing to report if the stat itself fails right after a successful write — unusual enough
+    // that guessing at a permission problem would be noise.
+  }
+
+  return { insecurePermissions }
+}

package/src/holder.ts

@@ -0,0 +1,215 @@
+import { hostname, userInfo } from 'node:os'
+import {
+  discoverAuthorizationServer, OAuthAccessDenied, OAuthError, OAUTH_DEVICE_NAME_MAX,
+  pollDeviceToken, requestDeviceAuthorization, revokeToken, signInRequired, TokenRejected
+} from '@owlmeans/oauth'
+import type { AuthorizationServerMetadata, DeviceSignInOutcome } from '@owlmeans/oauth'
+import { DEFAULT_WAIT_MS } from './consts.js'
+import { readCredentialsFile, resolveEnvFile, setEnvValues } from './env-file.js'
+import { claimOrJoinLock, lockPathFor, readLock, releaseLock } from './lock.js'
+import type { SignInLockInfo } from './lock.js'
+import { openBrowser } from './open-browser.js'
+
+export interface CliCredentialsOptions {
+  /** The API origin this credential set is for, and the OAuth `resource` it is scoped to unless
+   * `resource` says otherwise. */
+  apiUrl: string
+  /** This CLI's OAuth `client_id` — a static one the authorization server declared, or an https
+   * Client ID Metadata Document URL. */
+  clientId: string
+  deviceName?: string
+  resource?: string
+  scope?: string
+  /** Which key in `~/.owlmeans` (and the environment) carries the token. */
+  tokenEnvKey: string
+  /** Which key records the URL a stored token belongs to. A file naming no URL at all is treated
+   * as belonging to whichever `apiUrl` is asked for — only an explicit MISMATCH refuses it. */
+  apiUrlEnvKey: string
+  env?: NodeJS.ProcessEnv
+  /** Best-effort progress — "open this URL and enter this code", "signed in", a failure. A host
+   * wires this to stderr, an MCP `notifications/message`, or nothing at all. */
+  onNotify?: (message: string) => void
+}
+
+export interface CliCredentials {
+  /** The token this call site should use right now: the environment, then the bound file value,
+   * or `null` when neither has one. */
+  token: () => Promise<string | null>
+  /** Ensure a usable token exists. Starts or joins a device sign-in when there is none, waits up
+   * to `waitMs` for it to be approved, and returns the token. The sign-in keeps running in the
+   * background past that wait — a later `require()` call picks up wherever it left off, rather
+   * than starting over. */
+  require: (waitMs?: number) => Promise<string>
+  /** A 401 happened while presenting `rejectedToken`. A token that came from the FILE is forgotten
+   * so the next `require()` signs in again; a token that came from the ENVIRONMENT is reported —
+   * silently trying another identity behind an operator's back is worse than failing loudly. */
+  invalidate: (rejectedToken: string) => Promise<void>
+  /** Revoke the current token at the server and remove it from the file. */
+  signOut: () => Promise<void>
+}
+
+
+const defaultDeviceName = (): string => {
+  let who = 'cli'
+  try {
+    who = userInfo().username
+  } catch {
+    // Some sandboxes have no passwd entry for the running uid; the hostname alone still helps.
+  }
+
+  return `${hostname()} · ${who}`.slice(0, OAUTH_DEVICE_NAME_MAX)
+}
+
+/** One in-flight sign-in per API URL, per process — a second `require()` call while the first is
+ * still waiting joins the SAME poll rather than requesting a second device code. */
+const inFlightByApiUrl = new Map<string, Promise<DeviceSignInOutcome>>()
+
+export const makeCliCredentials = (opts: CliCredentialsOptions): CliCredentials => {
+  const env = opts.env ?? process.env
+  const notify = (message: string): void => opts.onNotify?.(message)
+  const credentialsPath = resolveEnvFile(env)
+  const lockPath = lockPathFor(credentialsPath)
+
+  const token = async (): Promise<string | null> => {
+    const envValue = env[opts.tokenEnvKey]
+    if (envValue != null && envValue !== '') return envValue
+
+    const file = await readCredentialsFile(env)
+    const boundUrl = file[opts.apiUrlEnvKey]
+    if (boundUrl != null && boundUrl !== '' && boundUrl !== opts.apiUrl) return null
+
+    const fileToken = file[opts.tokenEnvKey]
+
+    return fileToken != null && fileToken !== '' ? fileToken : null
+  }
+
+  /** Start a fresh device authorization, or adopt another live process's own — either way, claim
+   * or join the lock BEFORE requesting one, so the decision and the request agree. */
+  const claimJoinOrStart = async (server: AuthorizationServerMetadata): Promise<{ owner: boolean, info: SignInLockInfo }> => {
+    const authorization = await requestDeviceAuthorization(server, {
+      client_id: opts.clientId, scope: opts.scope, resource: opts.resource ?? opts.apiUrl,
+      device_name: opts.deviceName ?? defaultDeviceName(),
+    })
+
+    return await claimOrJoinLock(lockPath, opts.apiUrl, {
+      verificationUri: authorization.verification_uri,
+      verificationUriComplete: authorization.verification_uri_complete,
+      userCode: authorization.user_code,
+      deviceCode: authorization.device_code,
+      interval: authorization.interval,
+      expiresAt: Date.now() + authorization.expires_in * 1000,
+    })
+  }
+
+  /**
+   * Synchronous on purpose, up to the point it records itself in `inFlightByApiUrl` — that is
+   * what makes two `require()` calls racing in the SAME process converge on one sign-in rather
+   * than each starting its own before either has had a chance to publish that it is working on
+   * it. (Cross-PROCESS concurrency is what the file lock inside `claimJoinOrStart` is for.)
+   */
+  const beginOrJoin = (): Promise<DeviceSignInOutcome> => {
+    const existing = inFlightByApiUrl.get(opts.apiUrl)
+    if (existing != null) return existing
+
+    const promise = (async (): Promise<DeviceSignInOutcome> => {
+      const server = await discoverAuthorizationServer(opts.apiUrl)
+      const claim = await claimJoinOrStart(server)
+
+      notify(
+        claim.info.userCode != null
+          ? `Sign in at ${claim.info.verificationUri} with code ${claim.info.userCode}`
+          : `Sign in at ${claim.info.verificationUri}`
+      )
+      // Only the owner opens a browser — a joining process's own (unused) device authorization is
+      // simply left to expire, since a second, un-displayed code would only teach the server's
+      // rate limiter that this client polls too eagerly.
+      if (claim.owner) {
+        openBrowser(claim.info.verificationUriComplete ?? claim.info.verificationUri)
+      }
+
+      try {
+        const outcome = await pollDeviceToken(server, {
+          clientId: opts.clientId, deviceCode: claim.info.deviceCode, interval: claim.info.interval,
+          expiresAt: claim.info.expiresAt,
+        })
+        if (outcome.status === 'authorized') {
+          await setEnvValues(credentialsPath, { [opts.tokenEnvKey]: outcome.token, [opts.apiUrlEnvKey]: opts.apiUrl })
+          notify('Signed in.')
+        }
+
+        return outcome
+      } finally {
+        inFlightByApiUrl.delete(opts.apiUrl)
+        if (claim.owner) await releaseLock(lockPath, claim.info.nonce)
+      }
+    })()
+    inFlightByApiUrl.set(opts.apiUrl, promise)
+
+    return promise
+  }
+
+  return {
+    token,
+
+    require: async (waitMs = DEFAULT_WAIT_MS): Promise<string> => {
+      const existing = await token()
+      if (existing != null) return existing
+
+      // Deliberately NOT awaited here — `beginOrJoin()` is the pending sign-in itself, and
+      // racing it (rather than awaiting it first) is what lets `require()` return control to
+      // its caller after `waitMs` while the sign-in keeps running toward its own resolution.
+      const pollPromise = beginOrJoin()
+      // The ceiling's timer is cleared once the race is decided: a pending timer keeps a process
+      // alive, and `viable-mcp login` (waiting up to 15 minutes) must exit the moment it is signed in.
+      let ceiling: ReturnType<typeof setTimeout> | undefined
+      const raced = await Promise.race([
+        pollPromise.then(outcome => ({ settled: true as const, outcome })),
+        new Promise<{ settled: false }>(resolve => {
+          ceiling = setTimeout(() => resolve({ settled: false }), waitMs)
+        }),
+      ]).finally(() => clearTimeout(ceiling))
+
+      if (!raced.settled) {
+        const lock = await readLock(lockPath)
+        throw signInRequired({
+          url: lock?.verificationUri ?? opts.apiUrl, code: lock?.userCode, expiresAt: lock?.expiresAt,
+        })
+      }
+
+      switch (raced.outcome.status) {
+        case 'authorized':
+          return raced.outcome.token
+        case 'denied':
+          throw new OAuthAccessDenied('sign-in')
+        case 'expired':
+          throw new OAuthError('sign-in:expired')
+        default:
+          throw new OAuthError('sign-in:aborted')
+      }
+    },
+
+    invalidate: async (rejectedToken: string): Promise<void> => {
+      const file = await readCredentialsFile(env)
+      if (file[opts.tokenEnvKey] === rejectedToken) {
+        await setEnvValues(credentialsPath, { [opts.tokenEnvKey]: undefined })
+        notify('The stored token was refused. Signing in again.')
+
+        return
+      }
+      if (env[opts.tokenEnvKey] === rejectedToken) {
+        throw new TokenRejected(opts.tokenEnvKey)
+      }
+    },
+
+    signOut: async (): Promise<void> => {
+      const current = await token()
+      if (current == null) return
+
+      const server = await discoverAuthorizationServer(opts.apiUrl).catch(() => null)
+      if (server != null) {
+        await revokeToken(server, { token: current, clientId: opts.clientId }).catch(() => undefined)
+      }
+      await setEnvValues(credentialsPath, { [opts.tokenEnvKey]: undefined })
+    },
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './consts.js'
+export * from './env-file.js'
+export * from './lock.js'
+export * from './open-browser.js'
+export * from './holder.js'

package/src/lock.ts

@@ -0,0 +1,77 @@
+import { randomBytes } from 'node:crypto'
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+/**
+ * What one process tells every other one about the sign-in it is driving — the browser URL and
+ * code so a SECOND process can show the same "waiting on…" state instead of opening a second
+ * browser tab for the same API URL.
+ */
+export interface SignInLockInfo {
+  pid: number
+  apiUrl: string
+  verificationUri: string
+  verificationUriComplete?: string
+  userCode?: string
+  /** The device flow's own secret — protected the same way the eventual access token is (mode
+   * `0600`, same directory as the credentials file), so a joining process can poll the SAME
+   * pending authorization instead of requesting a second one nobody will ever display. */
+  deviceCode: string
+  interval: number
+  expiresAt: number
+  /** Proves ownership at release time — a process only clears the lock it itself wrote. */
+  nonce: string
+}
+
+export const lockPathFor = (credentialsPath: string): string => `${credentialsPath}.lock`
+
+export const readLock = async (path: string): Promise<SignInLockInfo | null> => {
+  try {
+    return JSON.parse(await readFile(path, 'utf-8')) as SignInLockInfo
+  } catch {
+    return null
+  }
+}
+
+const isAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0)
+
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Become the one process driving this API URL's sign-in, or find out somebody else already is.
+ *
+ * Best-effort, not a mutual-exclusion guarantee: two processes racing this at the exact same
+ * instant can both conclude they are the owner, and each then drives its own independent device
+ * authorization. That costs an extra browser tab, never a corrupted file or a double-spent code —
+ * this is a convenience for the ordinary case (a person running two terminal tabs), not a
+ * correctness boundary.
+ */
+export const claimOrJoinLock = async (
+  path: string, apiUrl: string, info: Omit<SignInLockInfo, 'pid' | 'nonce' | 'apiUrl'>
+): Promise<{ owner: boolean, info: SignInLockInfo }> => {
+  const existing = await readLock(path)
+  if (existing != null && existing.apiUrl === apiUrl && existing.expiresAt > Date.now() && isAlive(existing.pid)) {
+    return { owner: false, info: existing }
+  }
+
+  const mine: SignInLockInfo = { ...info, apiUrl, pid: process.pid, nonce: randomBytes(8).toString('hex') }
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, JSON.stringify(mine), { mode: 0o600 })
+
+  return { owner: true, info: mine }
+}
+
+/** Clear the lock, but only the copy of it this process itself wrote — a stale read after
+ * somebody else has already reclaimed the same path must never delete THEIR lock instead. */
+export const releaseLock = async (path: string, nonce: string): Promise<void> => {
+  const existing = await readLock(path)
+  if (existing?.nonce === nonce) {
+    await unlink(path).catch(() => undefined)
+  }
+}

package/src/open-browser.ts

@@ -0,0 +1,40 @@
+import { spawn } from 'node:child_process'
+
+const COMMAND_BY_PLATFORM: Record<string, string> = {
+  darwin: 'open',
+  win32: 'start',
+  linux: 'xdg-open',
+}
+
+/**
+ * Best-effort: open `url` in the person's default browser. `false` on any failure — a CLI whose
+ * whole job is print-a-URL-and-poll must still work over SSH, in a container, or on a platform
+ * this never learned to open a browser on, so a failure here is never fatal to the caller.
+ *
+ * Spawned detached and with every std stream ignored, because this process's stdout may be
+ * carrying a protocol (an MCP server's JSON-RPC stream) that nothing the opened program writes may
+ * ever reach.
+ */
+export const openBrowser = (url: string, env: NodeJS.ProcessEnv = process.env): boolean => {
+  const platform = process.platform
+  const command = COMMAND_BY_PLATFORM[platform]
+  if (command == null) return false
+  // `BROWSER=none` is the convention other CLIs already honour; the dedicated variable is for
+  // automation (an end-to-end run drives the page itself and must not pop a window on a desktop).
+  if (env.OWLMEANS_NO_BROWSER === '1' || env.BROWSER === 'none') return false
+  // A Linux session with no display (SSH, a container) has nothing for `xdg-open` to talk to.
+  if (platform === 'linux' && !env.DISPLAY && !env.WAYLAND_DISPLAY) return false
+
+  try {
+    const child = platform === 'win32'
+      ? spawn('cmd', ['/c', 'start', '""', url], { detached: true, stdio: 'ignore', windowsHide: true })
+      : spawn(command, [url], { detached: true, stdio: 'ignore' })
+
+    child.on('error', () => undefined) // a listener is required or Node throws on the next tick
+    child.unref()
+
+    return true
+  } catch {
+    return false
+  }
+}