netreq-auth 0.1.1

package/README.md

@@ -0,0 +1,191 @@
+# @netreq/auth
+
+JWT authentication plugin for netreq. Handles tokens, auto-refresh, and storage.
+
+## Install
+
+```bash
+npm install @netreq/auth
+```
+
+## Quick Start
+
+```typescript
+import { createClient } from 'netreq';
+import { Auth, WebStorage } from '@netreq/auth';
+
+const auth = new Auth({
+  storage: new WebStorage('localStorage'),
+  refreshEndpoint: '/api/auth/refresh',
+  onSessionExpired: () => {
+    window.location.href = '/login';
+  }
+});
+
+const client = createClient({
+  baseUrl: 'https://api.example.com'
+});
+
+client.use(auth.middleware());
+
+// Login
+await auth.login('/api/auth/login', {
+  email: 'user@example.com',
+  password: 'secret'
+});
+
+// All requests now include Authorization header
+// 401 responses trigger automatic token refresh
+const user = await client.get('/me');
+```
+
+## How It Works
+
+1. **Auto Header Injection** - Adds `Authorization: Bearer <token>` to every request
+2. **Token Refresh** - On 401 error, automatically refreshes token and retries the request
+3. **Request Queue** - While refreshing, other requests wait in queue. After refresh, all retry with new token.
+4. **Storage Adapter** - Tokens persist in localStorage/sessionStorage/memory/cookies
+
+## Storage Options
+
+```typescript
+import { Auth, MemoryStorage, WebStorage, CookieStorage } from '@netreq/auth';
+
+// Browser with persistence
+const auth = new Auth({
+  storage: new WebStorage('localStorage', 'myapp_tokens'),
+  refreshEndpoint: '/api/auth/refresh'
+});
+
+// Server-side / SSR
+const auth = new Auth({
+  storage: new MemoryStorage(),
+  refreshEndpoint: '/api/auth/refresh'
+});
+
+// Cookies
+const auth = new Auth({
+  storage: new CookieStorage({
+    name: 'auth',
+    secure: true,
+    sameSite: 'strict'
+  }),
+  refreshEndpoint: '/api/auth/refresh'
+});
+```
+
+## Configuration
+
+```typescript
+const auth = new Auth({
+  // Required
+  refreshEndpoint: '/api/auth/refresh',
+  
+  // Optional
+  storage: new WebStorage('localStorage'),
+  refreshMethod: 'POST',
+  authHeaderName: 'Authorization',
+  tokenPrefix: 'Bearer ',
+  maxRefreshRetries: 3,
+  refreshTimeout: 10000,
+  
+  // Transform refresh request/response
+  buildRefreshBody: (refreshToken) => ({ token: refreshToken }),
+  extractTokenPair: (response) => ({
+    accessToken: response.data.access_token,
+    refreshToken: response.data.refresh_token
+  }),
+  
+  // Events
+  onLogin: () => console.log('Logged in'),
+  onLogout: () => console.log('Logged out'),
+  onTokenRefreshed: () => console.log('Token refreshed'),
+  onSessionExpired: () => {
+    // Redirect to login
+    window.location.href = '/login';
+  }
+});
+```
+
+## API Methods
+
+```typescript
+// Check auth status
+auth.isAuthenticated(); // boolean
+auth.getAccessToken();  // string | null
+
+// Manual login/logout
+await auth.login('/api/login', { email, password });
+await auth.logout();
+
+// Manual token management
+await auth.setTokens({
+  accessToken: 'xxx',
+  refreshToken: 'yyy'
+});
+```
+
+## Custom Storage
+
+```typescript
+import type { TokenStorage, TokenPair } from '@netreq/auth';
+
+class EncryptedStorage implements TokenStorage {
+  async getTokens(): Promise<TokenPair | null> {
+    const encrypted = localStorage.getItem('tokens');
+    return encrypted ? decrypt(encrypted) : null;
+  }
+  
+  async setTokens(tokens: TokenPair): Promise<void> {
+    localStorage.setItem('tokens', encrypt(tokens));
+  }
+  
+  async clearTokens(): Promise<void> {
+    localStorage.removeItem('tokens');
+  }
+}
+
+const auth = new Auth({
+  storage: new EncryptedStorage(),
+  refreshEndpoint: '/api/auth/refresh'
+});
+```
+
+## React Example
+
+See [examples/react-integration.ts](examples/react-integration.ts) for full Context API setup.
+
+```typescript
+// AuthProvider.tsx
+const auth = new Auth({
+  storage: new WebStorage('localStorage'),
+  refreshEndpoint: '/api/auth/refresh'
+});
+
+client.use(auth.middleware());
+
+export function AuthProvider({ children }) {
+  const [user, setUser] = useState(null);
+  
+  const login = async (email, password) => {
+    await auth.login('/api/login', { email, password });
+    const res = await client.get('/me');
+    setUser(res.data);
+  };
+  
+  return (
+    <AuthContext.Provider value={{ user, login }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+```
+
+## Requirements
+
+- Node.js 18+
+- netreq 0.1.0+
+
+## License
+
+MIT

package/dist/Auth.d.ts

@@ -0,0 +1,180 @@
+/**
+ * @fileoverview Authentication plugin for netreq.
+ * Provides automatic token injection, seamless token refresh with queue management,
+ * and session state events.
+ */
+import type { AuthPluginOptions, TokenPair, LoginCredentials, LoginResult } from './types.js';
+/**
+ * Authentication plugin for netreq HTTP client.
+ *
+ * This plugin provides:
+ * 1. Automatic Authorization header injection
+ * 2. Seamless token refresh with mutex/queue pattern
+ * 3. Flexible storage adapters
+ * 4. Session state events
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from 'netreq';
+ * import { Auth, WebStorage } from '@netreq/auth';
+ *
+ * const auth = new Auth({
+ *   storage: new WebStorage('localStorage'),
+ *   refreshEndpoint: '/auth/refresh',
+ *   onSessionExpired: () => {
+ *     window.location.href = '/login';
+ *   }
+ * });
+ *
+ * const client = createClient({
+ *   baseUrl: 'https://api.example.com'
+ * });
+ *
+ * // Apply the plugin
+ * client.use(auth.middleware());
+ *
+ * // Login
+ * await auth.login('/auth/login', {
+ *   email: 'user@example.com',
+ *   password: 'secret'
+ * });
+ *
+ * // All subsequent requests automatically include Authorization header
+ * const user = await client.get('/me');
+ * ```
+ */
+export declare class Auth {
+    private readonly options;
+    private state;
+    /**
+     * Creates a new Auth instance.
+     *
+     * @param options - Plugin configuration options
+     */
+    constructor(options: AuthPluginOptions);
+    /**
+     * Initializes tokens from storage on plugin creation.
+     * @internal
+     */
+    private initializeFromStorage;
+    /**
+     * Emits a session event to registered listeners.
+     * @internal
+     */
+    private emit;
+    /**
+     * Performs token refresh operation.
+     * This method implements the core refresh logic with retry mechanism.
+     *
+     * Step 1: Check if refresh token exists
+     * Step 2: Make refresh request to endpoint
+     * Step 3: Extract and store new tokens
+     * Step 4: Reset retry counter on success
+     * Step 5: Handle failures and retry logic
+     *
+     * @internal
+     */
+    private performRefresh;
+    /**
+     * Handles refresh failure by clearing state and notifying listeners.
+     * @internal
+     */
+    private handleRefreshFailure;
+    /**
+     * Processes the refresh queue after successful token refresh.
+     * Replays all queued requests with the new access token.
+     *
+     * Step 1: Get the new access token
+     * Step 2: Process each queued request
+     * Step 3: Resolve with updated headers or reject on failure
+     * Step 4: Clear the queue
+     *
+     * @internal
+     */
+    private processQueue;
+    /**
+     * Handles 401 Unauthorized responses by initiating token refresh.
+     * Implements the mutex pattern to prevent multiple concurrent refresh attempts.
+     *
+     * Mutex Pattern Explanation:
+     * - When a 401 is received, we check if a refresh is already in progress
+     * - If yes: Add the request to queue and wait for refresh to complete
+     * - If no: Start refresh, queue other requests that arrive during refresh
+     * - After refresh: Process all queued requests with new token or reject them
+     *
+     * This prevents the "race condition" where multiple 401s trigger multiple
+     * refresh requests simultaneously.
+     *
+     * @internal
+     */
+    private handleUnauthorized;
+    /**
+     * Returns the netreq middleware function.
+     * This function is passed to client.use() to enable authentication.
+     *
+     * The middleware:
+     * 1. Injects Authorization header if token exists
+     * 2. Intercepts 401 responses and triggers token refresh
+     * 3. Queues requests during refresh to prevent race conditions
+     *
+     * @returns Middleware function for netreq client
+     */
+    middleware(): {
+        /**
+         * Request interceptor - adds Authorization header.
+         */
+        onRequest(config: {
+            path: string;
+            method?: string;
+            headers?: Record<string, string>;
+            body?: unknown;
+        }): Promise<typeof config>;
+        /**
+         * Response interceptor - handles 401 errors and triggers refresh.
+         */
+        onResponse(response: {
+            status: number;
+            statusText: string;
+            headers: Record<string, string>;
+            data: unknown;
+        }, requestConfig: {
+            path: string;
+            method?: string;
+            headers?: Record<string, string>;
+            body?: unknown;
+        }): Promise<typeof response>;
+        /**
+         * Error interceptor - handles network errors.
+         */
+        onError(error: Error): Promise<Error>;
+    };
+    /**
+     * Logs in a user and stores tokens.
+     *
+     * @param endpoint - Login API endpoint
+     * @param credentials - Login credentials
+     * @returns Login result with success status
+     */
+    login(endpoint: string, credentials: LoginCredentials): Promise<LoginResult>;
+    /**
+     * Logs out the current user and clears all tokens.
+     */
+    logout(): Promise<void>;
+    /**
+     * Gets the current access token.
+     * @returns Current access token or null if not logged in
+     */
+    getAccessToken(): string | null;
+    /**
+     * Checks if user is currently authenticated.
+     * @returns True if access token exists
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Manually sets tokens (useful for OAuth flows or testing).
+     *
+     * @param tokens - Token pair to set
+     */
+    setTokens(tokens: TokenPair): Promise<void>;
+}
+//# sourceMappingURL=Auth.d.ts.map

package/dist/Auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Auth.d.ts","sourceRoot":"","sources":["../src/Auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAGjB,SAAS,EAET,gBAAgB,EAChB,WAAW,EAEZ,MAAM,YAAY,CAAC;AAWpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAC,OAAO,CAQtB;IAEF,OAAO,CAAC,KAAK,CAAY;IAEzB;;;;OAIG;gBACS,OAAO,EAAE,iBAAiB;IA+BtC;;;OAGG;YACW,qBAAqB;IAYnC;;;OAGG;IACH,OAAO,CAAC,IAAI;IAkBZ;;;;;;;;;;;OAWG;YACW,cAAc;IAyD5B;;;OAGG;YACW,oBAAoB;IAgBlC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,YAAY;IAsBpB;;;;;;;;;;;;;;OAcG;YACW,kBAAkB;IAyChC;;;;;;;;;;OAUG;IACH,UAAU;QAIN;;WAEG;0BACqB;YACtB,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACjC,IAAI,CAAC,EAAE,OAAO,CAAC;SAChB,GAAG,OAAO,CAAC,OAAO,MAAM,CAAC;QAiB1B;;WAEG;6BAES;YACR,MAAM,EAAE,MAAM,CAAC;YACf,UAAU,EAAE,MAAM,CAAC;YACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YAChC,IAAI,EAAE,OAAO,CAAC;SACf,iBACc;YACb,IAAI,EAAE,MAAM,CAAC;YACb,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACjC,IAAI,CAAC,EAAE,OAAO,CAAC;SAChB,GACA,OAAO,CAAC,OAAO,QAAQ,CAAC;QAsC3B;;WAEG;uBACkB,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;;IAM/C;;;;;;OAMG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC;IA6ClF;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAc7B;;;OAGG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B;;;OAGG;IACH,eAAe,IAAI,OAAO;IAI1B;;;;OAIG;IACG,SAAS,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;CAKlD"}