@hamak/auth 0.5.1

package/dist/spi/storage/ITokenStorage.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Token Storage Interface
+ * Abstraction for persisting authentication tokens
+ */
+import type { User } from '../../api';
+/**
+ * Stored token data structure
+ */
+export interface StoredTokens {
+    /** The access token */
+    accessToken: string;
+    /** The refresh token (if available) */
+    refreshToken?: string;
+    /** Token type (usually 'Bearer') */
+    tokenType?: string;
+    /** When the access token expires (timestamp in ms) */
+    expiresAt?: number;
+    /** Token scopes */
+    scope?: string[];
+}
+/**
+ * Token storage interface
+ *
+ * Provides an abstraction layer over the actual storage mechanism.
+ * Implementations can use localStorage, sessionStorage, cookies, etc.
+ */
+export interface ITokenStorage {
+    /**
+     * Get the stored access token
+     * @returns The access token or null if not stored
+     */
+    getAccessToken(): string | null;
+    /**
+     * Store the access token
+     * @param token The access token
+     * @param expiresAt When the token expires (timestamp in ms)
+     */
+    setAccessToken(token: string, expiresAt?: number): void;
+    /**
+     * Get the stored refresh token
+     * @returns The refresh token or null if not stored
+     */
+    getRefreshToken(): string | null;
+    /**
+     * Store the refresh token
+     * @param token The refresh token
+     */
+    setRefreshToken(token: string): void;
+    /**
+     * Get all stored token data
+     * @returns The stored tokens or null if not stored
+     */
+    getTokens(): StoredTokens | null;
+    /**
+     * Store all token data at once
+     * @param tokens The tokens to store
+     */
+    setTokens(tokens: StoredTokens): void;
+    /**
+     * Clear all stored tokens
+     */
+    clearTokens(): void;
+    /**
+     * Check if the access token is expired
+     * @returns true if the token is expired or not present
+     */
+    isTokenExpired(): boolean;
+    /**
+     * Check if the token will expire soon
+     * @param thresholdMs Time in ms before expiry to consider "soon"
+     * @returns true if the token will expire within the threshold
+     */
+    isTokenExpiringSoon(thresholdMs: number): boolean;
+    /**
+     * Get the token expiration time
+     * @returns Timestamp in ms when the token expires, or null
+     */
+    getTokenExpiry(): number | null;
+    /**
+     * Get the stored user data
+     * @returns The user or null if not stored
+     */
+    getUser(): User | null;
+    /**
+     * Store user data
+     * @param user The user to store
+     */
+    setUser(user: User): void;
+    /**
+     * Clear stored user data
+     */
+    clearUser(): void;
+    /**
+     * Clear all auth data (tokens and user)
+     */
+    clearAll(): void;
+}
+/**
+ * Configuration for token storage
+ */
+export interface TokenStorageConfig {
+    /** Key prefix for storage (default: '@hamak/auth') */
+    keyPrefix?: string;
+    /** Whether to encrypt tokens before storing (implementation-specific) */
+    encrypt?: boolean;
+}
+//# sourceMappingURL=ITokenStorage.d.ts.map

package/dist/spi/storage/ITokenStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ITokenStorage.d.ts","sourceRoot":"","sources":["../../../src/spi/storage/ITokenStorage.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,uCAAuC;IACvC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB;IACnB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI,CAAC;IAEhC;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAExD;;;OAGG;IACH,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IAEjC;;;OAGG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAErC;;;OAGG;IACH,SAAS,IAAI,YAAY,GAAG,IAAI,CAAC;IAEjC;;;OAGG;IACH,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;IAEtC;;OAEG;IACH,WAAW,IAAI,IAAI,CAAC;IAEpB;;;OAGG;IACH,cAAc,IAAI,OAAO,CAAC;IAE1B;;;;OAIG;IACH,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC;IAElD;;;OAGG;IACH,cAAc,IAAI,MAAM,GAAG,IAAI,CAAC;IAEhC;;;OAGG;IACH,OAAO,IAAI,IAAI,GAAG,IAAI,CAAC;IAEvB;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAE1B;;OAEG;IACH,SAAS,IAAI,IAAI,CAAC;IAElB;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/spi/storage/ITokenStorage.js

@@ -0,0 +1,5 @@
+/**
+ * Token Storage Interface
+ * Abstraction for persisting authentication tokens
+ */
+export {};

package/dist/spi/storage/index.d.ts

@@ -0,0 +1,2 @@
+export * from './ITokenStorage';
+//# sourceMappingURL=index.d.ts.map

package/dist/spi/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spi/storage/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/spi/storage/index.js

@@ -0,0 +1 @@
+export * from './ITokenStorage';

package/dist/spi/strategies/IAuthStrategy.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Auth Strategy Interface
+ * Base interface for all authentication strategy implementations
+ */
+import type { AuthResult, AuthStrategyType, LoginCredentials, OAuthCallbackParams, User } from '../../api';
+/**
+ * HTTP client interface for making auth requests
+ * This abstraction allows strategies to work with any HTTP client
+ */
+export interface IHttpClient {
+    get<T = unknown>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    post<T = unknown>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    put<T = unknown>(url: string, data?: unknown, config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    delete<T = unknown>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+}
+export interface HttpRequestConfig {
+    headers?: Record<string, string>;
+    params?: Record<string, string>;
+    timeout?: number;
+}
+export interface HttpResponse<T = unknown> {
+    data: T;
+    status: number;
+    headers: Record<string, string>;
+}
+/**
+ * Base authentication strategy interface
+ *
+ * All authentication strategies must implement this interface.
+ * Strategies handle the specifics of authentication flows while
+ * the AuthService provides a unified API.
+ */
+export interface IAuthStrategy {
+    /**
+     * The type identifier for this strategy
+     */
+    readonly type: AuthStrategyType;
+    /**
+     * Unique name for this strategy instance
+     * Allows multiple strategies of the same type (e.g., multiple OAuth providers)
+     */
+    readonly name: string;
+    /**
+     * Authenticate with the given credentials
+     * @param credentials The login credentials
+     * @returns Authentication result with tokens and user info
+     */
+    authenticate(credentials: LoginCredentials): Promise<AuthResult>;
+    /**
+     * Refresh the access token using a refresh token
+     * @param refreshToken The refresh token
+     * @returns New authentication result with fresh tokens
+     */
+    refreshToken(refreshToken: string): Promise<AuthResult>;
+    /**
+     * Revoke tokens and end the session
+     * @param accessToken The current access token
+     */
+    logout(accessToken: string): Promise<void>;
+    /**
+     * Extract user information from a token (optional)
+     * Used for JWT-based strategies that embed user info in tokens
+     * @param token The access token
+     */
+    extractUserFromToken?(token: string): User | null;
+}
+/**
+ * OAuth-capable strategy interface
+ * Extends base strategy with OAuth-specific methods
+ */
+export interface IOAuthStrategy extends IAuthStrategy {
+    /**
+     * Get the authorization URL for OAuth redirect
+     * @returns The full authorization URL with all parameters
+     */
+    getAuthorizationUrl(): string | Promise<string>;
+    /**
+     * Handle the OAuth callback after user authorization
+     * @param params The callback parameters from the OAuth provider
+     * @returns Authentication result
+     */
+    handleCallback(params: OAuthCallbackParams): Promise<AuthResult>;
+    /**
+     * Get the stored state parameter for validation
+     * Used to validate the state parameter in OAuth callbacks
+     */
+    getStoredState(): string | null;
+    /**
+     * Clear stored OAuth state (code verifier, state, etc.)
+     */
+    clearOAuthState(): void;
+}
+/**
+ * Strategy that supports direct password authentication
+ * Some OAuth providers (like Keycloak) can also support direct grant
+ */
+export interface IDirectAuthStrategy extends IAuthStrategy {
+    /**
+     * Authenticate directly with username/password
+     * @param username The username
+     * @param password The password
+     * @returns Authentication result
+     */
+    authenticateDirect(username: string, password: string): Promise<AuthResult>;
+}
+/**
+ * Type guard to check if a strategy supports OAuth
+ */
+export declare function isOAuthStrategy(strategy: IAuthStrategy): strategy is IOAuthStrategy;
+/**
+ * Type guard to check if a strategy supports direct auth
+ */
+export declare function isDirectAuthStrategy(strategy: IAuthStrategy): strategy is IDirectAuthStrategy;
+//# sourceMappingURL=IAuthStrategy.d.ts.map

package/dist/spi/strategies/IAuthStrategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IAuthStrategy.d.ts","sourceRoot":"","sources":["../../../src/spi/strategies/IAuthStrategy.ts"],"names":[],"mappings":"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"}

package/dist/spi/strategies/IAuthStrategy.js

@@ -0,0 +1,16 @@
+/**
+ * Auth Strategy Interface
+ * Base interface for all authentication strategy implementations
+ */
+/**
+ * Type guard to check if a strategy supports OAuth
+ */
+export function isOAuthStrategy(strategy) {
+    return 'getAuthorizationUrl' in strategy && 'handleCallback' in strategy;
+}
+/**
+ * Type guard to check if a strategy supports direct auth
+ */
+export function isDirectAuthStrategy(strategy) {
+    return 'authenticateDirect' in strategy;
+}

package/dist/spi/strategies/IStrategyRegistry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Strategy Registry Interface
+ * Registry for managing multiple authentication strategies
+ */
+import type { IAuthStrategy, IOAuthStrategy } from './IAuthStrategy';
+/**
+ * Registry for authentication strategies
+ *
+ * Allows registering and retrieving multiple strategies.
+ * Useful for applications that support multiple login methods.
+ */
+export interface IStrategyRegistry {
+    /**
+     * Register an authentication strategy
+     * @param strategy The strategy to register
+     */
+    register(strategy: IAuthStrategy): void;
+    /**
+     * Unregister a strategy by name
+     * @param name The strategy name
+     */
+    unregister(name: string): void;
+    /**
+     * Get a strategy by name
+     * @param name The strategy name
+     * @returns The strategy or undefined if not found
+     */
+    get(name: string): IAuthStrategy | undefined;
+    /**
+     * Get an OAuth strategy by name
+     * @param name The strategy name
+     * @returns The OAuth strategy or undefined if not found
+     */
+    getOAuth(name: string): IOAuthStrategy | undefined;
+    /**
+     * Get all registered strategies
+     * @returns Array of all strategies
+     */
+    getAll(): IAuthStrategy[];
+    /**
+     * Get all OAuth strategies
+     * @returns Array of OAuth strategies
+     */
+    getAllOAuth(): IOAuthStrategy[];
+    /**
+     * Check if a strategy is registered
+     * @param name The strategy name
+     */
+    has(name: string): boolean;
+    /**
+     * Get the default strategy
+     */
+    getDefault(): IAuthStrategy | undefined;
+    /**
+     * Set the default strategy
+     * @param name The strategy name to use as default
+     */
+    setDefault(name: string): void;
+    /**
+     * Clear all registered strategies
+     */
+    clear(): void;
+}
+//# sourceMappingURL=IStrategyRegistry.d.ts.map

package/dist/spi/strategies/IStrategyRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IStrategyRegistry.d.ts","sourceRoot":"","sources":["../../../src/spi/strategies/IStrategyRegistry.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAExC;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAE7C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAC;IAEnD;;;OAGG;IACH,MAAM,IAAI,aAAa,EAAE,CAAC;IAE1B;;;OAGG;IACH,WAAW,IAAI,cAAc,EAAE,CAAC;IAEhC;;;OAGG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B;;OAEG;IACH,UAAU,IAAI,aAAa,GAAG,SAAS,CAAC;IAExC;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAE/B;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACf"}

package/dist/spi/strategies/IStrategyRegistry.js

@@ -0,0 +1,5 @@
+/**
+ * Strategy Registry Interface
+ * Registry for managing multiple authentication strategies
+ */
+export {};

package/dist/spi/strategies/index.d.ts

@@ -0,0 +1,3 @@
+export * from './IAuthStrategy';
+export * from './IStrategyRegistry';
+//# sourceMappingURL=index.d.ts.map

package/dist/spi/strategies/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/spi/strategies/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC"}

package/dist/spi/strategies/index.js

@@ -0,0 +1,2 @@
+export * from './IAuthStrategy';
+export * from './IStrategyRegistry';

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@hamak/auth",
+  "version": "0.5.1",
+  "description": "Auth - Complete authentication plugin with password, OAuth2, and Keycloak support",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.js"
+    },
+    "./spi": {
+      "types": "./dist/spi/index.d.ts",
+      "import": "./dist/spi/index.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "api": [
+        "./dist/api/index.d.ts"
+      ],
+      "spi": [
+        "./dist/spi/index.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amah/app-framework.git",
+    "directory": "packages/auth"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "auth",
+    "authentication",
+    "oauth2",
+    "keycloak",
+    "microkernel",
+    "plugin"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@hamak/microkernel-api": "*",
+    "@hamak/microkernel-spi": "*",
+    "@hamak/logging-api": "*"
+  },
+  "peerDependencies": {
+    "@hamak/ui-store-api": "*",
+    "axios": "^1.6.0"
+  },
+  "peerDependenciesMeta": {
+    "@hamak/ui-store-api": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "axios": "^1.6.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}