@moxxy/plugin-oauth 0.0.33

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Moxxy (moxxy.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapters/openai-device-flow.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Device-authorization adapter for OpenAI's non-standard flow (used by
+ * Codex/ChatGPT, opencode, codex-rs). Not RFC 8628 — speaks a JSON dialect:
+ *
+ *   1. POST `${issuer}/api/accounts/deviceauth/usercode` JSON `{client_id}`
+ *      → `{device_auth_id, user_code, interval}`.
+ *   2. Surface `user_code` + a product-specific verification URI
+ *      (`verificationUri`) to the user.
+ *   3. Poll `${issuer}/api/accounts/deviceauth/token` JSON
+ *      `{device_auth_id, user_code}`. 403/404 ⇒ keep polling. 200 returns
+ *      `{authorization_code, code_verifier}`.
+ *   4. Exchange that `authorization_code` + `code_verifier` for real tokens
+ *      via the standard `/oauth/token` endpoint with
+ *      `redirect_uri=${issuer}/deviceauth/callback` (not an actual redirect
+ *      target — just a registered value the server expects to see).
+ *
+ * Reusable for any OpenAI-issued client; product-specific bits are the
+ * verification URI and the `client_id`.
+ */
+import type { DeviceFlowAdapter } from '../profile.js';
+export interface OpenaiDeviceFlowOpts {
+    /** Auth issuer base URL, e.g. `https://auth.openai.com`. */
+    readonly issuer: string;
+    /** Standard OAuth token endpoint — `parseTokenResponse` consumes its reply. */
+    readonly tokenUrl: string;
+    /**
+     * URL the user opens to enter the device code. Product-specific —
+     * Codex uses `${issuer}/codex/device`. The init endpoint does NOT
+     * return one, so the caller supplies it.
+     */
+    readonly verificationUri: string;
+}
+export declare function openaiDeviceFlow(opts: OpenaiDeviceFlowOpts): DeviceFlowAdapter;
+//# sourceMappingURL=openai-device-flow.d.ts.map

package/dist/adapters/openai-device-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-device-flow.d.ts","sourceRoot":"","sources":["../../src/adapters/openai-device-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAQD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,iBAAiB,CAiI9E"}

package/dist/adapters/openai-device-flow.js

@@ -0,0 +1,136 @@
+/**
+ * Device-authorization adapter for OpenAI's non-standard flow (used by
+ * Codex/ChatGPT, opencode, codex-rs). Not RFC 8628 — speaks a JSON dialect:
+ *
+ *   1. POST `${issuer}/api/accounts/deviceauth/usercode` JSON `{client_id}`
+ *      → `{device_auth_id, user_code, interval}`.
+ *   2. Surface `user_code` + a product-specific verification URI
+ *      (`verificationUri`) to the user.
+ *   3. Poll `${issuer}/api/accounts/deviceauth/token` JSON
+ *      `{device_auth_id, user_code}`. 403/404 ⇒ keep polling. 200 returns
+ *      `{authorization_code, code_verifier}`.
+ *   4. Exchange that `authorization_code` + `code_verifier` for real tokens
+ *      via the standard `/oauth/token` endpoint with
+ *      `redirect_uri=${issuer}/deviceauth/callback` (not an actual redirect
+ *      target — just a registered value the server expects to see).
+ *
+ * Reusable for any OpenAI-issued client; product-specific bits are the
+ * verification URI and the `client_id`.
+ */
+import { classifyHttpStatus, MoxxyError } from '@moxxy/sdk';
+import { exchangeCodeForToken } from '../oauth/token-exchange.js';
+export function openaiDeviceFlow(opts) {
+    const initUrl = `${opts.issuer}/api/accounts/deviceauth/usercode`;
+    const pollUrl = `${opts.issuer}/api/accounts/deviceauth/token`;
+    const exchangeRedirectUri = `${opts.issuer}/deviceauth/callback`;
+    return {
+        async start(args) {
+            const res = await fetch(initUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ client_id: args.clientId }),
+                ...(args.signal ? { signal: args.signal } : {}),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw (classifyHttpStatus(res.status, { url: initUrl, body: text || res.statusText }) ??
+                    new MoxxyError({
+                        code: 'AUTH_INVALID',
+                        message: `device auth init failed: ${res.status} ${text || res.statusText}`,
+                        context: { status: res.status, url: initUrl },
+                    }));
+            }
+            const data = (await res.json().catch(() => {
+                throw new MoxxyError({
+                    code: 'PROVIDER_UNKNOWN_RESPONSE',
+                    message: 'device-auth init returned a non-JSON success body',
+                    context: { url: initUrl },
+                });
+            }));
+            // Required-field validation: a 200 missing device_auth_id/user_code would
+            // otherwise produce a poll body of `{ device_auth_id: undefined }` that
+            // 403s forever until timeout. Reject clearly instead.
+            if (typeof data.device_auth_id !== 'string' || typeof data.user_code !== 'string') {
+                throw new MoxxyError({
+                    code: 'PROVIDER_UNKNOWN_RESPONSE',
+                    message: 'device-auth init response missing device_auth_id or user_code',
+                    context: { url: initUrl },
+                });
+            }
+            // Coerce-then-validate: a malformed server value (e.g. interval:"" or a
+            // non-numeric string) parses to NaN, which would poison the poll timing
+            // (`setTimeout(_, NaN)` busy-loops; a NaN deadline aborts the flow). Only
+            // accept a finite number; otherwise fall back to the RFC-style defaults.
+            const rawInterval = typeof data.interval === 'string' ? parseInt(data.interval, 10) : data.interval;
+            const intervalSec = Math.max(Number.isFinite(rawInterval) ? rawInterval : 5, 1);
+            const rawExpiresIn = typeof data.expires_in === 'string' ? parseInt(data.expires_in, 10) : data.expires_in;
+            const expiresInSec = Number.isFinite(rawExpiresIn) ? rawExpiresIn : 600;
+            return {
+                userCode: data.user_code,
+                verificationUri: opts.verificationUri,
+                intervalMs: intervalSec * 1000,
+                expiresInMs: expiresInSec * 1000,
+                providerData: {
+                    deviceAuthId: data.device_auth_id,
+                    userCode: data.user_code,
+                    clientId: args.clientId,
+                },
+            };
+        },
+        async poll(init, state) {
+            const { deviceAuthId, userCode, clientId } = init.providerData;
+            const res = await fetch(pollUrl, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ device_auth_id: deviceAuthId, user_code: userCode }),
+                ...(state.signal ? { signal: state.signal } : {}),
+            });
+            if (res.ok) {
+                const data = (await res.json().catch(() => {
+                    throw new MoxxyError({
+                        code: 'PROVIDER_UNKNOWN_RESPONSE',
+                        message: 'device-auth poll returned a non-JSON success body',
+                        context: { url: pollUrl },
+                    });
+                }));
+                // Required-field validation: without it a 200 omitting these would call
+                // exchangeCodeForToken with undefined, which URLSearchParams coerces to
+                // the literal 'undefined' — a wasted exchange that fails opaquely.
+                if (typeof data.authorization_code !== 'string' || typeof data.code_verifier !== 'string') {
+                    throw new MoxxyError({
+                        code: 'PROVIDER_UNKNOWN_RESPONSE',
+                        message: 'device-auth poll response missing authorization_code or code_verifier',
+                        context: { url: pollUrl },
+                    });
+                }
+                // Two-step: poll returns a server-side authorization_code we
+                // exchange via the standard token endpoint. The redirect_uri
+                // here is the issuer's device callback — a registered value,
+                // not a URI we listen on. Route through the shared exchange
+                // helper so this dialect can't drift from browser-flow.
+                return {
+                    done: await exchangeCodeForToken({
+                        tokenUrl: opts.tokenUrl,
+                        code: data.authorization_code,
+                        redirectUri: exchangeRedirectUri,
+                        clientId,
+                        codeVerifier: data.code_verifier,
+                        ...(state.signal ? { signal: state.signal } : {}),
+                    }),
+                };
+            }
+            // OpenAI's "still waiting" signal — 403 or 404 with no further detail.
+            if (res.status === 403 || res.status === 404) {
+                return { pending: true };
+            }
+            const text = await res.text().catch(() => '');
+            throw (classifyHttpStatus(res.status, { url: pollUrl, body: text || res.statusText }) ??
+                new MoxxyError({
+                    code: 'AUTH_INVALID',
+                    message: `Device auth poll failed: ${res.status} ${text || res.statusText}`,
+                    context: { status: res.status, url: pollUrl },
+                }));
+        },
+    };
+}
+//# sourceMappingURL=openai-device-flow.js.map

package/dist/adapters/openai-device-flow.js.map

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

package/dist/adapters/rfc8628-device-flow.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Standards-compliant device-authorization adapter per RFC 8628.
+ *
+ * Phases:
+ *   1. POST `client_id` + `scope` to `deviceUrl` (form-encoded).
+ *   2. Surface `user_code` + `verification_uri` to the user.
+ *   3. Poll `tokenUrl` every `interval` with
+ *      `grant_type=urn:ietf:params:oauth:grant-type:device_code` + `device_code`.
+ *   4. Handle `authorization_pending` / `slow_down` / fatal codes per spec.
+ *
+ * The device-authorization request + poll-response classification are shared
+ * with the legacy `runDeviceCodeFlow` via `oauth/device-flow-shared`.
+ */
+import type { DeviceFlowAdapter } from '../profile.js';
+export interface Rfc8628AdapterOpts {
+    readonly deviceUrl: string;
+    readonly tokenUrl: string;
+}
+export declare function rfc8628DeviceFlow(opts: Rfc8628AdapterOpts): DeviceFlowAdapter;
+//# sourceMappingURL=rfc8628-device-flow.d.ts.map

package/dist/adapters/rfc8628-device-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rfc8628-device-flow.d.ts","sourceRoot":"","sources":["../../src/adapters/rfc8628-device-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAMD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,iBAAiB,CAuC7E"}

package/dist/adapters/rfc8628-device-flow.js

@@ -0,0 +1,54 @@
+/**
+ * Standards-compliant device-authorization adapter per RFC 8628.
+ *
+ * Phases:
+ *   1. POST `client_id` + `scope` to `deviceUrl` (form-encoded).
+ *   2. Surface `user_code` + `verification_uri` to the user.
+ *   3. Poll `tokenUrl` every `interval` with
+ *      `grant_type=urn:ietf:params:oauth:grant-type:device_code` + `device_code`.
+ *   4. Handle `authorization_pending` / `slow_down` / fatal codes per spec.
+ *
+ * The device-authorization request + poll-response classification are shared
+ * with the legacy `runDeviceCodeFlow` via `oauth/device-flow-shared`.
+ */
+import { classifyDeviceTokenResponse, requestDeviceAuthorization, } from '../oauth/device-flow-shared.js';
+export function rfc8628DeviceFlow(opts) {
+    return {
+        async start(args) {
+            const auth = await requestDeviceAuthorization({
+                deviceUrl: opts.deviceUrl,
+                clientId: args.clientId,
+                scopes: args.scopes,
+                ...(args.signal ? { signal: args.signal } : {}),
+            });
+            return {
+                userCode: auth.userCode,
+                verificationUri: auth.verificationUri,
+                ...(auth.verificationUriComplete
+                    ? { verificationUriComplete: auth.verificationUriComplete }
+                    : {}),
+                intervalMs: auth.intervalSec * 1000,
+                expiresInMs: auth.expiresInSec * 1000,
+                providerData: { deviceCode: auth.deviceCode },
+            };
+        },
+        async poll(init, state) {
+            const { deviceCode } = init.providerData;
+            const body = new URLSearchParams();
+            body.set('grant_type', 'urn:ietf:params:oauth:grant-type:device_code');
+            body.set('device_code', deviceCode);
+            const res = await fetch(opts.tokenUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Accept: 'application/json',
+                },
+                body: body.toString(),
+                ...(state.signal ? { signal: state.signal } : {}),
+            });
+            const json = (await res.json().catch(() => ({})));
+            return classifyDeviceTokenResponse(res, json, state);
+        },
+    };
+}
+//# sourceMappingURL=rfc8628-device-flow.js.map

package/dist/adapters/rfc8628-device-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rfc8628-device-flow.js","sourceRoot":"","sources":["../../src/adapters/rfc8628-device-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,gCAAgC,CAAC;AAkBxC,MAAM,UAAU,iBAAiB,CAAC,IAAwB;IACxD,OAAO;QACL,KAAK,CAAC,KAAK,CAAC,IAAyB;YACnC,MAAM,IAAI,GAAG,MAAM,0BAA0B,CAAC;gBAC5C,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAChD,CAAC,CAAC;YACH,OAAO;gBACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;gBACvB,eAAe,EAAE,IAAI,CAAC,eAAe;gBACrC,GAAG,CAAC,IAAI,CAAC,uBAAuB;oBAC9B,CAAC,CAAC,EAAE,uBAAuB,EAAE,IAAI,CAAC,uBAAuB,EAAE;oBAC3D,CAAC,CAAC,EAAE,CAAC;gBACP,UAAU,EAAE,IAAI,CAAC,WAAW,GAAG,IAAI;gBACnC,WAAW,EAAE,IAAI,CAAC,YAAY,GAAG,IAAI;gBACrC,YAAY,EAAE,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAyB;aACrE,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,IAAoB,EAAE,KAAgB;YAC/C,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC,YAA4B,CAAC;YACzD,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;YACnC,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,8CAA8C,CAAC,CAAC;YACvE,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;YACpC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE;gBACrC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE;oBACP,cAAc,EAAE,mCAAmC;oBACnD,MAAM,EAAE,kBAAkB;iBAC3B;gBACD,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE;gBACrB,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAClD,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAA4B,CAAC;YAC7E,OAAO,2BAA2B,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/credential-lock.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-credential refresh serialization.
+ *
+ * OAuth providers with ROTATING single-use refresh tokens (Anthropic's Claude
+ * subscription, OpenAI's Codex/ChatGPT plan) invalidate the previous
+ * refresh_token on every refresh. Two concurrent refreshes with the same
+ * stored token therefore race: one wins, the other burns a now-dead token and
+ * logs the user out. `withCredentialLock` serializes "refresh + persist"
+ * critical sections at two levels:
+ *
+ *   1. In-process: a per-key `Mutex` (promise chain) so concurrent consumers
+ *      in one process (e.g. the chat provider and the whisper-stt transcriber
+ *      sharing the codex credential) coalesce into a single refresh — the
+ *      followers re-read the vault under the lock and reuse the winner's
+ *      rotated tokens.
+ *   2. Cross-process: a best-effort O_EXCL lockfile under
+ *      `<moxxy home>/locks/` with stale-lock takeover, so a TUI and a desktop
+ *      runner refreshing the same credential queue up instead of racing.
+ *
+ * The file lock is deliberately best-effort: if the lock directory is
+ * unusable, or a live-but-slow holder keeps it past `waitMs`, we proceed
+ * WITHOUT the lock rather than deadlocking auth — the vault's read-merge-write
+ * persistence and the callers' invalid_grant re-read-retry recovery keep the
+ * losing side recoverable even then.
+ */
+export interface CredentialLockOptions {
+    /** Directory holding the lock files. Default `<moxxy home>/locks`. */
+    readonly dir?: string;
+    /**
+     * Take over a lock file whose mtime is older than this (holder crashed
+     * without releasing). Default 60s — comfortably above a worst-case retried
+     * token refresh.
+     */
+    readonly staleMs?: number;
+    /** Poll interval while waiting on a held lock. Default 150ms. */
+    readonly pollMs?: number;
+    /**
+     * Max time to wait for the file lock before proceeding WITHOUT it
+     * (best effort — never deadlock auth on a wedged lock). Default 30s.
+     */
+    readonly waitMs?: number;
+}
+/**
+ * Run `fn` while holding the per-credential lock (in-process mutex +
+ * best-effort cross-process lockfile). Callers should RE-READ their stored
+ * credential inside `fn` — a queued waiter usually finds the winner's
+ * freshly rotated tokens and can skip its own refresh entirely.
+ */
+export declare function withCredentialLock<T>(key: string, fn: () => Promise<T>, opts?: CredentialLockOptions): Promise<T>;
+/**
+ * True for deterministic credential rejections from a token endpoint, as
+ * opposed to transient network/5xx failures. Covers the AUTH_* codes (401/403
+ * and refresh-specific failures) plus PROVIDER_BAD_REQUEST — `invalid_grant`
+ * is canonically an HTTP 400 (RFC 6749 §5.2), which `classifyHttpStatus` maps
+ * there. Used to decide whether a failed refresh is worth retrying with a
+ * fresher refresh_token re-read from the vault (another process may have
+ * rotated ours away).
+ */
+export declare function isAuthRejection(err: unknown): boolean;
+//# sourceMappingURL=credential-lock.d.ts.map

package/dist/credential-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-lock.d.ts","sourceRoot":"","sources":["../src/credential-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAYD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EACxC,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,qBAA0B,GAC/B,OAAO,CAAC,CAAC,CAAC,CAoBZ;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAQrD"}

package/dist/credential-lock.js

@@ -0,0 +1,149 @@
+/**
+ * Per-credential refresh serialization.
+ *
+ * OAuth providers with ROTATING single-use refresh tokens (Anthropic's Claude
+ * subscription, OpenAI's Codex/ChatGPT plan) invalidate the previous
+ * refresh_token on every refresh. Two concurrent refreshes with the same
+ * stored token therefore race: one wins, the other burns a now-dead token and
+ * logs the user out. `withCredentialLock` serializes "refresh + persist"
+ * critical sections at two levels:
+ *
+ *   1. In-process: a per-key `Mutex` (promise chain) so concurrent consumers
+ *      in one process (e.g. the chat provider and the whisper-stt transcriber
+ *      sharing the codex credential) coalesce into a single refresh — the
+ *      followers re-read the vault under the lock and reuse the winner's
+ *      rotated tokens.
+ *   2. Cross-process: a best-effort O_EXCL lockfile under
+ *      `<moxxy home>/locks/` with stale-lock takeover, so a TUI and a desktop
+ *      runner refreshing the same credential queue up instead of racing.
+ *
+ * The file lock is deliberately best-effort: if the lock directory is
+ * unusable, or a live-but-slow holder keeps it past `waitMs`, we proceed
+ * WITHOUT the lock rather than deadlocking auth — the vault's read-merge-write
+ * persistence and the callers' invalid_grant re-read-retry recovery keep the
+ * losing side recoverable even then.
+ */
+import { mkdir, open, rename, rm, stat } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { MoxxyError, createMutex } from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+const DEFAULT_STALE_MS = 60_000;
+const DEFAULT_POLL_MS = 150;
+const DEFAULT_WAIT_MS = 30_000;
+/**
+ * In-process locks, keyed by sanitized credential key. Module-level so every
+ * consumer of this package instance (providers, stt, tools) shares them.
+ */
+const inProcessLocks = new Map();
+/**
+ * Run `fn` while holding the per-credential lock (in-process mutex +
+ * best-effort cross-process lockfile). Callers should RE-READ their stored
+ * credential inside `fn` — a queued waiter usually finds the winner's
+ * freshly rotated tokens and can skip its own refresh entirely.
+ */
+export async function withCredentialLock(key, fn, opts = {}) {
+    const safe = sanitizeKey(key);
+    let mutex = inProcessLocks.get(safe);
+    if (!mutex) {
+        mutex = createMutex();
+        inProcessLocks.set(safe, mutex);
+    }
+    return mutex.run(async () => {
+        const release = await acquireFileLock(join(opts.dir ?? moxxyPath('locks'), `${safe}.lock`), opts.staleMs ?? DEFAULT_STALE_MS, opts.pollMs ?? DEFAULT_POLL_MS, opts.waitMs ?? DEFAULT_WAIT_MS);
+        try {
+            return await fn();
+        }
+        finally {
+            await release();
+        }
+    });
+}
+/**
+ * True for deterministic credential rejections from a token endpoint, as
+ * opposed to transient network/5xx failures. Covers the AUTH_* codes (401/403
+ * and refresh-specific failures) plus PROVIDER_BAD_REQUEST — `invalid_grant`
+ * is canonically an HTTP 400 (RFC 6749 §5.2), which `classifyHttpStatus` maps
+ * there. Used to decide whether a failed refresh is worth retrying with a
+ * fresher refresh_token re-read from the vault (another process may have
+ * rotated ours away).
+ */
+export function isAuthRejection(err) {
+    return (err instanceof MoxxyError &&
+        (err.code === 'AUTH_INVALID' ||
+            err.code === 'AUTH_DENIED' ||
+            err.code === 'AUTH_EXPIRED' ||
+            err.code === 'PROVIDER_BAD_REQUEST'));
+}
+function sanitizeKey(key) {
+    return key.replace(/[^a-zA-Z0-9._-]+/g, '_');
+}
+/**
+ * O_EXCL ('wx') lockfile acquisition with stale takeover. Returns a release
+ * function. Never throws: an unusable lock dir degrades to running unlocked.
+ */
+async function acquireFileLock(lockPath, staleMs, pollMs, waitMs) {
+    const deadline = Date.now() + waitMs;
+    try {
+        await mkdir(dirname(lockPath), { recursive: true });
+    }
+    catch {
+        return async () => { };
+    }
+    for (;;) {
+        try {
+            const handle = await open(lockPath, 'wx');
+            try {
+                await handle.writeFile(`${process.pid} ${new Date().toISOString()}\n`, 'utf8');
+            }
+            finally {
+                await handle.close().catch(() => { });
+            }
+            return async () => {
+                await rm(lockPath, { force: true }).catch(() => { });
+            };
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST') {
+                // Read-only FS, permissions, … — degrade to unlocked rather than
+                // blocking the user's auth on infrastructure trouble.
+                return async () => { };
+            }
+        }
+        // Lock held — take over if the holder looks dead, else wait and re-try.
+        // Takeover is made atomic via rename() to dodge the rm()+open() TOCTOU: a
+        // naive rm() lets two processes both judge the same lock stale and both
+        // delete it, and one could unlink a holder's freshly-recreated lock. POSIX
+        // rename is atomic and single-winner — only one racer's rename of the SAME
+        // inode succeeds; the loser's rename fails (ENOENT/the file moved) and it
+        // spins to re-acquire instead of clobbering the winner. We rename to a
+        // unique temp then rm that temp, so the original path is freed for the
+        // winner's `open('wx')` on the next spin. The file lock stays best-effort
+        // (see the module header): any failure degrades to the unlocked-but-
+        // recoverable path guarded by the in-process mutex + invalid_grant retry.
+        try {
+            const st = await stat(lockPath);
+            if (Date.now() - st.mtimeMs > staleMs) {
+                const tmp = `${lockPath}.stale-${process.pid}-${randomBytes(6).toString('hex')}`;
+                try {
+                    await rename(lockPath, tmp);
+                }
+                catch {
+                    continue; // lost the takeover race (someone moved/recreated it) — respin
+                }
+                await rm(tmp, { force: true }).catch(() => { });
+                continue;
+            }
+        }
+        catch {
+            continue; // released between open() and stat() — grab it on the next spin
+        }
+        if (Date.now() >= deadline)
+            return async () => { };
+        await sleep(pollMs);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=credential-lock.js.map

package/dist/credential-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-lock.js","sourceRoot":"","sources":["../src/credential-lock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,WAAW,EAAc,MAAM,YAAY,CAAC;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAoB9C,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAChC,MAAM,eAAe,GAAG,GAAG,CAAC;AAC5B,MAAM,eAAe,GAAG,MAAM,CAAC;AAE/B;;;GAGG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,EAAiB,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,GAAW,EACX,EAAoB,EACpB,OAA8B,EAAE;IAEhC,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,KAAK,GAAG,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,KAAK,GAAG,WAAW,EAAE,CAAC;QACtB,cAAc,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE;QAC1B,MAAM,OAAO,GAAG,MAAM,eAAe,CACnC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,GAAG,IAAI,OAAO,CAAC,EACpD,IAAI,CAAC,OAAO,IAAI,gBAAgB,EAChC,IAAI,CAAC,MAAM,IAAI,eAAe,EAC9B,IAAI,CAAC,MAAM,IAAI,eAAe,CAC/B,CAAC;QACF,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;gBAAS,CAAC;YACT,MAAM,OAAO,EAAE,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,OAAO,CACL,GAAG,YAAY,UAAU;QACzB,CAAC,GAAG,CAAC,IAAI,KAAK,cAAc;YAC1B,GAAG,CAAC,IAAI,KAAK,aAAa;YAC1B,GAAG,CAAC,IAAI,KAAK,cAAc;YAC3B,GAAG,CAAC,IAAI,KAAK,sBAAsB,CAAC,CACvC,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,OAAO,GAAG,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,KAAK,UAAU,eAAe,CAC5B,QAAgB,EAChB,OAAe,EACf,MAAc,EACd,MAAc;IAEd,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;IACrC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;IACxB,CAAC;IACD,SAAS,CAAC;QACR,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC1C,IAAI,CAAC;gBACH,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;YACjF,CAAC;oBAAS,CAAC;gBACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACvC,CAAC;YACD,OAAO,KAAK,IAAI,EAAE;gBAChB,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;YACtD,CAAC,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrD,iEAAiE;gBACjE,sDAAsD;gBACtD,OAAO,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QACD,wEAAwE;QACxE,0EAA0E;QAC1E,wEAAwE;QACxE,2EAA2E;QAC3E,2EAA2E;QAC3E,0EAA0E;QAC1E,uEAAuE;QACvE,uEAAuE;QACvE,0EAA0E;QAC1E,qEAAqE;QACrE,0EAA0E;QAC1E,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;YAChC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,OAAO,GAAG,OAAO,EAAE,CAAC;gBACtC,MAAM,GAAG,GAAG,GAAG,QAAQ,UAAU,OAAO,CAAC,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;gBACjF,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;gBAC9B,CAAC;gBAAC,MAAM,CAAC;oBACP,SAAS,CAAC,+DAA+D;gBAC3E,CAAC;gBACD,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;gBAC/C,SAAS;YACX,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,gEAAgE;QAC5E,CAAC;QACD,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;YAAE,OAAO,KAAK,IAAI,EAAE,GAAE,CAAC,CAAC;QAClD,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC;AACH,CAAC;AAED,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/ensure-fresh.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Pre-request token freshness helper. Reads stored creds, refreshes when
+ * within `skewMs` of expiry (or forced), persists the rotated tokens BEFORE
+ * returning so a crash mid-flight can't strand a single-use refresh_token.
+ *
+ * The refresh + persist critical section runs under the per-credential lock
+ * (`withCredentialLock`): concurrent consumers — in this process or another
+ * moxxy process — coalesce into a single IdP refresh, with the followers
+ * re-reading the winner's rotated tokens from the vault instead of burning
+ * the (single-use, rotating) refresh_token a second time.
+ *
+ * Returns the live TokenSet + extras the provider can use to build headers
+ * (e.g. ChatGPT-Account-Id). Throws when no credential is stored or the
+ * refresh fails permanently.
+ */
+import { MoxxyError } from '@moxxy/sdk';
+import { type OAuthVault, type StoredCreds } from './storage.js';
+import type { TokenSet } from './oauth/types.js';
+import type { OAuthProviderProfile } from './profile.js';
+/**
+ * Single refresh-and-persist critical section shared by `ensureFreshTokens`
+ * (provider profiles) and `oauth_get_token` (raw stored creds). Encodes the
+ * security-critical sequence ONCE — refresh-token guard, rotation-race
+ * recovery, refresh_token preservation (RFC 6749 §6), atomic re-persist —
+ * and lets each caller plug in its own provider key, error wording, and
+ * extras handling via a {@link RefreshSpec}. MUST run inside
+ * `withCredentialLock`: it is a writer to the `oauth/<provider>/*` keys.
+ */
+export interface RefreshSpec {
+    /** Vault namespace + lock key for this credential. */
+    readonly provider: string;
+    /** Raised when the stored creds carry no refresh_token to spend. */
+    noRefreshTokenError(): MoxxyError;
+    /**
+     * Wrap a non-network refresh failure (after `classifyNetworkError` declined
+     * it). Return a MoxxyError to surface a friendly message, or the original
+     * error to re-throw it verbatim.
+     */
+    wrapRefreshFailure(err: unknown): unknown;
+    /**
+     * Compute the extras to persist alongside the refreshed tokens, given the
+     * merged token set and the previously-stored extras. Return `undefined` to
+     * omit the extras key entirely (matching `storeTokenSet`'s present-only
+     * write semantics).
+     */
+    resolveExtras(merged: TokenSet, storedExtras: Readonly<Record<string, string>>): Record<string, string> | undefined;
+}
+export declare function refreshAndStore(vault: OAuthVault, spec: RefreshSpec, stored: StoredCreds, retried?: boolean): Promise<{
+    tokens: TokenSet;
+    extras: Readonly<Record<string, string>>;
+}>;
+export interface EnsureFreshOptions {
+    /** Force a refresh even if the access token hasn't expired. */
+    readonly force?: boolean;
+    /** Refresh when within this many ms of expiry. Default 60_000. */
+    readonly skewMs?: number;
+}
+export interface EnsureFreshResult {
+    readonly tokens: TokenSet;
+    readonly extras: Readonly<Record<string, string>>;
+}
+export declare function ensureFreshTokens(profile: OAuthProviderProfile, vault: OAuthVault, opts?: EnsureFreshOptions): Promise<EnsureFreshResult>;
+//# sourceMappingURL=ensure-fresh.d.ts.map

package/dist/ensure-fresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-fresh.d.ts","sourceRoot":"","sources":["../src/ensure-fresh.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,UAAU,EAAwB,MAAM,YAAY,CAAC;AAC9D,OAAO,EAA6C,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAG5G,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,oEAAoE;IACpE,mBAAmB,IAAI,UAAU,CAAC;IAClC;;;;OAIG;IACH,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;IAC1C;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,QAAQ,EAAE,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;CACrH;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,EACjB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,WAAW,EACnB,OAAO,UAAQ,GACd,OAAO,CAAC;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CAAC,CA4CzE;AAED,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,oBAAoB,EAC7B,KAAK,EAAE,UAAU,EACjB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,iBAAiB,CAAC,CAyB5B"}