@levr-one/auth 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @levr-one/auth - Shared OAuth 2.1 client with self-healing token management
+ *
+ * This package provides:
+ * - OAuthClient: OAuth 2.1 with PKCE for authorization flow
+ * - TokenWatcher: Self-healing token file watching
+ * - Token storage utilities with atomic writes
+ *
+ * Usage in MCP servers:
+ *
+ * ```typescript
+ * import { OAuthClient, TokenWatcher } from '@levr-one/auth';
+ *
+ * // Initialize OAuth client
+ * const oauth = new OAuthClient({ clientId: 'my-client' });
+ *
+ * // Start token watcher for self-healing
+ * const watcher = new TokenWatcher();
+ * watcher.onTokenChange((tokens) => {
+ *   if (tokens) {
+ *     oauth.setTokensFromStorage(tokens);
+ *   }
+ * });
+ * watcher.start();
+ * ```
+ */
+export type { TokenResponse, StoredTokens, OAuthConfig, AuthStatus, TokenChangeCallback, DeviceAuthorizationResponse, } from './types.js';
+export { loadTokens, loadTokensForEnv, loadTokensForUrl, saveTokens, saveTokensForEnv, clearTokens, restoreTokensFromBackup, hasStoredTokens, getTokenFilePath, getTqDir, resolveEnvFromUrl, resolveUrlFromEnv, } from './token-store.js';
+export type { EnvName } from './token-store.js';
+export { loadWorkspace, saveWorkspace, clearWorkspace, getWorkspaceFilePath, loadIdentityCache, saveIdentityCache, } from './workspace-store.js';
+export type { IdentityCache } from './workspace-store.js';
+export { loadConfig, writeConfig, getConfigFilePath, resolveFromApiUrl, PRESETS, } from './config.js';
+export type { TqConfig } from './config.js';
+export { OAuthClient } from './oauth-client.js';
+export { listWorkspaces, WorkspaceFetchError } from './workspaces.js';
+export type { WorkspaceSite, WorkspaceFetchErrorCode } from './workspaces.js';
+export { acquireFileLock, getLockPath } from './file-lock.js';
+export type { FileLockHandle } from './file-lock.js';
+export { TokenWatcher } from './token-watcher.js';
+export type { TokenWatcherOptions } from './token-watcher.js';
+export { ConfigWatcher } from './config-watcher.js';
+export type { ConfigWatcherOptions, ConfigChangeCallback, } from './config-watcher.js';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,YAAY,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,EACV,mBAAmB,EACnB,2BAA2B,GAC5B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,uBAAuB,EACvB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,EACL,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtE,YAAY,EAAE,aAAa,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAG9E,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAGrD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAG9D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EACV,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC"}

package/dist/index.js

@@ -0,0 +1,43 @@
+/**
+ * @levr-one/auth - Shared OAuth 2.1 client with self-healing token management
+ *
+ * This package provides:
+ * - OAuthClient: OAuth 2.1 with PKCE for authorization flow
+ * - TokenWatcher: Self-healing token file watching
+ * - Token storage utilities with atomic writes
+ *
+ * Usage in MCP servers:
+ *
+ * ```typescript
+ * import { OAuthClient, TokenWatcher } from '@levr-one/auth';
+ *
+ * // Initialize OAuth client
+ * const oauth = new OAuthClient({ clientId: 'my-client' });
+ *
+ * // Start token watcher for self-healing
+ * const watcher = new TokenWatcher();
+ * watcher.onTokenChange((tokens) => {
+ *   if (tokens) {
+ *     oauth.setTokensFromStorage(tokens);
+ *   }
+ * });
+ * watcher.start();
+ * ```
+ */
+// Token storage (with atomic writes, map keyed by backend URL)
+export { loadTokens, loadTokensForEnv, loadTokensForUrl, saveTokens, saveTokensForEnv, clearTokens, restoreTokensFromBackup, hasStoredTokens, getTokenFilePath, getTqDir, resolveEnvFromUrl, resolveUrlFromEnv, } from './token-store.js';
+// Workspace storage
+export { loadWorkspace, saveWorkspace, clearWorkspace, getWorkspaceFilePath, loadIdentityCache, saveIdentityCache, } from './workspace-store.js';
+// Unified environment config
+export { loadConfig, writeConfig, getConfigFilePath, resolveFromApiUrl, PRESETS, } from './config.js';
+// OAuth client
+export { OAuthClient } from './oauth-client.js';
+// Workspace listing (public library surface)
+export { listWorkspaces, WorkspaceFetchError } from './workspaces.js';
+// File lock (cross-process refresh coordination)
+export { acquireFileLock, getLockPath } from './file-lock.js';
+// Token watcher (self-healing core)
+export { TokenWatcher } from './token-watcher.js';
+// Config watcher (environment change detection)
+export { ConfigWatcher } from './config-watcher.js';
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAYH,+DAA+D;AAC/D,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EAChB,WAAW,EACX,uBAAuB,EACvB,eAAe,EACf,gBAAgB,EAChB,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,oBAAoB;AACpB,OAAO,EACL,aAAa,EACb,aAAa,EACb,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAG9B,6BAA6B;AAC7B,OAAO,EACL,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,OAAO,GACR,MAAM,aAAa,CAAC;AAGrB,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,6CAA6C;AAC7C,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAGtE,iDAAiD;AACjD,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG9D,oCAAoC;AACpC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGlD,gDAAgD;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/oauth-client.d.ts

@@ -0,0 +1,156 @@
+/**
+ * OAuth 2.0 client for TQ MCP servers
+ * Implements authorization code flow with PKCE (RFC 7636)
+ */
+import type { OAuthConfig, StoredTokens } from './types.js';
+export declare class OAuthClient {
+    private config;
+    private accessToken;
+    private refreshToken;
+    private expiresAt;
+    private consecutiveRefreshFailures;
+    /**
+     * Set when refresh is definitively rejected (400/401).
+     * Prevents further network refresh attempts until re-authorization
+     * or fresh tokens are loaded via setTokensFromStorage/authorize.
+     */
+    private refreshRejected;
+    /**
+     * Deduplicates concurrent refresh calls. When multiple callers invoke
+     * refresh() simultaneously (e.g., parallel MCP tool requests), they
+     * all await the same in-flight promise instead of each firing a
+     * separate token rotation request — which would cause the second
+     * request to fail with invalid_grant (token already revoked by first).
+     */
+    private refreshPromise;
+    constructor(config: Partial<OAuthConfig> & {
+        clientId: string;
+    });
+    /**
+     * Load tokens from persistent storage
+     */
+    private loadStoredTokens;
+    /**
+     * Set tokens from external storage (used during initialization)
+     */
+    setTokensFromStorage(tokens: StoredTokens): void;
+    /**
+     * Generate PKCE code verifier and challenge
+     * @see https://datatracker.ietf.org/doc/html/rfc7636
+     */
+    private generatePKCE;
+    /**
+     * Start local HTTP server to receive OAuth callback
+     */
+    private waitForCallback;
+    /**
+     * Perform full OAuth authorization flow
+     * Opens browser for user to authorize, waits for callback
+     */
+    authorize(): Promise<void>;
+    /**
+     * Perform OAuth 2.0 Device Authorization Grant (RFC 8628).
+     * Works in headless/remote terminals — no browser redirect needed.
+     * Displays a URL and code for the user to authorize on any device.
+     */
+    authorizeDevice(): Promise<void>;
+    /**
+     * Exchange authorization code for access and refresh tokens
+     */
+    private exchangeCode;
+    /**
+     * Refresh access token using refresh token.
+     *
+     * Two layers of coordination:
+     *   1. In-process: `refreshPromise` dedups concurrent callers within
+     *      this OAuthClient instance.
+     *   2. Cross-process: a file lock keyed on apiBaseUrl serializes
+     *      refreshes across MCP server processes. On lock acquire, we
+     *      re-read the on-disk token — if another process already
+     *      refreshed while we waited, adopt their tokens and skip the
+     *      network call. This avoids the "N processes all POST with the
+     *      same refresh_token, all but one get invalid_grant" race that
+     *      would otherwise exhaust consecutiveRefreshFailures and trigger
+     *      clearTokens().
+     */
+    refresh(): Promise<void>;
+    /**
+     * Acquire the cross-process refresh lock, re-check disk state, and
+     * either adopt freshly-rotated tokens from disk or call the refresh
+     * endpoint. Always releases the lock.
+     */
+    private refreshWithLock;
+    /**
+     * Internal refresh implementation — called only once per dedup window.
+     * All concurrent callers share the same promise via refresh().
+     */
+    private refreshInternal;
+    /**
+     * Store tokens in memory and persist to disk.
+     *
+     * Non-refresh grants (authorization_code, device_code, password) carry
+     * `tokens.user.workspace_id` — the workspace the user just logged into.
+     * Refresh grants omit it. When present we persist it to ~/.tq/workspace.json
+     * so MCP clients pick up the selected workspace without a separate round-trip.
+     */
+    private setTokens;
+    /**
+     * Get a valid access token, refreshing if needed
+     * Note: Does NOT auto-authorize - throws if no tokens available
+     */
+    getAccessToken(): Promise<string>;
+    /**
+     * Get access token without auto-refresh (for checking current state)
+     */
+    getAccessTokenSync(): string | null;
+    /**
+     * Check if client has valid tokens
+     */
+    isAuthorized(): boolean;
+    /**
+     * Check if tokens exist (may be expired)
+     */
+    hasTokens(): boolean;
+    /**
+     * Attempt a proactive (background) refresh without accumulating toward
+     * the nuclear clearTokens() threshold. If refresh fails, the failure
+     * counter is reset so background timer ticks can never delete the
+     * token file. Only critical-path refreshes (from getAccessToken /
+     * ensureAuth) should count toward the threshold.
+     *
+     * @returns true if refresh succeeded, false otherwise
+     */
+    refreshProactive(): Promise<boolean>;
+    /**
+     * Clear all tokens (logout). Also clears the persisted workspace selection
+     * so the next login starts from a clean state on shared machines.
+     */
+    clearTokens(): void;
+    /**
+     * Get token expiration time
+     */
+    getExpiresAt(): number;
+    /**
+     * Get current refresh token (for storage)
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Get time until expiration in milliseconds
+     */
+    getTimeUntilExpiry(): number;
+    /**
+     * Check if token is expiring soon (within given minutes)
+     */
+    isExpiringSoon(withinMinutes?: number): boolean;
+    /**
+     * Check if refresh was definitively rejected (token revoked/invalid).
+     * When true, no further refresh attempts will be made until
+     * re-authorization or fresh tokens are loaded.
+     */
+    isRefreshRejected(): boolean;
+    /**
+     * Reload tokens from storage (useful after external refresh)
+     */
+    reloadTokens(): void;
+}
+//# sourceMappingURL=oauth-client.d.ts.map

package/dist/oauth-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-client.d.ts","sourceRoot":"","sources":["../src/oauth-client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH,OAAO,KAAK,EAEV,WAAW,EACX,YAAY,EAEb,MAAM,YAAY,CAAC;AAYpB,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,0BAA0B,CAAa;IAC/C;;;;OAIG;IACH,OAAO,CAAC,eAAe,CAAkB;IACzC;;;;;;OAMG;IACH,OAAO,CAAC,cAAc,CAA8B;gBAExC,MAAM,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE;IAkB/D;;OAEG;IACH,OAAO,CAAC,gBAAgB;IASxB;;OAEG;IACH,oBAAoB,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAQhD;;;OAGG;IACH,OAAO,CAAC,YAAY;IAapB;;OAEG;YACW,eAAe;IAkF7B;;;OAGG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAsChC;;;;OAIG;IACG,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAkFtC;;OAEG;YACW,YAAY;IAgC1B;;;;;;;;;;;;;;OAcG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC9B;;;;OAIG;YACW,eAAe;IA+C7B;;;OAGG;YACW,eAAe;IAyE7B;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAuBjB;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAoBvC;;OAEG;IACH,kBAAkB,IAAI,MAAM,GAAG,IAAI;IAInC;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;;;;;;;OAQG;IACG,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAY1C;;;OAGG;IACH,WAAW,IAAI,IAAI;IAQnB;;OAEG;IACH,YAAY,IAAI,MAAM;IAItB;;OAEG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;OAEG;IACH,cAAc,CAAC,aAAa,GAAE,MAAU,GAAG,OAAO;IAMlD;;;;OAIG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;OAEG;IACH,YAAY,IAAI,IAAI;CAGrB"}