oauth.do 0.1.12 → 0.1.14

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
@@ -163,15 +169,25 @@ 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
+ * Bypasses AuthKit login screen and goes directly to the provider
+ */
+type OAuthProvider = 'GitHubOAuth' | 'GoogleOAuth' | 'MicrosoftOAuth' | 'AppleOAuth';
+interface DeviceAuthOptions {
+    /** OAuth provider to use directly (bypasses AuthKit login screen) */
+    provider?: OAuthProvider;
+}
 /**
  * Initiate device authorization flow
  * Following OAuth 2.0 Device Authorization Grant (RFC 8628)
  *
+ * @param options - Optional settings including provider for direct OAuth
  * @returns Device authorization response with codes and URIs
  */
-declare function authorizeDevice(): Promise<DeviceAuthorizationResponse>;
+declare function authorizeDevice(options?: DeviceAuthOptions): Promise<DeviceAuthorizationResponse>;
 /**
  * Poll for tokens after device authorization
  *
@@ -182,6 +198,115 @@ declare function authorizeDevice(): Promise<DeviceAuthorizationResponse>;
  */
 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
@@ -218,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>;
@@ -299,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
@@ -312,6 +441,8 @@ interface LoginOptions {
     openBrowser?: boolean;
     /** Custom print function for output */
     print?: (message: string) => void;
+    /** OAuth provider to use directly (bypasses AuthKit login screen) */
+    provider?: OAuthProvider;
     /** Storage to use (default: createSecureStorage()) */
     storage?: {
         getToken: () => Promise<string | null>;
@@ -340,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, 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 = {
@@ -485,7 +496,8 @@ 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);
     return await storage.getToken();
   } catch {
     return null;
@@ -515,7 +527,7 @@ function buildAuthUrl(options) {
 }
 
 // src/device.ts
-async function authorizeDevice() {
+async function authorizeDevice(options = {}) {
   const config = getConfig();
   if (!config.clientId) {
     throw new Error('Client ID is required for device authorization. Set OAUTH_CLIENT_ID or configure({ clientId: "..." })');
@@ -526,12 +538,15 @@ async function authorizeDevice() {
       client_id: config.clientId,
       scope: "openid profile email"
     });
+    if (options.provider) {
+      body.set("provider", options.provider);
+    }
     const response = await config.fetch(url, {
       method: "POST",
       headers: {
         "Content-Type": "application/x-www-form-urlencoded"
       },
-      body
+      body: body.toString()
     });
     if (!response.ok) {
       const errorText = await response.text();
@@ -567,7 +582,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();
@@ -597,9 +612,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