@moxxy/plugin-oauth 0.0.33

package/dist/ensure-fresh.js

@@ -0,0 +1,122 @@
+/**
+ * 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, classifyNetworkError } from '@moxxy/sdk';
+import { isExpired, readStoredCreds, storeTokenSet } from './storage.js';
+import { refreshAccessToken } from './oauth/token-exchange.js';
+import { isAuthRejection, withCredentialLock } from './credential-lock.js';
+export async function refreshAndStore(vault, spec, stored, retried = false) {
+    if (!stored.tokenSet.refreshToken) {
+        throw spec.noRefreshTokenError();
+    }
+    let refreshed;
+    try {
+        refreshed = await refreshAccessToken({
+            tokenUrl: stored.tokenUrl,
+            clientId: stored.clientId,
+            ...(stored.clientSecret ? { clientSecret: stored.clientSecret } : {}),
+            refreshToken: stored.tokenSet.refreshToken,
+        });
+    }
+    catch (err) {
+        // Rotation-race recovery: an invalid_grant-style rejection with a
+        // DIFFERENT refresh_token now on disk means another process rotated ours
+        // away after we read it. Retry once with the fresher token before
+        // declaring re-auth necessary. Transient (network/5xx) failures are not
+        // recovered here — they aren't evidence of rotation.
+        if (!retried && isAuthRejection(err)) {
+            const latest = await readStoredCreds(vault, spec.provider);
+            if (latest?.tokenSet.refreshToken &&
+                latest.tokenSet.refreshToken !== stored.tokenSet.refreshToken) {
+                return refreshAndStore(vault, spec, latest, true);
+            }
+        }
+        const net = classifyNetworkError(err, { url: stored.tokenUrl, provider: spec.provider });
+        if (net)
+            throw net;
+        throw spec.wrapRefreshFailure(err);
+    }
+    // Providers MAY rotate refresh_token — preserve the prior one if not.
+    const merged = {
+        ...refreshed,
+        refreshToken: refreshed.refreshToken ?? stored.tokenSet.refreshToken,
+    };
+    const extras = spec.resolveExtras(merged, stored.extras);
+    await storeTokenSet(vault, spec.provider, merged, {
+        clientId: stored.clientId,
+        ...(stored.clientSecret ? { clientSecret: stored.clientSecret } : {}),
+        tokenUrl: stored.tokenUrl,
+        ...(extras ? { extras } : {}),
+    });
+    return { tokens: merged, extras: extras ?? stored.extras };
+}
+export async function ensureFreshTokens(profile, vault, opts = {}) {
+    const stored = await readStoredCreds(vault, profile.id);
+    if (!stored) {
+        throw new MoxxyError({
+            code: 'AUTH_NO_CREDENTIALS',
+            message: `No stored OAuth credentials for "${profile.id}".`,
+            hint: `Run \`moxxy login ${profile.id}\` to sign in.`,
+            context: { provider: profile.id },
+        });
+    }
+    if (!opts.force && !isExpired(stored.tokenSet, opts.skewMs)) {
+        return { tokens: stored.tokenSet, extras: stored.extras };
+    }
+    return withCredentialLock(`oauth-${profile.id}`, async () => {
+        // Re-read under the lock: another consumer/process may have refreshed
+        // while we waited. If the vault now holds a different, still-fresh access
+        // token, reuse it — even under `force`, which exists for 401 recovery and
+        // is satisfied by ANY rotation, not specifically ours.
+        const current = (await readStoredCreds(vault, profile.id)) ?? stored;
+        const rotatedMeanwhile = current.tokenSet.accessToken !== stored.tokenSet.accessToken;
+        if (!isExpired(current.tokenSet, opts.skewMs) && (!opts.force || rotatedMeanwhile)) {
+            return { tokens: current.tokenSet, extras: current.extras };
+        }
+        return refreshAndStore(vault, profileRefreshSpec(profile), current);
+    });
+}
+/**
+ * RefreshSpec for a provider profile: friendly `moxxy login`-flavored errors
+ * and extras re-derived from the fresh tokens (id_token re-issuance varies by
+ * provider, so fall back to stored extras for fields like account_id).
+ */
+function profileRefreshSpec(profile) {
+    return {
+        provider: profile.id,
+        noRefreshTokenError: () => new MoxxyError({
+            code: 'AUTH_EXPIRED',
+            message: `OAuth token for "${profile.id}" expired and no refresh_token is stored.`,
+            hint: `Re-run \`moxxy login ${profile.id}\` to sign in again.`,
+            context: { provider: profile.id },
+        }),
+        wrapRefreshFailure: (err) => new MoxxyError({
+            code: 'AUTH_EXPIRED',
+            message: `Couldn't refresh the OAuth token for "${profile.id}".`,
+            hint: `Re-run \`moxxy login ${profile.id}\` to sign in again.`,
+            context: { provider: profile.id },
+            cause: err,
+        }),
+        resolveExtras: (merged, storedExtras) => {
+            const freshAccountId = profile.extractAccountId?.(merged);
+            const freshExtras = profile.extractExtras?.(merged) ?? {};
+            const mergedExtras = { ...storedExtras, ...freshExtras };
+            if (freshAccountId)
+                mergedExtras.account_id = freshAccountId;
+            return mergedExtras;
+        },
+    };
+}
+//# sourceMappingURL=ensure-fresh.js.map

package/dist/ensure-fresh.js.map

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

package/dist/flow.d.ts

@@ -0,0 +1,6 @@
+export { buildAuthUrl, runAuthorizationCodeFlow, type BuildAuthUrlInput } from './oauth/browser-flow.js';
+export { runDeviceCodeFlow } from './oauth/device-flow.js';
+export { exchangeCodeForToken, parseTokenResponse, refreshAccessToken, } from './oauth/token-exchange.js';
+export type { DeviceFlowOptions, DevicePrompt, OAuthFlowOptions, TokenSet } from './oauth/types.js';
+export { pollUntil, type PollOutcome, type PollState, type PollUntilOpts } from './oauth/poll-until.js';
+//# sourceMappingURL=flow.d.ts.map

package/dist/flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.d.ts","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACzG,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AACnC,YAAY,EAAE,iBAAiB,EAAE,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/flow.js

@@ -0,0 +1,5 @@
+export { buildAuthUrl, runAuthorizationCodeFlow } from './oauth/browser-flow.js';
+export { runDeviceCodeFlow } from './oauth/device-flow.js';
+export { exchangeCodeForToken, parseTokenResponse, refreshAccessToken, } from './oauth/token-exchange.js';
+export { pollUntil } from './oauth/poll-until.js';
+//# sourceMappingURL=flow.js.map

package/dist/flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.js","sourceRoot":"","sources":["../src/flow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,wBAAwB,EAA0B,MAAM,yBAAyB,CAAC;AACzG,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EACL,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,SAAS,EAAwD,MAAM,uBAAuB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { type Plugin } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+export { buildAuthUrl, exchangeCodeForToken, parseTokenResponse, refreshAccessToken, runAuthorizationCodeFlow, runDeviceCodeFlow, pollUntil, } from './flow.js';
+export type { BuildAuthUrlInput, DeviceFlowOptions, DevicePrompt, OAuthFlowOptions, PollOutcome, PollState, PollUntilOpts, TokenSet, } from './flow.js';
+export { computeCodeChallenge, generateCodeVerifier, generateState } from './pkce.js';
+export { openInBrowser } from './open-browser.js';
+export { clearStoredCreds, isExpired, readStoredCreds, storeTokenSet, validateProvider, type OAuthVault, type StoreTokenSetMeta, type StoredCreds, } from './storage.js';
+export type { DeviceFlowAdapter, DeviceFlowInit, DeviceFlowStartArgs, OAuthProviderProfile, RunOauthLoginCtx, RunOauthLoginResult, } from './profile.js';
+export { runOauthLogin } from './run-login.js';
+export { ensureFreshTokens, type EnsureFreshOptions, type EnsureFreshResult, } from './ensure-fresh.js';
+export { isAuthRejection, withCredentialLock, type CredentialLockOptions, } from './credential-lock.js';
+export { rfc8628DeviceFlow, type Rfc8628AdapterOpts } from './adapters/rfc8628-device-flow.js';
+export { openaiDeviceFlow, type OpenaiDeviceFlowOpts } from './adapters/openai-device-flow.js';
+export { buildOauthAuthorizeTool, buildOauthClearTool, buildOauthGetTokenTool, type OAuthToolDeps, } from './tools.js';
+export interface BuildOauthPluginOpts {
+    readonly vault: VaultStore;
+}
+/**
+ * `@moxxy/plugin-oauth` — generic OAuth 2.0 + PKCE provider framework.
+ *
+ * Two surfaces:
+ *   1. **Tools** — `oauth_authorize`, `oauth_get_token`, `oauth_clear_token`.
+ *      Model-callable; suits ad-hoc usage and MCP server wiring.
+ *   2. **Provider framework** — declare an `OAuthProviderProfile`, plug in
+ *      (or write) a `DeviceFlowAdapter`, drive with `runOauthLogin(profile, ctx)`
+ *      and `ensureFreshTokens(profile, vault)`. Suits LLM providers (e.g.
+ *      `@moxxy/plugin-provider-openai-codex`) that own their auth lifecycle.
+ *
+ * Tokens persist in the vault under `oauth/<provider>/*`. Bundled device
+ * adapters: `rfc8628DeviceFlow` (standards-compliant), `openaiDeviceFlow`
+ * (OpenAI's non-standard flavor). New dialects ship their own adapter.
+ */
+export declare function buildOauthPlugin(opts: BuildOauthPluginOpts): Plugin;
+/**
+ * Discovery-loadable default export: resolves the vault from the inter-plugin
+ * service registry in `onInit` (the vault plugin publishes `'vault'`). Requires
+ * `@moxxy/plugin-vault` to load first (declared in `package.json`
+ * `moxxy.requirements`), so its `onInit` registers the service before this one
+ * consumes it. The tools read `deps.vault` lazily via a getter, so they resolve
+ * the store at call time — after `onInit` has wired it.
+ */
+export declare const oauthPlugin: Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,MAAM,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAStD,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,SAAS,GACV,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,SAAS,EACT,aAAa,EACb,QAAQ,GACT,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,cAAc,CAAC;AAItB,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EACL,iBAAiB,EACjB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,mBAAmB,CAAC;AAK3B,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,KAAK,qBAAqB,GAC3B,MAAM,sBAAsB,CAAC;AAG9B,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,KAAK,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAG/F,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,aAAa,GACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAGnE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,EAAE,MAgBtB,CAAC"}

package/dist/index.js

@@ -0,0 +1,82 @@
+import { definePlugin } from '@moxxy/sdk';
+import { buildOauthAuthorizeTool, buildOauthClearTool, buildOauthGetTokenTool, } from './tools.js';
+// Low-level flow primitives — useful for ad-hoc usage or custom adapters.
+export { buildAuthUrl, exchangeCodeForToken, parseTokenResponse, refreshAccessToken, runAuthorizationCodeFlow, runDeviceCodeFlow, pollUntil, } from './flow.js';
+export { computeCodeChallenge, generateCodeVerifier, generateState } from './pkce.js';
+export { openInBrowser } from './open-browser.js';
+// Storage (vault-backed; extras-aware).
+export { clearStoredCreds, isExpired, readStoredCreds, storeTokenSet, validateProvider, } from './storage.js';
+export { runOauthLogin } from './run-login.js';
+export { ensureFreshTokens, } from './ensure-fresh.js';
+// Per-credential refresh serialization (in-process mutex + best-effort
+// cross-process lockfile) for providers with single-use rotating
+// refresh tokens.
+export { isAuthRejection, withCredentialLock, } from './credential-lock.js';
+// Bundled device-flow adapters. Custom dialects implement `DeviceFlowAdapter`.
+export { rfc8628DeviceFlow } from './adapters/rfc8628-device-flow.js';
+export { openaiDeviceFlow } from './adapters/openai-device-flow.js';
+// Tools layer — `oauth_authorize`, `oauth_get_token`, `oauth_clear_token`.
+export { buildOauthAuthorizeTool, buildOauthClearTool, buildOauthGetTokenTool, } from './tools.js';
+/**
+ * `@moxxy/plugin-oauth` — generic OAuth 2.0 + PKCE provider framework.
+ *
+ * Two surfaces:
+ *   1. **Tools** — `oauth_authorize`, `oauth_get_token`, `oauth_clear_token`.
+ *      Model-callable; suits ad-hoc usage and MCP server wiring.
+ *   2. **Provider framework** — declare an `OAuthProviderProfile`, plug in
+ *      (or write) a `DeviceFlowAdapter`, drive with `runOauthLogin(profile, ctx)`
+ *      and `ensureFreshTokens(profile, vault)`. Suits LLM providers (e.g.
+ *      `@moxxy/plugin-provider-openai-codex`) that own their auth lifecycle.
+ *
+ * Tokens persist in the vault under `oauth/<provider>/*`. Bundled device
+ * adapters: `rfc8628DeviceFlow` (standards-compliant), `openaiDeviceFlow`
+ * (OpenAI's non-standard flavor). New dialects ship their own adapter.
+ */
+export function buildOauthPlugin(opts) {
+    // Host-injected vault (available immediately).
+    return makeOauthPlugin(() => opts.vault);
+}
+/**
+ * Discovery-loadable default export: resolves the vault from the inter-plugin
+ * service registry in `onInit` (the vault plugin publishes `'vault'`). Requires
+ * `@moxxy/plugin-vault` to load first (declared in `package.json`
+ * `moxxy.requirements`), so its `onInit` registers the service before this one
+ * consumes it. The tools read `deps.vault` lazily via a getter, so they resolve
+ * the store at call time — after `onInit` has wired it.
+ */
+export const oauthPlugin = (() => {
+    let resolved = null;
+    const getVault = () => {
+        if (!resolved) {
+            throw new Error('@moxxy/plugin-oauth: the "vault" service is unavailable — @moxxy/plugin-vault must load first');
+        }
+        return resolved;
+    };
+    const hooks = {
+        onInit: (ctx) => {
+            resolved = ctx.services.require('vault');
+        },
+    };
+    return makeOauthPlugin(getVault, hooks);
+})();
+function makeOauthPlugin(getVault, hooks) {
+    // The getter satisfies `OAuthToolDeps.vault` while deferring resolution to call
+    // time, so the same tools work whether the vault is host-injected or resolved
+    // from the service registry in onInit.
+    const deps = {
+        get vault() {
+            return getVault();
+        },
+    };
+    return definePlugin({
+        name: '@moxxy/plugin-oauth',
+        version: '0.0.0',
+        tools: [
+            buildOauthAuthorizeTool(deps),
+            buildOauthGetTokenTool(deps),
+            buildOauthClearTool(deps),
+        ],
+        ...(hooks ? { hooks } : {}),
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAoC,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,GAEvB,MAAM,YAAY,CAAC;AAEpB,0EAA0E;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,iBAAiB,EACjB,SAAS,GACV,MAAM,WAAW,CAAC;AAYnB,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,wCAAwC;AACxC,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,aAAa,EACb,gBAAgB,GAIjB,MAAM,cAAc,CAAC;AAYtB,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EACL,iBAAiB,GAGlB,MAAM,mBAAmB,CAAC;AAE3B,uEAAuE;AACvE,iEAAiE;AACjE,kBAAkB;AAClB,OAAO,EACL,eAAe,EACf,kBAAkB,GAEnB,MAAM,sBAAsB,CAAC;AAE9B,+EAA+E;AAC/E,OAAO,EAAE,iBAAiB,EAA2B,MAAM,mCAAmC,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAA6B,MAAM,kCAAkC,CAAC;AAE/F,2EAA2E;AAC3E,OAAO,EACL,uBAAuB,EACvB,mBAAmB,EACnB,sBAAsB,GAEvB,MAAM,YAAY,CAAC;AAMpB;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAA0B;IACzD,+CAA+C;IAC/C,OAAO,eAAe,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,WAAW,GAAW,CAAC,GAAG,EAAE;IACvC,IAAI,QAAQ,GAAsB,IAAI,CAAC;IACvC,MAAM,QAAQ,GAAG,GAAe,EAAE;QAChC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,+FAA+F,CAChG,CAAC;QACJ,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IACF,MAAM,KAAK,GAAmB;QAC5B,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE;YACd,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAa,OAAO,CAAC,CAAC;QACvD,CAAC;KACF,CAAC;IACF,OAAO,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;AAC1C,CAAC,CAAC,EAAE,CAAC;AAEL,SAAS,eAAe,CAAC,QAA0B,EAAE,KAAsB;IACzE,gFAAgF;IAChF,8EAA8E;IAC9E,uCAAuC;IACvC,MAAM,IAAI,GAAkB;QAC1B,IAAI,KAAK;YACP,OAAO,QAAQ,EAAE,CAAC;QACpB,CAAC;KACF,CAAC;IACF,OAAO,YAAY,CAAC;QAClB,IAAI,EAAE,qBAAqB;QAC3B,OAAO,EAAE,OAAO;QAChB,KAAK,EAAE;YACL,uBAAuB,CAAC,IAAI,CAAC;YAC7B,sBAAsB,CAAC,IAAI,CAAC;YAC5B,mBAAmB,CAAC,IAAI,CAAC;SAC1B;QACD,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5B,CAAC,CAAC;AACL,CAAC"}

package/dist/oauth/browser-flow.d.ts

@@ -0,0 +1,23 @@
+import type { OAuthFlowOptions, TokenSet } from './types.js';
+export interface BuildAuthUrlInput {
+    readonly authUrl: string;
+    readonly clientId: string;
+    readonly redirectUri: string;
+    readonly scopes: ReadonlyArray<string>;
+    readonly codeChallenge: string;
+    readonly state: string;
+    readonly extraAuthParams?: Readonly<Record<string, string>>;
+}
+/** Pure URL builder, exported separately so tests can assert on it. */
+export declare function buildAuthUrl(input: BuildAuthUrlInput): string;
+/**
+ * Run the full authorization-code-with-PKCE dance:
+ *   1. Bind a loopback HTTP server on `redirectPort`.
+ *   2. Build the auth URL (PKCE challenge, CSRF state, scopes, etc.).
+ *   3. Open the URL in the user's default browser.
+ *   4. Wait for the provider to redirect back with `code` + `state`.
+ *   5. Verify state, POST the code to the token endpoint with the
+ *      verifier, return the parsed token set.
+ */
+export declare function runAuthorizationCodeFlow(opts: OAuthFlowOptions): Promise<TokenSet>;
+//# sourceMappingURL=browser-flow.d.ts.map

package/dist/oauth/browser-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-flow.d.ts","sourceRoot":"","sources":["../../src/oauth/browser-flow.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7D;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,MAAM,CAa7D;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsDxF"}

package/dist/oauth/browser-flow.js

@@ -0,0 +1,82 @@
+import { computeCodeChallenge, generateCodeVerifier, generateState } from '../pkce.js';
+import { openInBrowser } from '../open-browser.js';
+import { waitForCallback } from './callback-server.js';
+import { exchangeCodeForToken } from './token-exchange.js';
+/** Pure URL builder, exported separately so tests can assert on it. */
+export function buildAuthUrl(input) {
+    const url = new URL(input.authUrl);
+    url.searchParams.set('client_id', input.clientId);
+    url.searchParams.set('redirect_uri', input.redirectUri);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('scope', input.scopes.join(' '));
+    url.searchParams.set('state', input.state);
+    url.searchParams.set('code_challenge', input.codeChallenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    for (const [k, v] of Object.entries(input.extraAuthParams ?? {})) {
+        url.searchParams.set(k, v);
+    }
+    return url.toString();
+}
+/**
+ * Run the full authorization-code-with-PKCE dance:
+ *   1. Bind a loopback HTTP server on `redirectPort`.
+ *   2. Build the auth URL (PKCE challenge, CSRF state, scopes, etc.).
+ *   3. Open the URL in the user's default browser.
+ *   4. Wait for the provider to redirect back with `code` + `state`.
+ *   5. Verify state, POST the code to the token endpoint with the
+ *      verifier, return the parsed token set.
+ */
+export async function runAuthorizationCodeFlow(opts) {
+    const port = opts.redirectPort ?? 8765;
+    const path = opts.redirectPath ?? '/callback';
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = computeCodeChallenge(codeVerifier);
+    const state = generateState();
+    const redirectUri = `http://localhost:${port}${path}`;
+    const authUrl = buildAuthUrl({
+        authUrl: opts.authUrl,
+        clientId: opts.clientId,
+        redirectUri,
+        scopes: opts.scopes,
+        codeChallenge,
+        state,
+        ...(opts.extraAuthParams ? { extraAuthParams: opts.extraAuthParams } : {}),
+    });
+    // Start the server BEFORE opening the browser — otherwise the user
+    // could complete the consent screen before we're listening and the
+    // redirect would 404.
+    const codePromise = waitForCallback({
+        port,
+        path,
+        expectedState: state,
+        timeoutMs: opts.timeoutMs ?? 300_000,
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+    if (opts.onAuthUrl)
+        opts.onAuthUrl(authUrl);
+    if (!opts.noOpen) {
+        try {
+            await openInBrowser(authUrl);
+        }
+        catch {
+            // Failed to open the browser — not fatal; the user can visit
+            // the URL surfaced via onAuthUrl. The loopback server is still
+            // listening.
+        }
+    }
+    const code = await codePromise;
+    // Thread the abort signal into the exchange too: a turn cancelled AFTER the
+    // browser redirect arrives but DURING the token POST must cancel the in-flight
+    // fetch, not leak a hung request past the cancel. (waitForCallback already
+    // honours the same signal for the listening phase.)
+    return exchangeCodeForToken({
+        tokenUrl: opts.tokenUrl,
+        code,
+        redirectUri,
+        clientId: opts.clientId,
+        ...(opts.clientSecret ? { clientSecret: opts.clientSecret } : {}),
+        codeVerifier,
+        ...(opts.signal ? { signal: opts.signal } : {}),
+    });
+}
+//# sourceMappingURL=browser-flow.js.map

package/dist/oauth/browser-flow.js.map

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

package/dist/oauth/callback-server.d.ts

@@ -0,0 +1,10 @@
+interface WaitForCallbackOpts {
+    readonly port: number;
+    readonly path: string;
+    readonly expectedState: string;
+    readonly timeoutMs: number;
+    readonly signal?: AbortSignal;
+}
+export declare function waitForCallback(opts: WaitForCallbackOpts): Promise<string>;
+export {};
+//# sourceMappingURL=callback-server.d.ts.map

package/dist/oauth/callback-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback-server.d.ts","sourceRoot":"","sources":["../../src/oauth/callback-server.ts"],"names":[],"mappings":"AAGA,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAwL1E"}

package/dist/oauth/callback-server.js

@@ -0,0 +1,158 @@
+import { createServer } from 'node:http';
+import { MoxxyError } from '@moxxy/sdk';
+export function waitForCallback(opts) {
+    return new Promise((resolve, reject) => {
+        // Bind BOTH loopback stacks. The redirect_uri uses `localhost`, which
+        // Windows resolves to `::1` (IPv6) first while macOS/Linux use `127.0.0.1`
+        // (IPv4). A v4-only listener therefore never receives the redirect on
+        // Windows → the login hangs on "waiting for the browser". IPv4 is required;
+        // IPv6 is best-effort (a host without it still works, since there
+        // `localhost` is IPv4 anyway).
+        const servers = [];
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            // Single cleanup chokepoint: clear the timeout AND detach the abort
+            // listener on every exit (success/timeout/abort/error), so neither a
+            // dangling timer nor a lingering signal listener is left behind. Guard
+            // each close()/fn() so a Server.close() that throws ERR_SERVER_NOT_RUNNING
+            // (server pushed before its listen completed) can never strand the
+            // remaining servers or skip the resolve/reject.
+            clearTimeout(timer);
+            opts.signal?.removeEventListener('abort', onAbort);
+            try {
+                for (const s of servers) {
+                    try {
+                        s.close();
+                    }
+                    catch {
+                        /* not yet listening — nothing to close */
+                    }
+                }
+            }
+            finally {
+                fn();
+            }
+        };
+        const timer = setTimeout(() => {
+            settle(() => reject(new MoxxyError({
+                code: 'OAUTH_FLOW_TIMEOUT',
+                message: `OAuth callback timed out after ${Math.round(opts.timeoutMs / 1000)}s.`,
+                hint: 'Re-run the login command and complete the consent screen before the timeout.',
+                context: { port: opts.port, path: opts.path, timeout_ms: opts.timeoutMs },
+            })));
+        }, opts.timeoutMs);
+        timer.unref?.();
+        const onAbort = () => {
+            settle(() => reject(new MoxxyError({
+                code: 'NETWORK_ABORTED',
+                message: 'OAuth flow was aborted.',
+            })));
+        };
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        // A signal that was ALREADY aborted before entry never fires `abort`, so
+        // the listener above won't run — without this guard we'd bind two HTTP
+        // servers and block for the full timeout, ignoring the cancel. (pollUntil
+        // guards the same case.) settle() detaches the listener and skips binding.
+        if (opts.signal?.aborted) {
+            settle(() => reject(new MoxxyError({
+                code: 'NETWORK_ABORTED',
+                message: 'OAuth flow was aborted.',
+            })));
+            return;
+        }
+        const handleRequest = (req, res) => {
+            const url = new URL(req.url ?? '/', `http://localhost:${opts.port}`);
+            if (url.pathname !== opts.path) {
+                res.writeHead(404, { 'Content-Type': 'text/plain' });
+                res.end('not found');
+                return;
+            }
+            const err = url.searchParams.get('error');
+            const errDesc = url.searchParams.get('error_description');
+            if (err) {
+                res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(htmlPage('OAuth error', `${err}${errDesc ? `: ${errDesc}` : ''}`));
+                const denied = err === 'access_denied';
+                settle(() => reject(new MoxxyError({
+                    code: denied ? 'OAUTH_FLOW_DENIED' : 'AUTH_INVALID',
+                    message: denied
+                        ? 'You declined the authorization request.'
+                        : `Authorization server returned an error: ${err}${errDesc ? ` — ${errDesc}` : ''}.`,
+                    ...(denied
+                        ? { hint: 'Re-run the login command and approve the consent screen to continue.' }
+                        : {}),
+                    context: { provider_error: err, ...(errDesc ? { description: errDesc } : {}) },
+                })));
+                return;
+            }
+            const code = url.searchParams.get('code');
+            const returnedState = url.searchParams.get('state');
+            if (!code || !returnedState) {
+                res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(htmlPage('OAuth error', 'callback was missing code or state'));
+                settle(() => reject(new MoxxyError({
+                    code: 'AUTH_INVALID',
+                    message: 'OAuth callback was missing code or state — the upstream redirect is malformed.',
+                    hint: 'Re-run the login command. If this persists, the provider may have rejected the request.',
+                })));
+                return;
+            }
+            if (returnedState !== opts.expectedState) {
+                res.writeHead(400, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(htmlPage('OAuth error', 'state mismatch — possible CSRF, refusing'));
+                settle(() => reject(new MoxxyError({
+                    code: 'OAUTH_FLOW_STATE_MISMATCH',
+                    message: 'OAuth state mismatch — possible CSRF attempt, refusing to continue.',
+                    hint: 'Make sure no other moxxy login is running at the same time, and re-run the command. ' +
+                        'If this keeps happening, your browser or a proxy may be tampering with redirects.',
+                })));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+            res.end(htmlPage('Authorized', 'You can close this window — moxxy received the token.'));
+            settle(() => resolve(code));
+        };
+        const onFatalError = (e) => {
+            if (e.code === 'EADDRINUSE') {
+                settle(() => reject(new MoxxyError({
+                    code: 'OAUTH_FLOW_PORT_BUSY',
+                    message: `OAuth callback port ${opts.port} is already in use.`,
+                    hint: 'Another moxxy login may already be running, or the port is occupied by something else. ' +
+                        `Stop the other process, or set a different port for this provider's redirect.`,
+                    context: { port: opts.port },
+                    cause: e,
+                })));
+                return;
+            }
+            settle(() => reject(MoxxyError.wrap(e, {
+                code: 'INTERNAL',
+                message: `OAuth callback server failed: ${e.message}`,
+            })));
+        };
+        // IPv4 loopback — the required listener; its bind/port errors are fatal.
+        const v4 = createServer(handleRequest);
+        v4.on('error', onFatalError);
+        v4.listen(opts.port, '127.0.0.1');
+        servers.push(v4);
+        // IPv6 loopback — Windows resolves `localhost` to ::1 first, so the
+        // redirect lands here. Best-effort: swallow bind errors (host without IPv6,
+        // or ::1 already bound), since the IPv4 listener above is the guaranteed
+        // path and on such hosts `localhost` is IPv4 anyway.
+        const v6 = createServer(handleRequest);
+        v6.on('error', () => undefined);
+        v6.listen(opts.port, '::1');
+        servers.push(v6);
+    });
+}
+function htmlPage(title, body) {
+    return `<!doctype html><html><head><meta charset="utf-8"><title>${escapeHtml(title)}</title>
+<style>body{font-family:-apple-system,BlinkMacSystemFont,sans-serif;background:#111;color:#eee;display:flex;flex-direction:column;align-items:center;justify-content:center;height:100vh;margin:0}h1{font-weight:300}</style>
+</head><body><h1>${escapeHtml(title)}</h1><p>${escapeHtml(body)}</p></body></html>`;
+}
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : c === '"' ? '&quot;' : '&#39;');
+}
+//# sourceMappingURL=callback-server.js.map

package/dist/oauth/callback-server.js.map

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

package/dist/oauth/device-flow-shared.d.ts

@@ -0,0 +1,39 @@
+import type { PollOutcome } from './poll-until.js';
+import type { TokenSet } from './types.js';
+/**
+ * Parsed RFC 8628 device-authorization response. Times are kept in seconds (as
+ * the wire reports them); callers convert to ms where their API needs it.
+ */
+export interface DeviceAuthorization {
+    readonly deviceCode: string;
+    readonly userCode: string;
+    readonly verificationUri: string;
+    readonly verificationUriComplete?: string;
+    readonly expiresInSec: number;
+    readonly intervalSec: number;
+}
+/**
+ * POST the RFC 8628 device-authorization request and parse the response. The
+ * single home for the request + field parsing + error handling shared by the
+ * legacy `runDeviceCodeFlow` and the `rfc8628DeviceFlow` adapter.
+ */
+export declare function requestDeviceAuthorization(args: {
+    readonly deviceUrl: string;
+    readonly clientId: string;
+    readonly scopes: ReadonlyArray<string>;
+    readonly signal?: AbortSignal;
+}): Promise<DeviceAuthorization>;
+/**
+ * Classify a device-flow token-poll response per RFC 8628 §3.5: success →
+ * `done`; `authorization_pending` → keep waiting; `slow_down` → +5s and wait;
+ * `access_denied` / `expired_token` / other → throw a MoxxyError. Shared by both
+ * poll loops; each caller builds its own request body (the legacy flow appends
+ * client_id/client_secret) and hands the response + parsed JSON here.
+ */
+export declare function classifyDeviceTokenResponse(res: {
+    readonly ok: boolean;
+    readonly status: number;
+}, json: Record<string, unknown>, state: {
+    intervalMs: number;
+}): PollOutcome<TokenSet>;
+//# sourceMappingURL=device-flow-shared.d.ts.map