oauth.do 0.1.13 → 0.1.15

package/dist/index.d.ts

@@ -20,6 +20,12 @@ interface OAuthConfig {
      * Custom fetch implementation
      */
     fetch?: typeof fetch;
+    /**
+     * Custom path for token storage
+     * Supports ~ for home directory (e.g., '~/.studio/tokens.json')
+     * @default '~/.oauth.do/token'
+     */
+    storagePath?: string;
 }
 /**
  * User information returned from auth endpoints
@@ -115,7 +121,7 @@ declare function logout(token?: string): Promise<void>;
  * 1. globalThis.DO_ADMIN_TOKEN / DO_TOKEN (Workers legacy)
  * 2. process.env.DO_ADMIN_TOKEN / DO_TOKEN (Node.js)
  * 3. cloudflare:workers env import (Workers 2025+) - supports secrets store bindings
- * 4. Stored token (keychain/secure file)
+ * 4. Stored token (keychain/secure file) - with automatic refresh if expired
  *
  * @see https://developers.cloudflare.com/changelog/2025-03-17-importable-env/
  */
@@ -163,7 +169,7 @@ declare function configure(config: OAuthConfig): void;
 /**
  * Get current configuration
  */
-declare function getConfig(): Required<OAuthConfig>;
+declare function getConfig(): Omit<Required<OAuthConfig>, 'storagePath'> & Pick<OAuthConfig, 'storagePath'>;
 
 /**
  * OAuth provider options for direct provider login
@@ -192,6 +198,115 @@ declare function authorizeDevice(options?: DeviceAuthOptions): Promise<DeviceAut
  */
 declare function pollForTokens(deviceCode: string, interval?: number, expiresIn?: number): Promise<TokenResponse>;
 
+/**
+ * GitHub Device Flow implementation
+ * Following OAuth 2.0 Device Authorization Grant (RFC 8628)
+ * https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow
+ */
+interface GitHubDeviceFlowOptions {
+    /** GitHub OAuth App client ID */
+    clientId: string;
+    /** OAuth scopes (default: 'user:email read:user') */
+    scope?: string;
+    /** Custom fetch implementation */
+    fetch?: typeof fetch;
+}
+interface GitHubDeviceAuthResponse {
+    /** Device verification code */
+    deviceCode: string;
+    /** User verification code to display */
+    userCode: string;
+    /** Verification URI for user to visit */
+    verificationUri: string;
+    /** Expiration time in seconds */
+    expiresIn: number;
+    /** Polling interval in seconds */
+    interval: number;
+}
+interface GitHubTokenResponse {
+    /** Access token for GitHub API */
+    accessToken: string;
+    /** Token type (typically 'bearer') */
+    tokenType: string;
+    /** Granted scopes */
+    scope: string;
+}
+interface GitHubUser {
+    /** Numeric GitHub user ID (critical for sqid generation) */
+    id: number;
+    /** GitHub username */
+    login: string;
+    /** User's email (may be null if not public) */
+    email: string | null;
+    /** User's display name */
+    name: string | null;
+    /** Avatar image URL */
+    avatarUrl: string;
+}
+/**
+ * Start GitHub Device Flow
+ *
+ * Initiates device authorization flow by requesting device and user codes.
+ *
+ * @param options - Client ID, scope, and optional custom fetch
+ * @returns Device authorization response with codes and URIs
+ *
+ * @example
+ * ```ts
+ * const auth = await startGitHubDeviceFlow({
+ *   clientId: 'Ov23liABCDEFGHIJKLMN',
+ *   scope: 'user:email read:user'
+ * })
+ *
+ * console.log(`Visit ${auth.verificationUri} and enter code: ${auth.userCode}`)
+ * ```
+ */
+declare function startGitHubDeviceFlow(options: GitHubDeviceFlowOptions): Promise<GitHubDeviceAuthResponse>;
+/**
+ * Poll GitHub Device Flow for access token
+ *
+ * Polls GitHub's token endpoint until user completes authorization.
+ * Handles all error states including authorization_pending, slow_down, etc.
+ *
+ * @param deviceCode - Device code from startGitHubDeviceFlow
+ * @param options - Client ID and optional custom fetch
+ * @returns Token response with access token
+ *
+ * @example
+ * ```ts
+ * const auth = await startGitHubDeviceFlow({ clientId: '...' })
+ * // User completes authorization...
+ * const token = await pollGitHubDeviceFlow(auth.deviceCode, {
+ *   clientId: '...',
+ *   interval: auth.interval,
+ *   expiresIn: auth.expiresIn
+ * })
+ * console.log('Access token:', token.accessToken)
+ * ```
+ */
+declare function pollGitHubDeviceFlow(deviceCode: string, options: GitHubDeviceFlowOptions & {
+    interval?: number;
+    expiresIn?: number;
+}): Promise<GitHubTokenResponse>;
+/**
+ * Get GitHub user information
+ *
+ * Fetches authenticated user's profile from GitHub API.
+ *
+ * @param accessToken - GitHub access token
+ * @param options - Optional custom fetch implementation
+ * @returns GitHub user profile
+ *
+ * @example
+ * ```ts
+ * const user = await getGitHubUser(token.accessToken)
+ * console.log(`Logged in as ${user.login} (ID: ${user.id})`)
+ * ```
+ */
+declare function getGitHubUser(accessToken: string, options?: {
+    fetch?: typeof fetch;
+}): Promise<GitHubUser>;
+
 /**
  * Keychain-based token storage using OS credential manager
  * - macOS: Keychain
@@ -228,6 +343,8 @@ declare class SecureFileTokenStorage implements TokenStorage {
     private tokenPath;
     private configDir;
     private initialized;
+    private customPath?;
+    constructor(customPath?: string);
     private init;
     getToken(): Promise<string | null>;
     setToken(token: string): Promise<void>;
@@ -309,8 +426,10 @@ declare class CompositeTokenStorage implements TokenStorage {
  *
  * Note: We use file storage by default because keychain storage on macOS
  * requires GUI authorization popups, which breaks automation and agent workflows.
+ *
+ * @param storagePath - Optional custom path for token storage (e.g., '~/.studio/tokens.json')
  */
-declare function createSecureStorage(): TokenStorage;
+declare function createSecureStorage(storagePath?: string): TokenStorage;
 
 /**
  * CLI-centric login utilities
@@ -352,4 +471,4 @@ declare function forceLogin(options?: LoginOptions): Promise<LoginResult>;
  */
 declare function ensureLoggedOut(options?: LoginOptions): Promise<void>;
 
-export { type AuthProvider, type AuthResult, CompositeTokenStorage, type DeviceAuthorizationResponse, FileTokenStorage, KeychainTokenStorage, LocalStorageTokenStorage, type LoginOptions, type LoginResult, MemoryTokenStorage, type OAuthConfig, type OAuthProvider, SecureFileTokenStorage, type TokenError, type TokenResponse, type TokenStorage, type User, ensureLoggedOut as a, auth, authorizeDevice, buildAuthUrl, configure, createSecureStorage, ensureLoggedIn as e, forceLogin as f, getConfig, getToken, getUser, isAuthenticated, login, logout, pollForTokens };
+export { type AuthProvider, type AuthResult, CompositeTokenStorage, type DeviceAuthorizationResponse, FileTokenStorage, type GitHubDeviceAuthResponse, type GitHubDeviceFlowOptions, type GitHubTokenResponse, type GitHubUser, KeychainTokenStorage, LocalStorageTokenStorage, type LoginOptions, type LoginResult, MemoryTokenStorage, type OAuthConfig, type OAuthProvider, SecureFileTokenStorage, type TokenError, type TokenResponse, type TokenStorage, type User, ensureLoggedOut as a, auth, authorizeDevice, buildAuthUrl, configure, createSecureStorage, ensureLoggedIn as e, forceLogin as f, getConfig, getGitHubUser, getToken, getUser, isAuthenticated, login, logout, pollForTokens, pollGitHubDeviceFlow, startGitHubDeviceFlow };

package/dist/index.js

@@ -26,9 +26,9 @@ function getEnv2(key) {
   if (typeof process !== "undefined" && process.env?.[key]) return process.env[key];
   return void 0;
 }
-function createSecureStorage() {
+function createSecureStorage(storagePath) {
   if (isNode()) {
-    return new SecureFileTokenStorage();
+    return new SecureFileTokenStorage(storagePath);
   }
   if (typeof localStorage !== "undefined") {
     return new LocalStorageTokenStorage();
@@ -133,6 +133,10 @@ var init_storage = __esm({
       tokenPath = null;
       configDir = null;
       initialized = false;
+      customPath;
+      constructor(customPath) {
+        this.customPath = customPath;
+      }
       async init() {
         if (this.initialized) return this.tokenPath !== null;
         this.initialized = true;
@@ -140,8 +144,14 @@ var init_storage = __esm({
         try {
           const os = await import('os');
           const path = await import('path');
-          this.configDir = path.join(os.homedir(), ".oauth.do");
-          this.tokenPath = path.join(this.configDir, "token");
+          if (this.customPath) {
+            const expandedPath = this.customPath.startsWith("~/") ? path.join(os.homedir(), this.customPath.slice(2)) : this.customPath;
+            this.tokenPath = expandedPath;
+            this.configDir = path.dirname(expandedPath);
+          } else {
+            this.configDir = path.join(os.homedir(), ".oauth.do");
+            this.tokenPath = path.join(this.configDir, "token");
+          }
           return true;
         } catch {
           return false;
@@ -376,7 +386,8 @@ var globalConfig = {
   apiUrl: getEnv("OAUTH_API_URL") || getEnv("API_URL") || "https://apis.do",
   clientId: getEnv("OAUTH_CLIENT_ID") || "client_01JQYTRXK9ZPD8JPJTKDCRB656",
   authKitDomain: getEnv("OAUTH_AUTHKIT_DOMAIN") || "login.oauth.do",
-  fetch: globalThis.fetch
+  fetch: globalThis.fetch,
+  storagePath: getEnv("OAUTH_STORAGE_PATH")
 };
 function configure(config) {
   globalConfig = {
@@ -470,6 +481,11 @@ async function logout(token) {
     console.error("Logout error:", error);
   }
 }
+var REFRESH_BUFFER_MS = 5 * 60 * 1e3;
+function isTokenExpired(expiresAt) {
+  if (!expiresAt) return false;
+  return Date.now() >= expiresAt - REFRESH_BUFFER_MS;
+}
 async function getToken() {
   const adminToken = getEnv3("DO_ADMIN_TOKEN");
   if (adminToken) return adminToken;
@@ -485,7 +501,34 @@ async function getToken() {
   }
   try {
     const { createSecureStorage: createSecureStorage2 } = await Promise.resolve().then(() => (init_storage(), storage_exports));
-    const storage = createSecureStorage2();
+    const config = getConfig();
+    const storage = createSecureStorage2(config.storagePath);
+    const tokenData = storage.getTokenData ? await storage.getTokenData() : null;
+    if (tokenData) {
+      if (!isTokenExpired(tokenData.expiresAt)) {
+        return tokenData.accessToken;
+      }
+      if (tokenData.refreshToken) {
+        try {
+          const newTokens = await refreshAccessToken(tokenData.refreshToken);
+          const expiresAt = newTokens.expires_in ? Date.now() + newTokens.expires_in * 1e3 : void 0;
+          const newData = {
+            accessToken: newTokens.access_token,
+            refreshToken: newTokens.refresh_token || tokenData.refreshToken,
+            expiresAt
+          };
+          if (storage.setTokenData) {
+            await storage.setTokenData(newData);
+          } else {
+            await storage.setToken(newTokens.access_token);
+          }
+          return newTokens.access_token;
+        } catch {
+          return null;
+        }
+      }
+      return null;
+    }
     return await storage.getToken();
   } catch {
     return null;
@@ -498,6 +541,28 @@ async function isAuthenticated(token) {
 function auth() {
   return getToken;
 }
+async function refreshAccessToken(refreshToken) {
+  const config = getConfig();
+  if (!config.clientId) {
+    throw new Error("Client ID is required for token refresh");
+  }
+  const response = await config.fetch("https://auth.apis.do/user_management/authenticate", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded"
+    },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: config.clientId
+    }).toString()
+  });
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`Token refresh failed: ${response.status} - ${errorText}`);
+  }
+  return await response.json();
+}
 function buildAuthUrl(options) {
   const config = getConfig();
   const clientId = options.clientId || config.clientId;
@@ -534,7 +599,7 @@ async function authorizeDevice(options = {}) {
       headers: {
         "Content-Type": "application/x-www-form-urlencoded"
       },
-      body
+      body: body.toString()
     });
     if (!response.ok) {
       const errorText = await response.text();
@@ -570,7 +635,7 @@ async function pollForTokens(deviceCode, interval = 5, expiresIn = 600) {
           grant_type: "urn:ietf:params:oauth:grant-type:device_code",
           device_code: deviceCode,
           client_id: config.clientId
-        })
+        }).toString()
       });
       if (response.ok) {
         const data = await response.json();
@@ -600,9 +665,138 @@ async function pollForTokens(deviceCode, interval = 5, expiresIn = 600) {
   }
 }
 
+// src/github-device.ts
+async function startGitHubDeviceFlow(options) {
+  const { clientId, scope = "user:email read:user" } = options;
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (!clientId) {
+    throw new Error("GitHub client ID is required for device authorization");
+  }
+  try {
+    const url = "https://github.com/login/device/code";
+    const body = new URLSearchParams({
+      client_id: clientId,
+      scope
+    });
+    const response = await fetchImpl(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "Accept": "application/json"
+      },
+      body
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`GitHub device authorization failed: ${response.statusText} - ${errorText}`);
+    }
+    const data = await response.json();
+    return {
+      deviceCode: data.device_code,
+      userCode: data.user_code,
+      verificationUri: data.verification_uri,
+      expiresIn: data.expires_in,
+      interval: data.interval
+    };
+  } catch (error) {
+    console.error("GitHub device authorization error:", error);
+    throw error;
+  }
+}
+async function pollGitHubDeviceFlow(deviceCode, options) {
+  const { clientId, interval = 5, expiresIn = 900 } = options;
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (!clientId) {
+    throw new Error("GitHub client ID is required for token polling");
+  }
+  const startTime = Date.now();
+  const timeout = expiresIn * 1e3;
+  let currentInterval = interval * 1e3;
+  while (true) {
+    if (Date.now() - startTime > timeout) {
+      throw new Error("GitHub device authorization expired. Please try again.");
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentInterval));
+    try {
+      const url = "https://github.com/login/oauth/access_token";
+      const body = new URLSearchParams({
+        client_id: clientId,
+        device_code: deviceCode,
+        grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+      });
+      const response = await fetchImpl(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          "Accept": "application/json"
+        },
+        body
+      });
+      const data = await response.json();
+      if ("access_token" in data) {
+        return {
+          accessToken: data.access_token,
+          tokenType: data.token_type,
+          scope: data.scope
+        };
+      }
+      const error = data.error || "unknown";
+      switch (error) {
+        case "authorization_pending":
+          continue;
+        case "slow_down":
+          currentInterval += 5e3;
+          continue;
+        case "access_denied":
+          throw new Error("Access denied by user");
+        case "expired_token":
+          throw new Error("Device code expired");
+        default:
+          throw new Error(`GitHub token polling failed: ${error}`);
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        throw error;
+      }
+      continue;
+    }
+  }
+}
+async function getGitHubUser(accessToken, options = {}) {
+  const fetchImpl = options.fetch || globalThis.fetch;
+  if (!accessToken) {
+    throw new Error("GitHub access token is required");
+  }
+  try {
+    const response = await fetchImpl("https://api.github.com/user", {
+      method: "GET",
+      headers: {
+        "Authorization": `Bearer ${accessToken}`,
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28"
+      }
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`GitHub user fetch failed: ${response.statusText} - ${errorText}`);
+    }
+    const data = await response.json();
+    return {
+      id: data.id,
+      login: data.login,
+      email: data.email,
+      name: data.name,
+      avatarUrl: data.avatar_url
+    };
+  } catch (error) {
+    console.error("GitHub user fetch error:", error);
+    throw error;
+  }
+}
+
 // src/index.ts
 init_storage();
 
-export { CompositeTokenStorage, FileTokenStorage, KeychainTokenStorage, LocalStorageTokenStorage, MemoryTokenStorage, SecureFileTokenStorage, auth, authorizeDevice, buildAuthUrl, configure, createSecureStorage, getConfig, getToken, getUser, isAuthenticated, login, logout, pollForTokens };
+export { CompositeTokenStorage, FileTokenStorage, KeychainTokenStorage, LocalStorageTokenStorage, MemoryTokenStorage, SecureFileTokenStorage, auth, authorizeDevice, buildAuthUrl, configure, createSecureStorage, getConfig, getGitHubUser, getToken, getUser, isAuthenticated, login, logout, pollForTokens, pollGitHubDeviceFlow, startGitHubDeviceFlow };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map