@hamak/auth 0.5.1

package/dist/impl/strategies/KeycloakStrategy.js

@@ -0,0 +1,237 @@
+/**
+ * Keycloak Authentication Strategy
+ * Implements authentication with Keycloak identity provider
+ */
+import { OAuth2Strategy } from './OAuth2Strategy';
+import { extractUserFromJWT } from '../utils/jwt';
+/**
+ * Keycloak authentication strategy
+ *
+ * Extends OAuth2 strategy with Keycloak-specific features:
+ * - Direct grant (password) authentication
+ * - Role extraction from JWT tokens
+ * - Keycloak realm and resource roles
+ * - Proper logout with session invalidation
+ */
+export class KeycloakStrategy {
+    constructor(config, httpClient, name = 'keycloak') {
+        this.config = config;
+        this.httpClient = httpClient;
+        this.type = 'keycloak';
+        this.name = name;
+        // Build Keycloak OpenID Connect URLs
+        this.baseUrl = `${config.serverUrl}/realms/${config.realm}/protocol/openid-connect`;
+        this.tokenUrl = `${this.baseUrl}/token`;
+        this.logoutUrl = `${this.baseUrl}/logout`;
+        // Create underlying OAuth2 strategy
+        this.oauth2 = new OAuth2Strategy({
+            clientId: config.clientId,
+            authorizationUrl: `${this.baseUrl}/auth`,
+            tokenUrl: this.tokenUrl,
+            userInfoUrl: `${this.baseUrl}/userinfo`,
+            redirectUri: config.redirectUri,
+            scope: config.scope || ['openid', 'profile', 'email'],
+            usePkce: config.usePkce !== false
+        }, httpClient, `${name}-oauth2`);
+    }
+    async getAuthorizationUrl() {
+        return this.oauth2.getAuthorizationUrl();
+    }
+    async handleCallback(params) {
+        const result = await this.oauth2.handleCallback(params);
+        if (result.success && result.accessToken) {
+            // Extract user with roles from JWT
+            result.user = this.extractUserWithRoles(result.accessToken);
+        }
+        return result;
+    }
+    async authenticate(credentials) {
+        // For password credentials, use direct grant
+        if (credentials.type === 'password' && this.config.enableDirectGrant) {
+            return this.authenticateDirect(credentials.username, credentials.password);
+        }
+        // For OAuth credentials, use callback flow
+        if (credentials.type === 'oauth') {
+            return this.handleCallback({
+                code: credentials.code,
+                state: credentials.state
+            });
+        }
+        return {
+            success: false,
+            error: {
+                code: 'invalid_credentials',
+                message: 'Invalid credentials type for Keycloak strategy'
+            }
+        };
+    }
+    async authenticateDirect(username, password) {
+        if (!this.config.enableDirectGrant) {
+            return {
+                success: false,
+                error: {
+                    code: 'invalid_credentials',
+                    message: 'Direct grant is not enabled for this Keycloak client'
+                }
+            };
+        }
+        try {
+            const response = await this.httpClient.post(this.tokenUrl, new URLSearchParams({
+                grant_type: 'password',
+                client_id: this.config.clientId,
+                username,
+                password,
+                scope: (this.config.scope || ['openid', 'profile', 'email']).join(' ')
+            }).toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                }
+            });
+            const data = response.data;
+            const user = this.extractUserWithRoles(data.access_token);
+            return {
+                success: true,
+                user,
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token,
+                tokenType: data.token_type || 'Bearer',
+                expiresAt: data.expires_in
+                    ? Date.now() + data.expires_in * 1000
+                    : undefined,
+                scope: data.scope?.split(' ')
+            };
+        }
+        catch (error) {
+            return this.handleKeycloakError(error);
+        }
+    }
+    async refreshToken(refreshToken) {
+        try {
+            const response = await this.httpClient.post(this.tokenUrl, new URLSearchParams({
+                grant_type: 'refresh_token',
+                client_id: this.config.clientId,
+                refresh_token: refreshToken
+            }).toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                }
+            });
+            const data = response.data;
+            const user = this.extractUserWithRoles(data.access_token);
+            return {
+                success: true,
+                user,
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token,
+                tokenType: data.token_type || 'Bearer',
+                expiresAt: data.expires_in
+                    ? Date.now() + data.expires_in * 1000
+                    : undefined,
+                scope: data.scope?.split(' ')
+            };
+        }
+        catch (error) {
+            return this.handleKeycloakError(error);
+        }
+    }
+    async logout(accessToken) {
+        try {
+            // Keycloak requires the refresh token for proper logout
+            // If we don't have it, we can still try to logout with just the access token
+            await this.httpClient.post(this.logoutUrl, new URLSearchParams({
+                client_id: this.config.clientId
+            }).toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Authorization: `Bearer ${accessToken}`
+                }
+            });
+        }
+        catch {
+            // Ignore logout errors - continue with local cleanup
+        }
+        this.oauth2.clearOAuthState();
+    }
+    /**
+     * Logout with refresh token for complete session invalidation
+     */
+    async logoutWithRefreshToken(refreshToken) {
+        try {
+            await this.httpClient.post(this.logoutUrl, new URLSearchParams({
+                client_id: this.config.clientId,
+                refresh_token: refreshToken
+            }).toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                }
+            });
+        }
+        catch {
+            // Ignore logout errors
+        }
+        this.oauth2.clearOAuthState();
+    }
+    getStoredState() {
+        return this.oauth2.getStoredState();
+    }
+    clearOAuthState() {
+        this.oauth2.clearOAuthState();
+    }
+    extractUserFromToken(token) {
+        return this.extractUserWithRoles(token) || null;
+    }
+    extractUserWithRoles(token) {
+        const user = extractUserFromJWT(token, this.config.clientId);
+        return user || undefined;
+    }
+    handleKeycloakError(error) {
+        const httpError = error;
+        const errorCode = httpError.response?.data?.error;
+        const errorDesc = httpError.response?.data?.error_description;
+        const status = httpError.response?.status;
+        // Map Keycloak errors to our error codes
+        if (errorCode === 'invalid_grant') {
+            if (errorDesc?.includes('disabled')) {
+                return {
+                    success: false,
+                    error: {
+                        code: 'account_disabled',
+                        message: 'User account is disabled'
+                    }
+                };
+            }
+            if (errorDesc?.includes('locked')) {
+                return {
+                    success: false,
+                    error: {
+                        code: 'account_locked',
+                        message: 'User account is locked'
+                    }
+                };
+            }
+            return {
+                success: false,
+                error: {
+                    code: 'invalid_credentials',
+                    message: errorDesc || 'Invalid username or password'
+                }
+            };
+        }
+        if (status === 401) {
+            return {
+                success: false,
+                error: {
+                    code: 'unauthorized',
+                    message: errorDesc || 'Authentication failed'
+                }
+            };
+        }
+        return {
+            success: false,
+            error: {
+                code: 'server_error',
+                message: errorDesc || 'Keycloak authentication failed'
+            }
+        };
+    }
+}

package/dist/impl/strategies/OAuth2Strategy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OAuth2 Authentication Strategy
+ * Implements OAuth2 Authorization Code flow with PKCE
+ */
+import type { AuthResult, LoginCredentials, OAuth2StrategyConfig, OAuthCallbackParams } from '../../api';
+import type { IOAuthStrategy, IHttpClient } from '../../spi';
+/**
+ * OAuth2 authentication strategy
+ *
+ * Implements the OAuth2 Authorization Code flow with PKCE support.
+ * Can be used with any OAuth2-compliant identity provider.
+ */
+export declare class OAuth2Strategy implements IOAuthStrategy {
+    private readonly config;
+    private readonly httpClient;
+    readonly type: "oauth2";
+    readonly name: string;
+    private storedState;
+    constructor(config: OAuth2StrategyConfig, httpClient: IHttpClient, name?: string);
+    getAuthorizationUrl(): Promise<string>;
+    handleCallback(params: OAuthCallbackParams): Promise<AuthResult>;
+    authenticate(credentials: LoginCredentials): Promise<AuthResult>;
+    refreshToken(refreshToken: string): Promise<AuthResult>;
+    logout(_accessToken: string): Promise<void>;
+    getStoredState(): string | null;
+    clearOAuthState(): void;
+    private fetchUserInfo;
+    private handleError;
+}
+//# sourceMappingURL=OAuth2Strategy.d.ts.map

package/dist/impl/strategies/OAuth2Strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuth2Strategy.d.ts","sourceRoot":"","sources":["../../../src/impl/strategies/OAuth2Strategy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EAEpB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAqC7D;;;;;GAKG;AACH,qBAAa,cAAe,YAAW,cAAc;IAMjD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAN7B,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,WAAW,CAAuB;gBAGvB,MAAM,EAAE,oBAAoB,EAC5B,UAAU,EAAE,WAAW,EACxC,IAAI,SAAW;IAKX,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC;IAsCtC,cAAc,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;IAgFhE,YAAY,CAAC,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IAiBhE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAuCvD,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMjD,cAAc,IAAI,MAAM,GAAG,IAAI;IAI/B,eAAe,IAAI,IAAI;YAKT,aAAa;IA+B3B,OAAO,CAAC,WAAW;CAiCpB"}

package/dist/impl/strategies/OAuth2Strategy.js

@@ -0,0 +1,232 @@
+/**
+ * OAuth2 Authentication Strategy
+ * Implements OAuth2 Authorization Code flow with PKCE
+ */
+import { generateState, generateCodeVerifier, generateCodeChallenge, storePKCEState, retrievePKCEState, clearPKCEState } from '../utils/pkce';
+/**
+ * OAuth2 authentication strategy
+ *
+ * Implements the OAuth2 Authorization Code flow with PKCE support.
+ * Can be used with any OAuth2-compliant identity provider.
+ */
+export class OAuth2Strategy {
+    constructor(config, httpClient, name = 'oauth2') {
+        this.config = config;
+        this.httpClient = httpClient;
+        this.type = 'oauth2';
+        this.storedState = null;
+        this.name = name;
+    }
+    async getAuthorizationUrl() {
+        const state = generateState();
+        this.storedState = state;
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            redirect_uri: this.config.redirectUri,
+            response_type: this.config.responseType || 'code',
+            scope: this.config.scope.join(' '),
+            state
+        });
+        // Add PKCE if enabled (recommended for public clients)
+        if (this.config.usePkce !== false) {
+            const codeVerifier = generateCodeVerifier();
+            const codeChallenge = await generateCodeChallenge(codeVerifier);
+            params.set('code_challenge', codeChallenge);
+            params.set('code_challenge_method', 'S256');
+            // Store PKCE state for callback
+            storePKCEState({
+                state,
+                codeVerifier,
+                createdAt: Date.now()
+            });
+        }
+        // Add any additional params
+        if (this.config.additionalParams) {
+            Object.entries(this.config.additionalParams).forEach(([key, value]) => {
+                params.set(key, value);
+            });
+        }
+        return `${this.config.authorizationUrl}?${params.toString()}`;
+    }
+    async handleCallback(params) {
+        // Check for OAuth errors
+        if (params.error) {
+            return {
+                success: false,
+                error: {
+                    code: 'unauthorized',
+                    message: params.errorDescription || params.error
+                }
+            };
+        }
+        // Validate state
+        const pkceState = retrievePKCEState();
+        if (pkceState && params.state !== pkceState.state) {
+            clearPKCEState();
+            return {
+                success: false,
+                error: {
+                    code: 'invalid_state',
+                    message: 'State parameter mismatch - possible CSRF attack'
+                }
+            };
+        }
+        try {
+            // Exchange code for tokens
+            const tokenParams = {
+                grant_type: 'authorization_code',
+                client_id: this.config.clientId,
+                code: params.code,
+                redirect_uri: this.config.redirectUri
+            };
+            // Add client secret if provided (for confidential clients)
+            if (this.config.clientSecret) {
+                tokenParams.client_secret = this.config.clientSecret;
+            }
+            // Add code verifier for PKCE
+            if (pkceState?.codeVerifier) {
+                tokenParams.code_verifier = pkceState.codeVerifier;
+            }
+            const response = await this.httpClient.post(this.config.tokenUrl, new URLSearchParams(tokenParams).toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                }
+            });
+            clearPKCEState();
+            const data = response.data;
+            // Fetch user info
+            let user;
+            if (this.config.userInfoUrl) {
+                user = await this.fetchUserInfo(data.access_token);
+            }
+            return {
+                success: true,
+                user,
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token,
+                tokenType: data.token_type || 'Bearer',
+                expiresAt: data.expires_in
+                    ? Date.now() + data.expires_in * 1000
+                    : undefined,
+                scope: data.scope?.split(' ')
+            };
+        }
+        catch (error) {
+            clearPKCEState();
+            return this.handleError(error);
+        }
+    }
+    async authenticate(credentials) {
+        if (credentials.type !== 'oauth') {
+            return {
+                success: false,
+                error: {
+                    code: 'invalid_credentials',
+                    message: 'Use handleCallback for OAuth authentication'
+                }
+            };
+        }
+        return this.handleCallback({
+            code: credentials.code,
+            state: credentials.state
+        });
+    }
+    async refreshToken(refreshToken) {
+        try {
+            const tokenParams = {
+                grant_type: 'refresh_token',
+                client_id: this.config.clientId,
+                refresh_token: refreshToken
+            };
+            if (this.config.clientSecret) {
+                tokenParams.client_secret = this.config.clientSecret;
+            }
+            const response = await this.httpClient.post(this.config.tokenUrl, new URLSearchParams(tokenParams).toString(), {
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded'
+                }
+            });
+            const data = response.data;
+            return {
+                success: true,
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token,
+                tokenType: data.token_type || 'Bearer',
+                expiresAt: data.expires_in
+                    ? Date.now() + data.expires_in * 1000
+                    : undefined,
+                scope: data.scope?.split(' ')
+            };
+        }
+        catch (error) {
+            return this.handleError(error);
+        }
+    }
+    async logout(_accessToken) {
+        // OAuth2 doesn't have a standard logout endpoint
+        // Subclasses (like KeycloakStrategy) can override this
+        clearPKCEState();
+    }
+    getStoredState() {
+        return this.storedState || retrievePKCEState()?.state || null;
+    }
+    clearOAuthState() {
+        this.storedState = null;
+        clearPKCEState();
+    }
+    async fetchUserInfo(accessToken) {
+        if (!this.config.userInfoUrl) {
+            return undefined;
+        }
+        try {
+            const response = await this.httpClient.get(this.config.userInfoUrl, {
+                headers: {
+                    Authorization: `Bearer ${accessToken}`
+                }
+            });
+            const data = response.data;
+            return {
+                id: data.sub,
+                email: data.email || '',
+                name: data.name || data.preferred_username,
+                username: data.preferred_username,
+                avatar: data.picture,
+                roles: [],
+                permissions: []
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    handleError(error) {
+        const httpError = error;
+        const errorCode = httpError.response?.data?.error;
+        const errorDesc = httpError.response?.data?.error_description;
+        if (errorCode === 'invalid_grant') {
+            return {
+                success: false,
+                error: {
+                    code: 'invalid_token',
+                    message: errorDesc || 'Invalid or expired authorization code'
+                }
+            };
+        }
+        if (errorCode === 'invalid_client') {
+            return {
+                success: false,
+                error: {
+                    code: 'server_error',
+                    message: 'Invalid client configuration'
+                }
+            };
+        }
+        return {
+            success: false,
+            error: {
+                code: 'server_error',
+                message: errorDesc || 'OAuth authentication failed'
+            }
+        };
+    }
+}

package/dist/impl/strategies/PasswordStrategy.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Password Authentication Strategy
+ * Implements username/password based authentication
+ */
+import type { AuthResult, LoginCredentials, PasswordStrategyConfig } from '../../api';
+import type { IAuthStrategy, IHttpClient } from '../../spi';
+/**
+ * Password-based authentication strategy
+ *
+ * Authenticates users with username and password against a backend API.
+ * Supports token refresh and logout operations.
+ */
+export declare class PasswordStrategy implements IAuthStrategy {
+    private readonly config;
+    private readonly httpClient;
+    readonly type: "password";
+    readonly name: string;
+    constructor(config: PasswordStrategyConfig, httpClient: IHttpClient, name?: string);
+    authenticate(credentials: LoginCredentials): Promise<AuthResult>;
+    refreshToken(refreshToken: string): Promise<AuthResult>;
+    logout(accessToken: string): Promise<void>;
+    private fetchUserInfo;
+    private handleError;
+}
+//# sourceMappingURL=PasswordStrategy.d.ts.map

package/dist/impl/strategies/PasswordStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PasswordStrategy.d.ts","sourceRoot":"","sources":["../../../src/impl/strategies/PasswordStrategy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,gBAAgB,EAChB,sBAAsB,EAEvB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AA4B5D;;;;;GAKG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IAKlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAL7B,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAGH,MAAM,EAAE,sBAAsB,EAC9B,UAAU,EAAE,WAAW,EACxC,IAAI,SAAa;IAKb,YAAY,CAAC,WAAW,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC;IA+ChE,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IA8BvD,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAiBlC,aAAa;IAgC3B,OAAO,CAAC,WAAW;CA2CpB"}

package/dist/impl/strategies/PasswordStrategy.js

@@ -0,0 +1,159 @@
+/**
+ * Password Authentication Strategy
+ * Implements username/password based authentication
+ */
+/**
+ * Password-based authentication strategy
+ *
+ * Authenticates users with username and password against a backend API.
+ * Supports token refresh and logout operations.
+ */
+export class PasswordStrategy {
+    constructor(config, httpClient, name = 'password') {
+        this.config = config;
+        this.httpClient = httpClient;
+        this.type = 'password';
+        this.name = name;
+    }
+    async authenticate(credentials) {
+        if (credentials.type !== 'password') {
+            return {
+                success: false,
+                error: {
+                    code: 'invalid_credentials',
+                    message: 'Invalid credentials type for password strategy'
+                }
+            };
+        }
+        try {
+            const response = await this.httpClient.post(this.config.loginEndpoint, {
+                username: credentials.username,
+                password: credentials.password
+            }, {
+                headers: this.config.headers
+            });
+            const data = response.data;
+            // Get user info if not included in login response
+            let user = data.user;
+            if (!user && this.config.userInfoEndpoint) {
+                user = await this.fetchUserInfo(data.access_token);
+            }
+            return {
+                success: true,
+                user,
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token,
+                tokenType: data.token_type || 'Bearer',
+                expiresAt: data.expires_in
+                    ? Date.now() + data.expires_in * 1000
+                    : undefined,
+                scope: data.scope?.split(' ')
+            };
+        }
+        catch (error) {
+            return this.handleError(error);
+        }
+    }
+    async refreshToken(refreshToken) {
+        try {
+            const response = await this.httpClient.post(this.config.refreshEndpoint, {
+                refresh_token: refreshToken,
+                grant_type: 'refresh_token'
+            }, {
+                headers: this.config.headers
+            });
+            const data = response.data;
+            return {
+                success: true,
+                accessToken: data.access_token,
+                refreshToken: data.refresh_token,
+                tokenType: data.token_type || 'Bearer',
+                expiresAt: data.expires_in
+                    ? Date.now() + data.expires_in * 1000
+                    : undefined,
+                scope: data.scope?.split(' ')
+            };
+        }
+        catch (error) {
+            return this.handleError(error);
+        }
+    }
+    async logout(accessToken) {
+        try {
+            await this.httpClient.post(this.config.logoutEndpoint, {}, {
+                headers: {
+                    ...this.config.headers,
+                    Authorization: `Bearer ${accessToken}`
+                }
+            });
+        }
+        catch {
+            // Ignore logout errors - continue with local cleanup
+        }
+    }
+    async fetchUserInfo(accessToken) {
+        if (!this.config.userInfoEndpoint) {
+            return undefined;
+        }
+        try {
+            const response = await this.httpClient.get(this.config.userInfoEndpoint, {
+                headers: {
+                    ...this.config.headers,
+                    Authorization: `Bearer ${accessToken}`
+                }
+            });
+            const data = response.data;
+            return {
+                id: data.id,
+                email: data.email,
+                name: data.name,
+                username: data.username,
+                avatar: data.avatar,
+                roles: data.roles || [],
+                permissions: data.permissions || []
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    handleError(error) {
+        const httpError = error;
+        const status = httpError.response?.status;
+        const message = httpError.response?.data?.message;
+        if (status === 401) {
+            return {
+                success: false,
+                error: {
+                    code: 'invalid_credentials',
+                    message: message || 'Invalid username or password'
+                }
+            };
+        }
+        if (status === 403) {
+            return {
+                success: false,
+                error: {
+                    code: 'forbidden',
+                    message: message || 'Access forbidden'
+                }
+            };
+        }
+        if (status === 423) {
+            return {
+                success: false,
+                error: {
+                    code: 'account_locked',
+                    message: message || 'Account is locked'
+                }
+            };
+        }
+        return {
+            success: false,
+            error: {
+                code: 'server_error',
+                message: message || 'Authentication failed'
+            }
+        };
+    }
+}