@moxxy/plugin-oauth 0.0.33

package/dist/open-browser.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Open a URL in the user's default browser. Platform-specific:
+ *   macOS  → `open <url>`
+ *   Linux  → `xdg-open <url>`
+ *   Win32  → `cmd /c start "" "<url>"` (the URL DOUBLE-QUOTED + args passed
+ *           verbatim — see {@link browserOpenCommand})
+ *
+ * Returns once the helper process is spawned — it does NOT wait for the
+ * browser itself, since the user's flow continues asynchronously via
+ * the OAuth callback. Failures fall back to returning the URL string
+ * so the caller can print it for the user to paste manually.
+ */
+export declare function openInBrowser(url: string): Promise<void>;
+/**
+ * Resolve the platform's "open this URL in the default browser" command.
+ * Exported + `platform`-parameterized so the Windows quoting can be unit-tested
+ * without actually spawning a browser.
+ *
+ * Windows is the tricky one: `&` (and `|`, `<`, `>`, `^`) in a URL are cmd.exe
+ * command separators. `cmd /c start "" http://a?x=1&y=2` truncates the URL at
+ * the first `&`, so an OAuth authorize URL loses redirect_uri / code_challenge /
+ * state and the provider rejects the request ("authorization error"). Wrapping
+ * the URL in double quotes makes cmd treat it as one literal token; passing the
+ * args verbatim (`windowsVerbatimArguments`) stops Node from re-quoting and
+ * undoing that. The empty `""` is the required `start` window-title placeholder.
+ */
+export declare function browserOpenCommand(url: string, platform?: NodeJS.Platform): {
+    cmd: string;
+    args: string[];
+    verbatim?: boolean;
+};
+//# sourceMappingURL=open-browser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"open-browser.d.ts","sourceRoot":"","sources":["../src/open-browser.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwC9D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,CAWrD"}

package/dist/open-browser.js

@@ -0,0 +1,83 @@
+import { spawn } from 'node:child_process';
+/**
+ * Open a URL in the user's default browser. Platform-specific:
+ *   macOS  → `open <url>`
+ *   Linux  → `xdg-open <url>`
+ *   Win32  → `cmd /c start "" "<url>"` (the URL DOUBLE-QUOTED + args passed
+ *           verbatim — see {@link browserOpenCommand})
+ *
+ * Returns once the helper process is spawned — it does NOT wait for the
+ * browser itself, since the user's flow continues asynchronously via
+ * the OAuth callback. Failures fall back to returning the URL string
+ * so the caller can print it for the user to paste manually.
+ */
+export async function openInBrowser(url) {
+    const { cmd, args, verbatim } = browserOpenCommand(url);
+    await new Promise((resolve, reject) => {
+        const child = spawn(cmd, args, {
+            stdio: 'ignore',
+            detached: true,
+            // Windows only: keep cmd.exe from re-quoting our already-quoted URL,
+            // which would otherwise break the `&` escaping (see below).
+            ...(verbatim ? { windowsVerbatimArguments: true } : {}),
+        });
+        // Settle exactly once. An early spawn `error` rejects AND clears the pending
+        // 50ms timer (else it would fire a stray resolve later and hold a live timer
+        // handle on the event loop). After we've resolved, a LATE async spawn error
+        // must NOT be left unhandled: an 'error' event with no listener is fatal in
+        // Node (it re-throws as an uncaught exception). So we keep an error listener
+        // attached for the child's whole lifetime — it rejects before settle, and
+        // harmlessly swallows after.
+        let settled = false;
+        const onError = (err) => {
+            if (settled)
+                return; // post-resolve late error: swallow, never crash
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        };
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            resolve();
+        }, 50);
+        // Don't let the 50ms settle-timer keep the process alive on its own.
+        timer.unref?.();
+        // `on` (not `once`): the listener stays for the child's lifetime so any late
+        // 'error' is always handled (a listenerless 'error' would crash the process).
+        child.on('error', onError);
+        // `unref` so a misbehaving opener process can't keep the moxxy
+        // process alive past its own lifetime.
+        child.unref();
+        // Resolve after spawn — we never want to wait for the browser to
+        // close. A 50ms tick is enough to surface spawn-time errors.
+    });
+}
+/**
+ * Resolve the platform's "open this URL in the default browser" command.
+ * Exported + `platform`-parameterized so the Windows quoting can be unit-tested
+ * without actually spawning a browser.
+ *
+ * Windows is the tricky one: `&` (and `|`, `<`, `>`, `^`) in a URL are cmd.exe
+ * command separators. `cmd /c start "" http://a?x=1&y=2` truncates the URL at
+ * the first `&`, so an OAuth authorize URL loses redirect_uri / code_challenge /
+ * state and the provider rejects the request ("authorization error"). Wrapping
+ * the URL in double quotes makes cmd treat it as one literal token; passing the
+ * args verbatim (`windowsVerbatimArguments`) stops Node from re-quoting and
+ * undoing that. The empty `""` is the required `start` window-title placeholder.
+ */
+export function browserOpenCommand(url, platform = process.platform) {
+    if (platform === 'darwin')
+        return { cmd: 'open', args: [url] };
+    if (platform === 'win32') {
+        return {
+            cmd: process.env.ComSpec || 'cmd.exe',
+            args: ['/c', 'start', '""', `"${url}"`],
+            verbatim: true,
+        };
+    }
+    // Linux + everything else assumes a Freedesktop-compliant `xdg-open`.
+    return { cmd: 'xdg-open', args: [url] };
+}
+//# sourceMappingURL=open-browser.js.map

package/dist/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,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,GAAW;IAC7C,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACxD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,IAAI,EAAE;YAC7B,KAAK,EAAE,QAAQ;YACf,QAAQ,EAAE,IAAI;YACd,qEAAqE;YACrE,4DAA4D;YAC5D,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,wBAAwB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACxD,CAAC,CAAC;QACH,6EAA6E;QAC7E,6EAA6E;QAC7E,4EAA4E;QAC5E,4EAA4E;QAC5E,6EAA6E;QAC7E,0EAA0E;QAC1E,6BAA6B;QAC7B,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,OAAO,GAAG,CAAC,GAAU,EAAQ,EAAE;YACnC,IAAI,OAAO;gBAAE,OAAO,CAAC,gDAAgD;YACrE,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,qEAAqE;QACrE,KAAK,CAAC,KAAK,EAAE,EAAE,CAAC;QAChB,6EAA6E;QAC7E,8EAA8E;QAC9E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC3B,+DAA+D;QAC/D,uCAAuC;QACvC,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,iEAAiE;QACjE,6DAA6D;IAC/D,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAW,EACX,WAA4B,OAAO,CAAC,QAAQ;IAE5C,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;IAC/D,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QACzB,OAAO;YACL,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,SAAS;YACrC,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,GAAG,GAAG,CAAC;YACvC,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IACD,sEAAsE;IACtE,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC;AAC1C,CAAC"}

package/dist/pkce.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Generate a PKCE code verifier per RFC 7636 §4.1.
+ * Spec range: 43–128 chars from the unreserved set [A-Z a-z 0-9 - . _ ~].
+ * We use 96 bytes of entropy → 128 base64url chars (full length).
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * RFC 7636 §4.2 — SHA-256(verifier) then base64url-encode. The
+ * challenge_method is implied: callers MUST send `code_challenge_method=S256`
+ * to the authorization endpoint when using this helper.
+ */
+export declare function computeCodeChallenge(codeVerifier: string): string;
+/**
+ * Opaque CSRF token included in the `state` query param. The callback
+ * server verifies that the returned state matches what we sent, so a
+ * cross-site forgery can't redirect the user back into our local
+ * server with attacker-controlled code.
+ */
+export declare function generateState(): string;
+//# sourceMappingURL=pkce.d.ts.map

package/dist/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../src/pkce.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC"}

package/dist/pkce.js

@@ -0,0 +1,34 @@
+import { createHash, randomBytes } from 'node:crypto';
+/**
+ * Generate a PKCE code verifier per RFC 7636 §4.1.
+ * Spec range: 43–128 chars from the unreserved set [A-Z a-z 0-9 - . _ ~].
+ * We use 96 bytes of entropy → 128 base64url chars (full length).
+ */
+export function generateCodeVerifier() {
+    return base64urlEncode(randomBytes(96));
+}
+/**
+ * RFC 7636 §4.2 — SHA-256(verifier) then base64url-encode. The
+ * challenge_method is implied: callers MUST send `code_challenge_method=S256`
+ * to the authorization endpoint when using this helper.
+ */
+export function computeCodeChallenge(codeVerifier) {
+    return base64urlEncode(createHash('sha256').update(codeVerifier).digest());
+}
+/**
+ * Opaque CSRF token included in the `state` query param. The callback
+ * server verifies that the returned state matches what we sent, so a
+ * cross-site forgery can't redirect the user back into our local
+ * server with attacker-controlled code.
+ */
+export function generateState() {
+    return base64urlEncode(randomBytes(24));
+}
+function base64urlEncode(buf) {
+    return buf
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}
+//# sourceMappingURL=pkce.js.map

package/dist/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../src/pkce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;GAIG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,eAAe,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAoB;IACvD,OAAO,eAAe,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,eAAe,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,SAAS,eAAe,CAAC,GAAW;IAClC,OAAO,GAAG;SACP,QAAQ,CAAC,QAAQ,CAAC;SAClB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC;SACnB,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;AACxB,CAAC"}

package/dist/profile.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Provider-framework types. A new OAuth provider plugs in by exporting an
+ * `OAuthProviderProfile` and (if it supports device-flow) one of the bundled
+ * adapters — or a custom adapter for a non-standard dialect.
+ *
+ * The host then calls `runOauthLogin(profile, ctx)` to drive the full dance
+ * and `ensureFreshTokens(profile, vault)` before each upstream request to
+ * keep the access token fresh.
+ */
+import type { PollOutcome, PollState } from './oauth/poll-until.js';
+import type { TokenSet } from './oauth/types.js';
+/**
+ * Single source of truth for everything OAuth-related about a provider.
+ * Constants + extraction logic live here; the framework handles the
+ * actual HTTP / vault / refresh plumbing.
+ */
+export interface OAuthProviderProfile {
+    /**
+     * Stable namespace under `oauth/<id>/*` in the vault. Lowercase,
+     * digits, dot/dash/underscore only — same rules as `validateProvider`.
+     * Example: `'openai-codex'`, `'google'`, `'github'`.
+     */
+    readonly id: string;
+    /** Authorization endpoint, e.g. https://accounts.google.com/o/oauth2/v2/auth */
+    readonly authUrl: string;
+    /** Token endpoint, e.g. https://oauth2.googleapis.com/token */
+    readonly tokenUrl: string;
+    readonly clientId: string;
+    /** Confidential clients only — loopback flows usually omit. */
+    readonly clientSecret?: string;
+    readonly scopes: ReadonlyArray<string>;
+    /**
+     * Provider-specific auth-URL params. Google wants
+     * `access_type=offline` + `prompt=consent` for a refresh_token; Codex
+     * wants `id_token_add_organizations=true` etc.
+     */
+    readonly extraAuthParams?: Readonly<Record<string, string>>;
+    /**
+     * Loopback callback config. Provider's registered redirect URI must
+     * match `http://localhost:<port><path>` EXACTLY.
+     */
+    readonly redirect?: {
+        readonly port?: number;
+        readonly path?: string;
+    };
+    /**
+     * Device-flow adapter. Omit when the provider doesn't support a
+     * headless flow — `runOauthLogin` will reject `headless=true` with a
+     * helpful message.
+     */
+    readonly deviceFlow?: DeviceFlowAdapter;
+    /**
+     * Pull a stable per-account identifier out of the token set. Codex
+     * extracts `chatgpt_account_id` from the id_token; Google could
+     * extract `email`. Returned value is shown to the user post-login and
+     * persisted under `extras.account_id`. Optional — providers that
+     * don't expose a useful identifier skip it.
+     */
+    readonly extractAccountId?: (tokens: TokenSet) => string | undefined;
+    /**
+     * Extract extra provider-specific fields to persist alongside the
+     * token set (e.g. `team_slug`, `org_id`). Merged with the account_id
+     * (if any) into the `extras` map under `oauth/<id>/extras`.
+     */
+    readonly extractExtras?: (tokens: TokenSet) => Readonly<Record<string, string>>;
+    /**
+     * Human-readable name used in prompts and success messages, e.g.
+     * "ChatGPT Pro/Plus", "Google Workspace". Falls back to `id` when omitted.
+     */
+    readonly displayName?: string;
+}
+/**
+ * Pluggable device-flow contract. Implementations encode a single dialect
+ * (RFC 8628, OpenAI's flavor, ...). The framework calls `start()` once,
+ * surfaces the returned prompt to the user, then modes on `poll()` via
+ * the shared `pollUntil` primitive.
+ */
+export interface DeviceFlowAdapter {
+    start(args: DeviceFlowStartArgs): Promise<DeviceFlowInit>;
+    /**
+     * Single poll attempt against the provider's poll endpoint. May
+     * mutate `state.intervalMs` to honour a `slow_down` from the server.
+     * Resolves to `{done}` with the issued TokenSet, or `{pending: true}`
+     * to keep polling. Throws on fatal errors (denied / expired).
+     */
+    poll(init: DeviceFlowInit, state: PollState): Promise<PollOutcome<TokenSet>>;
+}
+export interface DeviceFlowStartArgs {
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    readonly scopes: ReadonlyArray<string>;
+    readonly signal?: AbortSignal;
+}
+export interface DeviceFlowInit {
+    /** Short code the user enters at `verificationUri`. */
+    readonly userCode: string;
+    readonly verificationUri: string;
+    /** Some providers return a URL that already embeds the user_code. */
+    readonly verificationUriComplete?: string;
+    /** Initial poll interval. The framework honours `slow_down` bumps. */
+    readonly intervalMs: number;
+    /** Hard deadline (ms from now) before the device_code dies. */
+    readonly expiresInMs: number;
+    /**
+     * Opaque data the adapter threads from `start()` to `poll()` —
+     * device_code, server-assigned ids, code_verifier, etc. The framework
+     * never inspects this.
+     */
+    readonly providerData: unknown;
+}
+export interface RunOauthLoginCtx {
+    readonly vault: {
+        get(key: string): Promise<string | null>;
+        set(key: string, value: string, tags?: ReadonlyArray<string>): Promise<void>;
+        delete?(key: string): Promise<boolean>;
+    };
+    /** True ⇒ choose the device flow. False ⇒ open a browser. */
+    readonly headless: boolean;
+    /** Progress-message sink. The host wires this to its preferred renderer. */
+    readonly write: (chunk: string) => void;
+    readonly signal?: AbortSignal;
+}
+export interface RunOauthLoginResult {
+    readonly tokens: TokenSet;
+    /** Convenience surface for `ProviderOAuthResult.accountId`. */
+    readonly accountId?: string;
+    readonly extras: Readonly<Record<string, string>>;
+}
+//# sourceMappingURL=profile.d.ts.map

package/dist/profile.d.ts.map

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

package/dist/profile.js

@@ -0,0 +1,11 @@
+/**
+ * Provider-framework types. A new OAuth provider plugs in by exporting an
+ * `OAuthProviderProfile` and (if it supports device-flow) one of the bundled
+ * adapters — or a custom adapter for a non-standard dialect.
+ *
+ * The host then calls `runOauthLogin(profile, ctx)` to drive the full dance
+ * and `ensureFreshTokens(profile, vault)` before each upstream request to
+ * keep the access token fresh.
+ */
+export {};
+//# sourceMappingURL=profile.js.map

package/dist/profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.js","sourceRoot":"","sources":["../src/profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/run-login.d.ts

@@ -0,0 +1,9 @@
+/**
+ * High-level orchestrator. Drives the full login dance for any provider
+ * declared via `OAuthProviderProfile` — picks browser or device flow based
+ * on `ctx.headless`, surfaces the user-facing prompt, persists the result
+ * (token set + extras) under `oauth/<profile.id>/*`.
+ */
+import type { OAuthProviderProfile, RunOauthLoginCtx, RunOauthLoginResult } from './profile.js';
+export declare function runOauthLogin(profile: OAuthProviderProfile, ctx: RunOauthLoginCtx): Promise<RunOauthLoginResult>;
+//# sourceMappingURL=run-login.d.ts.map

package/dist/run-login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-login.d.ts","sourceRoot":"","sources":["../src/run-login.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,OAAO,KAAK,EAGV,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,cAAc,CAAC;AAMtB,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,gBAAgB,GACpB,OAAO,CAAC,mBAAmB,CAAC,CAsB9B"}

package/dist/run-login.js

@@ -0,0 +1,93 @@
+/**
+ * High-level orchestrator. Drives the full login dance for any provider
+ * declared via `OAuthProviderProfile` — picks browser or device flow based
+ * on `ctx.headless`, surfaces the user-facing prompt, persists the result
+ * (token set + extras) under `oauth/<profile.id>/*`.
+ */
+import { MoxxyError } from '@moxxy/sdk';
+import { runAuthorizationCodeFlow } from './oauth/browser-flow.js';
+import { pollUntil } from './oauth/poll-until.js';
+import { storeTokenSet } from './storage.js';
+const DEFAULT_BROWSER_TIMEOUT_MS = 5 * 60 * 1000;
+const DEFAULT_DEVICE_TIMEOUT_MS = 10 * 60 * 1000;
+const DEVICE_POLL_SAFETY_MARGIN_MS = 3000;
+export async function runOauthLogin(profile, ctx) {
+    const tokens = ctx.headless
+        ? await runDeviceFlow(profile, ctx)
+        : await runBrowserFlow(profile, ctx);
+    const accountId = profile.extractAccountId?.(tokens);
+    const customExtras = profile.extractExtras?.(tokens) ?? {};
+    const extras = { ...customExtras };
+    if (accountId)
+        extras.account_id = accountId;
+    await storeTokenSet(ctx.vault, profile.id, tokens, {
+        clientId: profile.clientId,
+        ...(profile.clientSecret ? { clientSecret: profile.clientSecret } : {}),
+        tokenUrl: profile.tokenUrl,
+        extras,
+    });
+    return {
+        tokens,
+        ...(accountId ? { accountId } : {}),
+        extras,
+    };
+}
+async function runBrowserFlow(profile, ctx) {
+    const port = profile.redirect?.port ?? 8765;
+    const path = profile.redirect?.path ?? '/callback';
+    const serviceName = profile.displayName ?? profile.id;
+    return runAuthorizationCodeFlow({
+        authUrl: profile.authUrl,
+        tokenUrl: profile.tokenUrl,
+        clientId: profile.clientId,
+        ...(profile.clientSecret ? { clientSecret: profile.clientSecret } : {}),
+        scopes: profile.scopes,
+        redirectPort: port,
+        redirectPath: path,
+        ...(profile.extraAuthParams ? { extraAuthParams: profile.extraAuthParams } : {}),
+        timeoutMs: DEFAULT_BROWSER_TIMEOUT_MS,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+        onAuthUrl: (url) => {
+            ctx.write(`\nSign in to ${serviceName} to authorize moxxy\n\n` +
+                `If your browser doesn't open automatically, paste this URL:\n\n  ${url}\n\n` +
+                `Waiting for callback on http://localhost:${port}${path} (5 min timeout)…\n\n`);
+        },
+    });
+}
+async function runDeviceFlow(profile, ctx) {
+    if (!profile.deviceFlow) {
+        throw new MoxxyError({
+            code: 'OAUTH_FLOW_NOT_SUPPORTED',
+            message: `Provider "${profile.id}" doesn't expose a headless (device-code) flow.`,
+            hint: 'Run this command on a host with a browser, or ask the provider plugin author to ' +
+                'add a deviceFlow adapter to the profile.',
+            context: { provider: profile.id },
+        });
+    }
+    const adapter = profile.deviceFlow;
+    const init = await adapter.start({
+        clientId: profile.clientId,
+        ...(profile.clientSecret ? { clientSecret: profile.clientSecret } : {}),
+        scopes: profile.scopes,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+    });
+    const serviceName = profile.displayName ?? profile.id;
+    ctx.write(`\nSign in to ${serviceName} (headless / device code flow)\n\n` +
+        `  1. On any browser-capable device, open:\n` +
+        `       ${init.verificationUriComplete ?? init.verificationUri}\n\n` +
+        `  2. Enter this code:\n` +
+        `       ${init.userCode}\n\n` +
+        `Polling every ${Math.round(init.intervalMs / 1000)}s ` +
+        `(${Math.round(init.expiresInMs / 60000)} min timeout)…\n\n`);
+    // Cap the polling deadline by the device_code's own expiry — once it
+    // dies, any further poll is wasted.
+    const timeoutMs = Math.min(init.expiresInMs, DEFAULT_DEVICE_TIMEOUT_MS);
+    return pollUntil((state) => adapter.poll(init, state), {
+        intervalMs: init.intervalMs + DEVICE_POLL_SAFETY_MARGIN_MS,
+        timeoutMs,
+        label: `${profile.id} device flow`,
+        leadingWait: true,
+        ...(ctx.signal ? { signal: ctx.signal } : {}),
+    });
+}
+//# sourceMappingURL=run-login.js.map

package/dist/run-login.js.map

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

package/dist/storage.d.ts

@@ -0,0 +1,46 @@
+import type { TokenSet } from './flow.js';
+/**
+ * Minimal vault shape this module uses. Both `@moxxy/plugin-vault`'s
+ * `VaultStore` and the SDK's `ProviderVault` structurally satisfy it, so
+ * callers can pass whichever they hold.
+ */
+export interface OAuthVault {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, tags?: ReadonlyArray<string>): Promise<void>;
+    delete?(key: string): Promise<boolean>;
+}
+export declare function validateProvider(name: string): void;
+export interface StoreTokenSetMeta {
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    readonly tokenUrl: string;
+    /**
+     * Provider-specific extras the framework persists alongside the token
+     * set. Used for fields like `account_id`, `org_id`, `team_slug` that
+     * don't fit `TokenSet` but the caller wants to recover later.
+     */
+    readonly extras?: Readonly<Record<string, string>>;
+}
+export interface StoredCreds {
+    readonly tokenSet: TokenSet;
+    readonly clientId: string;
+    readonly clientSecret: string | null;
+    readonly tokenUrl: string;
+    readonly extras: Readonly<Record<string, string>>;
+}
+export declare function storeTokenSet(vault: OAuthVault, provider: string, tokens: TokenSet, meta: StoreTokenSetMeta): Promise<void>;
+export declare function readStoredCreds(vault: OAuthVault, provider: string): Promise<StoredCreds | null>;
+export declare function clearStoredCreds(vault: OAuthVault, provider: string): Promise<number>;
+/**
+ * True when the access token has expired (or is within `skewMs` of doing so).
+ *
+ * A token with no `expiresAt` is treated as non-expiring (some providers issue
+ * tokens without `expires_in`). A non-FINITE `expiresAt` (NaN/Infinity — corrupt
+ * data, an out-of-range parse) is treated as EXPIRED, never as fresh: a bare
+ * `>=` against NaN is always false, which would otherwise mark a token eternally
+ * valid and suppress every refresh. Forcing the expired branch degrades to a
+ * refresh (or a clear AUTH_EXPIRED if no refresh_token) instead of silently
+ * serving a token whose real expiry is unknown.
+ */
+export declare function isExpired(tokens: TokenSet, skewMs?: number): boolean;
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAqB1C;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7E,MAAM,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMnD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACnD;AAED,wBAAsB,aAAa,CACjC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,QAAQ,EAChB,IAAI,EAAE,iBAAiB,GACtB,OAAO,CAAC,IAAI,CAAC,CAkCf;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAiD7B;AAED,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAoB3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,GAAG,OAAO,CAIpE"}