@owlmeans/cli-auth 0.1.18-rc.1

package/README.md

@@ -0,0 +1,15 @@
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded agent skills under `agent-meta/`. After installing your
+`@owlmeans/*` packages, run the OwlMeans agent-skills installer to place them into
+your project's skill store (`.agents/skills/`):
+
+```sh
+npx @owlmeans/agent-skills@^0.1.18-rc.28
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/manifest.json

@@ -0,0 +1,16 @@
+{
+  "schemaVersion": 2,
+  "package": "@owlmeans/cli-auth",
+  "version": "0.1.18-rc.1",
+  "generatedAt": "2026-09-18T17:54:11.948Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "cli-auth",
+      "category": "package-specific",
+      "file": "skills/cli-auth/SKILL.md",
+      "canonicalPath": ".agents/skills/cli-auth/SKILL.md"
+    }
+  ]
+}

package/agent-meta/skills/cli-auth/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: cli-auth
+description: How to use @owlmeans/cli-auth — Node-side browser sign-in for a command-line tool or stdio MCP server: the `~/.owlmeans` dotenv credentials file and its precedence, atomic 0600 writes, the browser opener and its suppression, the cross-process sign-in lock, and makeCliCredentials (token/require/invalidate/signOut) that runs the device grant. Auto-invoked when adding sign-in to a CLI, reading or writing the credentials file, diagnosing "signed in but the token is ignored", or writing tests that must not touch the developer's real credentials.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/cli-auth
+
+**Layer:** Tooling (Node/Bun — no React, no DOM, no framework runtime)
+**Install:** `"@owlmeans/cli-auth": "^0.1.18-rc.1"` in `dependencies`
+**Contracts:** `@owlmeans/oauth` (discovery, device authorization, polling, revoke, `SignInRequired`)
+**Server half:** any API built on `@owlmeans/server-oauth`; **consumers:** `@owlmeans/viable-mcp`
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `makeCliCredentials(opts)` | The holder: `token()` · `require(waitMs?)` · `invalidate(rejected)` · `signOut()` |
+| `resolveEnvFile(env?)` | `OWLMEANS_CREDENTIALS`, else `~/.owlmeans` |
+| `parseEnv(content)` | `KEY=value`, optional `export `, `#` comments, one level of quotes |
+| `readCredentialsFile(env?)` | The file's values alone — what a token is *bound* to |
+| `loadOwlmeansEnv(env?)` | File overlaid by the process environment (below) |
+| `setEnvValues(path, values)` | Replace named keys, keep every other line; atomic, `0600`; returns `{ insecurePermissions }` |
+| `openBrowser(url, env?)` | Best-effort detached opener; `false` on any refusal |
+| `claimOrJoinLock` · `readLock` · `releaseLock` · `lockPathFor` · `SignInLockInfo` | The sign-in lock |
+| `ENV_CREDENTIALS_FILE` · `DEFAULT_CREDENTIALS_FILENAME` · `DEFAULT_WAIT_MS` (20 s) · `MAX_SIGN_IN_WAIT_MS` (15 min) | Constants |
+
+`CliCredentialsOptions`: `apiUrl`, `clientId` (a static client the server declared, or a CIMD URL),
+`tokenEnvKey`, `apiUrlEnvKey` (both required — the package is not tied to one product's key
+names), `deviceName?` (defaults to `host · user`), `resource?` (defaults to `apiUrl`), `scope?`,
+`env?` (defaults to `process.env`), `onNotify?`.
+
+## The credentials file
+
+Dotenv-style `KEY=VALUE`, e.g. `VIABLE_API_URL=…` and `VIABLE_API_TOKEN=…`. Never merged with another
+file; a CLI that serves several deployments points `OWLMEANS_CREDENTIALS` at one file each.
+
+- **The environment wins over the file** (`loadOwlmeansEnv` → `{ ...file, ...envWithoutEmpty }`).
+- **An empty environment value counts as unset.** A harness config that expands an unset variable
+  (`${VIABLE_API_TOKEN:-}`) produces `''`, which must not shadow the file — "I did not set it" and
+  "set it to nothing" are not the same, and the file is the more deliberate of the two.
+- **A token belongs to the file's API URL.** `token()` refuses a file token when the file names a
+  different `apiUrlEnvKey` value than the one asked for; a file that names none belongs to whichever
+  URL is asked for. A token is never sent to another API.
+- **Writes are atomic and private:** temp file in the same directory, `rename`, mode `0600`, other
+  lines and comments preserved. Loose permissions on an existing file are *reported*
+  (`insecurePermissions`), not silently tightened — someone may have set them on purpose.
+- The token is never read from argv, never written to a harness/config file.
+
+## The holder
+
+- **`token()`** — the environment value, else the bound file value, else `null`.
+- **`require(waitMs = DEFAULT_WAIT_MS)`** — returns a token, starting or joining ONE device sign-in
+  per API URL: discover → `requestDeviceAuthorization` → claim/join the lock → `notify("Sign in at
+  <url> with code <code>")` → open the browser (owner only) → `pollDeviceToken` → persist
+  `{tokenEnvKey, apiUrlEnvKey}` → resolve. If `waitMs` runs out first it throws `signInRequired`
+  (`url`, `code`, `expiresAt` from the lock) and **polling continues in the background**; the next
+  `require()` joins it instead of starting over. `denied`/`expired`/`aborted` become
+  `OAuthAccessDenied` / `OAuthError`.
+- **The `waitMs` ceiling is a timer that is cleared** when the race is decided. A pending timer keeps
+  a Node process alive, so an uncleared one made `viable-mcp login` (ceiling 15 minutes) hang after
+  it had signed in. Any new timeout in this package clears its timer the same way.
+- **Single-flight in-process:** `beginOrJoin` is synchronous up to the module-level
+  `inFlightByApiUrl` map insert, so two racing `require()` calls converge. An `await` before that
+  insert reopens the race (a `Promise<Promise<…>>` there once made `require()` hang forever).
+- **Single-flight across processes:** `<credentials file>.lock` (mode `0600`) records `pid`,
+  `apiUrl`, `verificationUri`, `userCode`, `deviceCode`, `interval`, `expiresAt` and a `nonce`. A live
+  lock for the same URL (unexpired, pid alive) makes a second process a **joiner** — it shows the same
+  code, does not open a second tab, and polls the same authorization. `releaseLock` deletes only a
+  lock carrying the caller's own `nonce`. Best effort, not mutual exclusion: two processes racing the
+  same instant may each drive a sign-in, costing a tab, never a corrupt file.
+- **`invalidate(rejected)`** — call on a 401. A file token that is still the rejected one is removed
+  (next `require()` signs in); an **environment** token is never silently replaced — it throws
+  `TokenRejected(tokenEnvKey)` so the operator hears "VIABLE_API_TOKEN was refused" instead of the
+  tool quietly becoming another identity.
+- **`signOut()`** — best-effort `revokeToken` at the server, then remove the file token.
+
+## Opening the browser
+
+`openBrowser` spawns `open` / `xdg-open` / `cmd /c start` **detached with `stdio: 'ignore'`**, because
+stdout may carry a protocol (an MCP server's JSON-RPC) that nothing the opened program writes may
+reach. It refuses (returns `false`) when `OWLMEANS_NO_BROWSER=1` or `BROWSER=none`, and on Linux
+with neither `DISPLAY` nor `WAYLAND_DISPLAY`. Automation and end-to-end runs set
+`OWLMEANS_NO_BROWSER=1` and open the printed URL themselves. A failed open is never fatal — the
+"sign in at … with code …" line is the real interface and works over SSH and in containers.
+
+## Testing
+
+Category A: `bun test ./tests` (`env-file`, `holder`, `lock`, `open-browser` specs). Rules that keep
+the suite off the developer's machine:
+
+- Point `OWLMEANS_CREDENTIALS` at a temp path — never let a test read the real `~/.owlmeans`.
+- Holder tests use a **distinct `apiUrl` per test**: `inFlightByApiUrl` is module-level, so a shared
+  URL leaks a pending sign-in from one test into the next.
+- `holder.spec.ts` replaces `globalThis.fetch` with a fake device-flow server (metadata,
+  `device_authorization` with `interval: 0.001`, a token endpoint that stays `authorization_pending`
+  for N polls, revoke) and restores it in `afterEach`; never wait out a real 5 s interval.
+- Anything that spawns a CLI passes `OWLMEANS_NO_BROWSER=1` and deletes the token and any URL
+  override variables from the inherited environment.

package/build/consts.d.ts

@@ -0,0 +1,10 @@
+/** Overrides where the credentials file lives. Unset means `~/.owlmeans`. */
+export declare const ENV_CREDENTIALS_FILE = "OWLMEANS_CREDENTIALS";
+export declare 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 declare const DEFAULT_WAIT_MS = 20000;
+/** 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 declare const MAX_SIGN_IN_WAIT_MS: number;
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,yBAAyB,CAAA;AAE1D,eAAO,MAAM,4BAA4B,cAAc,CAAA;AAEvD;0EAC0E;AAC1E,eAAO,MAAM,eAAe,QAAS,CAAA;AAErC;+DAC+D;AAC/D,eAAO,MAAM,mBAAmB,QAAiB,CAAA"}

package/build/consts.js

@@ -0,0 +1,10 @@
+/** 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;
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,MAAM,CAAC,MAAM,oBAAoB,GAAG,sBAAsB,CAAA;AAE1D,MAAM,CAAC,MAAM,4BAA4B,GAAG,WAAW,CAAA;AAEvD;0EAC0E;AAC1E,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAA;AAErC;+DAC+D;AAC/D,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA"}

package/build/env-file.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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 declare const resolveEnvFile: (env?: NodeJS.ProcessEnv) => string;
+/**
+ * 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 declare const parseEnv: (content: string) => Record<string, string>;
+/**
+ * The credentials file's values alone, with no environment overlay — what a token is bound to.
+ */
+export declare const readCredentialsFile: (env?: NodeJS.ProcessEnv) => Promise<Record<string, string>>;
+/**
+ * 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 declare const loadOwlmeansEnv: (env?: NodeJS.ProcessEnv) => Promise<Record<string, string>>;
+/**
+ * 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 declare const setEnvValues: (path: string, values: Record<string, string | undefined>) => Promise<{
+    insecurePermissions: boolean;
+}>;
+//# sourceMappingURL=env-file.d.ts.map

package/build/env-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-file.d.ts","sourceRoot":"","sources":["../src/env-file.ts"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,SAAS,MAAM,CAAC,UAAU,KAAiB,MAGnB,CAAA;AAEnD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,YAAa,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAkB/D,CAAA;AAKD;;GAEG;AACH,eAAO,MAAM,mBAAmB,SAAe,MAAM,CAAC,UAAU,KAAiB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CACvD,CAAA;AAExD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,SAAe,MAAM,CAAC,UAAU,KAAiB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQ1G,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,SACjB,MAAM,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KACvD,OAAO,CAAC;IAAE,mBAAmB,EAAE,OAAO,CAAA;CAAE,CAuC1C,CAAA"}

package/build/env-file.js

@@ -0,0 +1,107 @@
+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 = process.env) => 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) => {
+    const values = {};
+    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) => 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 = process.env) => 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 = process.env) => {
+    const file = await readCredentialsFile(env);
+    const fromEnv = {};
+    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, values) => {
+    const existing = await readFileIfPresent(path);
+    const lines = existing === '' ? [] : existing.split('\n');
+    const claimed = new Set();
+    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 != 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 };
+};
+//# sourceMappingURL=env-file.js.map

package/build/env-file.js.map

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

package/build/holder.d.ts

@@ -0,0 +1,38 @@
+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>;
+}
+export declare const makeCliCredentials: (opts: CliCredentialsOptions) => CliCredentials;
+//# sourceMappingURL=holder.d.ts.map

package/build/holder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"holder.d.ts","sourceRoot":"","sources":["../src/holder.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,qBAAqB;IACpC;oCACgC;IAChC,MAAM,EAAE,MAAM,CAAA;IACd;0CACsC;IACtC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAA;IACnB;iGAC6F;IAC7F,YAAY,EAAE,MAAM,CAAA;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB;kFAC8E;IAC9E,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B;yCACqC;IACrC,KAAK,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACnC;;;6BAGyB;IACzB,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC7C;;kGAE8F;IAC9F,UAAU,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpD,0EAA0E;IAC1E,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAC7B;AAkBD,eAAO,MAAM,kBAAkB,SAAU,qBAAqB,KAAG,cAoJhE,CAAA"}

package/build/holder.js

@@ -0,0 +1,153 @@
+import { hostname, userInfo } from 'node:os';
+import { discoverAuthorizationServer, OAuthAccessDenied, OAuthError, OAUTH_DEVICE_NAME_MAX, pollDeviceToken, requestDeviceAuthorization, revokeToken, signInRequired, TokenRejected } 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 { openBrowser } from './open-browser.js';
+const defaultDeviceName = () => {
+    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();
+export const makeCliCredentials = (opts) => {
+    const env = opts.env ?? process.env;
+    const notify = (message) => opts.onNotify?.(message);
+    const credentialsPath = resolveEnvFile(env);
+    const lockPath = lockPathFor(credentialsPath);
+    const token = async () => {
+        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) => {
+        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 = () => {
+        const existing = inFlightByApiUrl.get(opts.apiUrl);
+        if (existing != null)
+            return existing;
+        const promise = (async () => {
+            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) => {
+            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;
+            const raced = await Promise.race([
+                pollPromise.then(outcome => ({ settled: true, outcome })),
+                new Promise(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) => {
+            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 () => {
+            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 });
+        },
+    };
+};
+//# sourceMappingURL=holder.js.map

package/build/holder.js.map

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

package/build/index.d.ts

@@ -0,0 +1,6 @@
+export * from './consts.js';
+export * from './env-file.js';
+export * from './lock.js';
+export * from './open-browser.js';
+export * from './holder.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -0,0 +1,6 @@
+export * from './consts.js';
+export * from './env-file.js';
+export * from './lock.js';
+export * from './open-browser.js';
+export * from './holder.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,WAAW,CAAA;AACzB,cAAc,mBAAmB,CAAA;AACjC,cAAc,aAAa,CAAA"}

package/build/lock.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 declare const lockPathFor: (credentialsPath: string) => string;
+export declare const readLock: (path: string) => Promise<SignInLockInfo | null>;
+/**
+ * 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 declare const claimOrJoinLock: (path: string, apiUrl: string, info: Omit<SignInLockInfo, 'pid' | 'nonce' | 'apiUrl'>) => Promise<{
+    owner: boolean;
+    info: SignInLockInfo;
+}>;
+/** 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 declare const releaseLock: (path: string, nonce: string) => Promise<void>;
+//# sourceMappingURL=lock.d.ts.map

package/build/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../src/lock.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,eAAe,EAAE,MAAM,CAAA;IACvB,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;4FAEwF;IACxF,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,yFAAyF;IACzF,KAAK,EAAE,MAAM,CAAA;CACd;AAED,eAAO,MAAM,WAAW,oBAAqB,MAAM,KAAG,MAAmC,CAAA;AAEzF,eAAO,MAAM,QAAQ,SAAgB,MAAM,KAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAM1E,CAAA;AAYD;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,SACpB,MAAM,UAAU,MAAM,QAAQ,IAAI,CAAC,cAAc,EAAE,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC,KACnF,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,CAWlD,CAAA;AAED;6FAC6F;AAC7F,eAAO,MAAM,WAAW,SAAgB,MAAM,SAAS,MAAM,KAAG,OAAO,CAAC,IAAI,CAK3E,CAAA"}