binoauth 0.0.11 → 0.0.12

package/dist/core/src/oauth/client.d.ts

@@ -0,0 +1,322 @@
+import type { AuthConfig, BinoAuthConfig, StorageConfig, User, DeviceCodeResponse } from "./types";
+import { TokenStorage } from "./storage";
+/**
+ * BinoAuth OAuth 2.0 Client
+ *
+ * A comprehensive OAuth 2.0 client that supports multiple grant types
+ * including Authorization Code, Device Code, Client Credentials, and Refresh Token flows.
+ *
+ * Features:
+ * - Automatic token refresh and management
+ * - PKCE support for secure authentication
+ * - Device authorization for IoT and limited-input devices
+ * - Server-to-server authentication with client credentials
+ * - Secure token storage with encryption
+ * - Rate limiting and CSRF protection
+ *
+ * @example
+ * ```typescript
+ * import { BinoAuthOAuth, InMemoryTokenStorage } from 'binoauth';
+ *
+ * // Simple configuration using issuer
+ * const client = new BinoAuthOAuth({
+ *   issuer: 'https://auth.binoauth.com',
+ *   clientId: 'your_client_id',
+ *   redirectUri: 'https://yourapp.com/callback',
+ *   scope: 'openid profile email'
+ * }, {
+ *   storage: new InMemoryTokenStorage(),
+ *   clientId: 'your_client_id'
+ * });
+ *
+ * // Authorization Code Flow (for web/mobile apps)
+ * const loginUrl = await client.getLoginUrl();
+ * window.location.href = loginUrl;
+ *
+ * // Handle callback after user returns
+ * const urlParams = new URLSearchParams(window.location.search);
+ * await client.handleCallback(
+ *   urlParams.get('code')!,
+ *   urlParams.get('state')!
+ * );
+ *
+ * // Check authentication status
+ * const isLoggedIn = await client.isAuthenticated();
+ * if (isLoggedIn) {
+ *   const userInfo = await client.getUserInfo();
+ *   console.log('Logged in as:', userInfo.email);
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Device Code Flow (for TVs, IoT devices, CLI tools)
+ * const deviceAuth = await client.requestDeviceCode();
+ * console.log(`Visit: ${deviceAuth.verification_uri}`);
+ * console.log(`Enter code: ${deviceAuth.user_code}`);
+ *
+ * // Poll for authorization
+ * const pollInterval = deviceAuth.interval * 1000;
+ * while (true) {
+ *   try {
+ *     await client.pollForToken(deviceAuth.device_code);
+ *     console.log('Device authorized successfully!');
+ *     break;
+ *   } catch (error) {
+ *     if (error.code === 'authorization_pending') {
+ *       await new Promise(resolve => setTimeout(resolve, pollInterval));
+ *       continue;
+ *     }
+ *     throw error;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Client Credentials Flow (for server-to-server)
+ * client.initializeClientCredentials('your_client_secret');
+ * await client.getClientCredentialsTokens();
+ *
+ * // Use token for API calls
+ * const accessToken = await client.getAccessToken();
+ * const response = await fetch('/api/protected', {
+ *   headers: { 'Authorization': `Bearer ${accessToken}` }
+ * });
+ * ```
+ */
+export declare class BinoAuthOAuth {
+    private config;
+    private storage;
+    private oauthApi?;
+    private authCodeFlow;
+    private refreshFlow;
+    private deviceFlow;
+    private clientCredentialsFlow?;
+    /**
+     * Creates a new BinoAuth OAuth client
+     *
+     * @param config - OAuth configuration (can use simplified BinoAuthConfig with issuer)
+     * @param storageConfig - Token storage configuration
+     *
+     * @example
+     * ```typescript
+     * // Simple configuration with issuer
+     * const client = new BinoAuthOAuth({
+     *   issuer: 'https://auth.binoauth.com',
+     *   clientId: 'your_client_id',
+     *   redirectUri: 'https://yourapp.com/callback'
+     * }, {
+     *   storage: new InMemoryTokenStorage(),
+     *   clientId: 'your_client_id'
+     * });
+     *
+     * // Full configuration
+     * const client = new BinoAuthOAuth({
+     *   clientId: 'your_client_id',
+     *   redirectUri: 'https://yourapp.com/callback',
+     *   authorizeEndpoint: 'https://auth.binoauth.com/api/v1/oauth/authorize',
+     *   tokenEndpoint: 'https://auth.binoauth.com/api/v1/oauth/token',
+     *   userInfoEndpoint: 'https://auth.binoauth.com/api/v1/oauth/userinfo'
+     * }, storageConfig);
+     * ```
+     */
+    constructor(config: BinoAuthConfig | AuthConfig, storageConfig: StorageConfig);
+    /**
+     * Initializes client credentials flow for server-to-server authentication
+     *
+     * @param clientSecret - The client secret for authentication
+     *
+     * @example
+     * ```typescript
+     * client.initializeClientCredentials('your_client_secret');
+     * await client.getClientCredentialsTokens();
+     * ```
+     */
+    initializeClientCredentials(clientSecret: string): void;
+    /**
+     * Updates the token storage instance
+     *
+     * @param tokenStorage - New token storage instance
+     */
+    setTokenStorage(tokenStorage: TokenStorage): void;
+    /**
+     * Gets the current token storage instance
+     *
+     * @returns The current token storage
+     */
+    getTokenStorage(): TokenStorage;
+    /**
+     * Generates the authorization URL for the OAuth flow
+     *
+     * @returns Promise resolving to the authorization URL
+     *
+     * @example
+     * ```typescript
+     * const loginUrl = await client.getLoginUrl();
+     * window.location.href = loginUrl; // Redirect user to BinoAuth
+     * ```
+     */
+    getLoginUrl(): Promise<string>;
+    /**
+     * Handles the OAuth callback and exchanges code for tokens
+     *
+     * @param code - Authorization code from callback
+     * @param state - State parameter from callback
+     *
+     * @example
+     * ```typescript
+     * const urlParams = new URLSearchParams(window.location.search);
+     * await client.handleCallback(
+     *   urlParams.get('code')!,
+     *   urlParams.get('state')!
+     * );
+     * ```
+     */
+    handleCallback(code: string, state: string): Promise<void>;
+    /**
+     * Generates the logout URL
+     *
+     * @returns Promise resolving to the logout URL
+     */
+    getLogoutUrl(): Promise<string>;
+    /**
+     * Generates the logout page URL with optional return URL
+     *
+     * @param returnTo - Optional URL to redirect to after logout
+     * @returns Promise resolving to the logout page URL
+     */
+    getLogoutPageUrl(returnTo?: string): Promise<string>;
+    /**
+     * Initiates device authorization flow
+     *
+     * @returns Promise resolving to device authorization response
+     *
+     * @example
+     * ```typescript
+     * const deviceAuth = await client.requestDeviceCode();
+     * console.log(`Visit: ${deviceAuth.verification_uri}`);
+     * console.log(`Enter code: ${deviceAuth.user_code}`);
+     * ```
+     */
+    requestDeviceCode(): Promise<DeviceCodeResponse>;
+    /**
+     * Polls for token using device code
+     *
+     * @param deviceCode - Device code from requestDeviceCode()
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await client.pollForToken(deviceAuth.device_code);
+     *   console.log('Device authorized!');
+     * } catch (error) {
+     *   if (error.code === 'authorization_pending') {
+     *     // User hasn't entered code yet, continue polling
+     *   }
+     * }
+     * ```
+     */
+    pollForToken(deviceCode: string): Promise<void>;
+    /**
+     * Requests tokens using client credentials flow
+     *
+     * @example
+     * ```typescript
+     * client.initializeClientCredentials('your_client_secret');
+     * await client.getClientCredentialsTokens();
+     *
+     * const accessToken = await client.getAccessToken();
+     * // Use token for server-to-server API calls
+     * ```
+     *
+     * @throws {AuthError} When client credentials flow is not initialized
+     */
+    getClientCredentialsTokens(): Promise<void>;
+    /**
+     * Gets a valid access token, automatically refreshing if needed
+     *
+     * @returns Promise resolving to access token or null if not authenticated
+     *
+     * @example
+     * ```typescript
+     * const accessToken = await client.getAccessToken();
+     * if (accessToken) {
+     *   const response = await fetch('/api/protected', {
+     *     headers: { 'Authorization': `Bearer ${accessToken}` }
+     *   });
+     * }
+     * ```
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Manually refreshes access tokens using refresh token
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await client.refreshTokens();
+     *   console.log('Tokens refreshed successfully');
+     * } catch (error) {
+     *   console.log('Token refresh failed:', error.message);
+     * }
+     * ```
+     */
+    refreshTokens(): Promise<void>;
+    /**
+     * Fetches authenticated user information
+     *
+     * @returns Promise resolving to user info or null if not authenticated
+     *
+     * @example
+     * ```typescript
+     * const userInfo = await client.getUserInfo();
+     * if (userInfo) {
+     *   console.log(`Welcome, ${userInfo.name}!`);
+     *   console.log(`Email: ${userInfo.email}`);
+     * }
+     * ```
+     *
+     * @throws {AuthError} When userInfoEndpoint is missing from config
+     */
+    getUserInfo(): Promise<User | null>;
+    /**
+     * Checks if the user is currently authenticated
+     *
+     * Automatically attempts token refresh if access token is expired
+     * but refresh token is still valid.
+     *
+     * @returns Promise resolving to true if authenticated, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (await client.isAuthenticated()) {
+     *   // User is logged in, show authenticated content
+     *   const userInfo = await client.getUserInfo();
+     * } else {
+     *   // User needs to log in
+     *   const loginUrl = await client.getLoginUrl();
+     *   window.location.href = loginUrl;
+     * }
+     * ```
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * Logs out the user and revokes tokens
+     *
+     * Attempts to revoke tokens on the server if revoke endpoint is configured,
+     * then clears local token storage.
+     *
+     * @example
+     * ```typescript
+     * await client.logout();
+     * console.log('User logged out successfully');
+     *
+     * // Redirect to login page
+     * const loginUrl = await client.getLoginUrl();
+     * window.location.href = loginUrl;
+     * ```
+     */
+    logout(): Promise<void>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/core/src/oauth/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../../src/oauth/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,aAAa,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAEnG,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AASzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,QAAQ,CAAC,CAAY;IAC7B,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,WAAW,CAAmB;IACtC,OAAO,CAAC,UAAU,CAAiB;IACnC,OAAO,CAAC,qBAAqB,CAAC,CAAwB;IAEtD;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;gBACS,MAAM,EAAE,cAAc,GAAG,UAAU,EAAE,aAAa,EAAE,aAAa;IA2B7E;;;;;;;;;;OAUG;IACH,2BAA2B,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAQvD;;;;OAIG;IACH,eAAe,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAIjD;;;;OAIG;IACH,eAAe,IAAI,YAAY;IAM/B;;;;;;;;;;OAUG;IACG,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC;IAIpC;;;;;;;;;;;;;;OAcG;IACG,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhE;;;;OAIG;IACG,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAIrC;;;;;OAKG;IACG,gBAAgB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAM1D;;;;;;;;;;;OAWG;IACG,iBAAiB,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAItD;;;;;;;;;;;;;;;;OAgBG;IACG,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMrD;;;;;;;;;;;;;OAaG;IACG,0BAA0B,IAAI,OAAO,CAAC,IAAI,CAAC;IAYjD;;;;;;;;;;;;;;OAcG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAkB9C;;;;;;;;;;;;OAYG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAMpC;;;;;;;;;;;;;;;OAeG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC;IA4CzC;;;;;;;;;;;;;;;;;;;OAmBG;IACG,eAAe,IAAI,OAAO,CAAC,OAAO,CAAC;IAuBzC;;;;;;;;;;;;;;;OAeG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CA0C9B"}