@armco/iam-client 0.1.1

package/README.md

@@ -0,0 +1,181 @@
+# @armco/iam-client
+
+Browser/SPA client for IAM - OIDC/OAuth2 authentication with PKCE.
+
+## Installation
+
+```bash
+npm install @armco/iam-client
+```
+
+## Quick Start
+
+### Vanilla JavaScript/TypeScript
+
+```typescript
+import { createIAMClient } from '@armco/iam-client';
+
+const iam = createIAMClient({
+  issuer: 'http://localhost:5000',
+  clientId: 'my-app',
+  redirectUri: 'http://localhost:3000/callback',
+  scopes: ['openid', 'profile', 'email', 'offline_access'],
+});
+
+// Login
+document.getElementById('login-btn').onclick = () => iam.login();
+
+// Signup
+document.getElementById('signup-btn').onclick = () => iam.signup();
+
+// Handle callback (on /callback page)
+const result = await iam.handleCallback();
+if (result.success) {
+  console.log('Logged in:', result.user);
+} else {
+  console.error('Login failed:', result.error);
+}
+
+// Get current user
+const user = iam.getUser();
+
+// Get access token (auto-refreshes if needed)
+const token = await iam.getAccessToken();
+
+// Logout
+await iam.logout();
+```
+
+### React
+
+```tsx
+import { IAMProvider, useAuth } from '@armco/iam-client/react';
+
+// Wrap your app
+function App() {
+  return (
+    <IAMProvider
+      issuer="http://localhost:5000"
+      clientId="my-app"
+      redirectUri="http://localhost:3000/callback"
+      onLoginSuccess={(result) => {
+        console.log('Logged in:', result.user);
+        // Navigate to dashboard
+      }}
+    >
+      <Router>
+        <Routes>
+          <Route path="/" element={<Home />} />
+          <Route path="/callback" element={<Callback />} />
+          <Route path="/dashboard" element={<Dashboard />} />
+        </Routes>
+      </Router>
+    </StuffleIAMProvider>
+  );
+}
+
+// Use the hook
+function Home() {
+  const { isAuthenticated, isLoading, user, login, signup, logout } = useAuth();
+
+  if (isLoading) return <div>Loading...</div>;
+
+  if (!isAuthenticated) {
+    return (
+      <div>
+        <button onClick={() => login()}>Login</button>
+        <button onClick={() => signup()}>Sign Up</button>
+      </div>
+    );
+  }
+
+  return (
+    <div>
+      <p>Welcome, {user?.name || user?.email}</p>
+      <button onClick={() => logout()}>Logout</button>
+    </div>
+  );
+}
+
+// Callback page (auto-handled by provider)
+function Callback() {
+  const { isLoading, error } = useAuth();
+  
+  if (isLoading) return <div>Processing login...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  
+  return <Navigate to="/dashboard" />;
+}
+```
+
+## Configuration
+
+```typescript
+interface StuffleIAMConfig {
+  /** IAM server base URL */
+  issuer: string;
+  /** OAuth2 client ID */
+  clientId: string;
+  /** Redirect URI after login */
+  redirectUri: string;
+  /** Requested scopes (default: openid profile email) */
+  scopes?: string[];
+  /** Post-logout redirect URI */
+  postLogoutRedirectUri?: string;
+  /** Enable PKCE (default: true) */
+  usePkce?: boolean;
+  /** Storage type (default: sessionStorage) */
+  storage?: 'localStorage' | 'sessionStorage' | 'memory';
+  /** Auto-refresh tokens (default: true) */
+  autoRefresh?: boolean;
+  /** Seconds before expiry to refresh (default: 60) */
+  refreshThreshold?: number;
+}
+```
+
+## React Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useAuth()` | Full auth context (user, login, logout, etc.) |
+| `useUser()` | Current user object |
+| `useIsAuthenticated()` | Boolean auth status |
+| `useAccessToken()` | Function to get access token |
+| `useHasRole(roles)` | Check if user has role(s) |
+
+## Protected Routes (HOC)
+
+```tsx
+import { withAuth } from '@armco/iam-client/react';
+
+const ProtectedPage = withAuth(MyComponent, {
+  LoadingComponent: () => <div>Loading...</div>,
+  UnauthorizedComponent: () => <div>Please login</div>,
+  roles: ['admin'], // Optional: require specific roles
+});
+```
+
+## API Reference
+
+### StuffleIAMClient Methods
+
+| Method | Description |
+|--------|-------------|
+| `login(options?)` | Start login flow |
+| `signup(options?)` | Start signup flow |
+| `logout(options?)` | End session |
+| `handleCallback(url?)` | Process OAuth callback |
+| `getUser()` | Get current user from ID token |
+| `getAccessToken()` | Get access token (refreshes if needed) |
+| `isAuthenticated()` | Check if user is logged in |
+| `refreshToken()` | Manually refresh tokens |
+| `subscribe(listener)` | Subscribe to auth state changes |
+
+## Development
+
+```bash
+cd packages/sdk-js
+npm install
+npm run build
+npm run dev  # Watch mode
+```

package/dist/client-CTKWBZ26.d.mts

@@ -0,0 +1,185 @@
+/**
+ * Stuffle IAM SDK Types
+ */
+interface StuffleIAMConfig {
+    /** IAM server base URL (e.g., http://localhost:5000) */
+    issuer: string;
+    /** OAuth2 client ID */
+    clientId: string;
+    /** Redirect URI after login */
+    redirectUri: string;
+    /** Requested scopes (default: openid profile email) */
+    scopes?: string[];
+    /** Post-logout redirect URI */
+    postLogoutRedirectUri?: string;
+    /** Enable PKCE (default: true, recommended for SPAs) */
+    usePkce?: boolean;
+    /** Storage type for tokens (default: sessionStorage) */
+    storage?: 'localStorage' | 'sessionStorage' | 'memory';
+    /** Auto-refresh tokens before expiry (default: true) */
+    autoRefresh?: boolean;
+    /** Seconds before expiry to trigger refresh (default: 60) */
+    refreshThreshold?: number;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+interface User {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: string;
+    username?: string;
+    roles?: string[];
+    tenantId?: string;
+    [key: string]: unknown;
+}
+interface AuthState {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    user: User | null;
+    accessToken: string | null;
+    idToken: string | null;
+    error: Error | null;
+}
+interface LoginOptions {
+    /** Additional scopes to request */
+    scopes?: string[];
+    /** State parameter (auto-generated if not provided) */
+    state?: string;
+    /** Nonce for ID token validation */
+    nonce?: string;
+    /** Redirect to signup instead of login */
+    signup?: boolean;
+    /** Prompt parameter (none, login, consent, select_account) */
+    prompt?: 'none' | 'login' | 'consent' | 'select_account';
+    /** Login hint (email or username) */
+    loginHint?: string;
+}
+interface LogoutOptions {
+    /** Post-logout redirect URI */
+    returnTo?: string;
+    /** Include id_token_hint in logout request */
+    idTokenHint?: string;
+}
+interface CallbackResult {
+    success: boolean;
+    user?: User;
+    accessToken?: string;
+    idToken?: string;
+    refreshToken?: string;
+    error?: string;
+    errorDescription?: string;
+}
+interface OIDCDiscovery {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    jwks_uri: string;
+    end_session_endpoint?: string;
+    registration_endpoint?: string;
+    scopes_supported: string[];
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    code_challenge_methods_supported?: string[];
+}
+
+/**
+ * Stuffle IAM Client
+ *
+ * OIDC/OAuth2 client for browser-based applications.
+ * Supports authorization code flow with PKCE.
+ */
+
+declare class StuffleIAMClient {
+    private config;
+    private storage;
+    private discovery;
+    private refreshTimer;
+    private listeners;
+    constructor(config: StuffleIAMConfig);
+    /**
+     * Fetch OIDC discovery document
+     */
+    getDiscovery(): Promise<OIDCDiscovery>;
+    /**
+     * Start login flow - redirects to authorization endpoint
+     */
+    login(options?: LoginOptions): Promise<void>;
+    /**
+     * Alias for login({ signup: true })
+     */
+    signup(options?: Omit<LoginOptions, 'signup'>): Promise<void>;
+    /**
+     * Handle callback from authorization server
+     */
+    handleCallback(url?: string): Promise<CallbackResult>;
+    /**
+     * Exchange authorization code for tokens
+     */
+    private exchangeCode;
+    /**
+     * Refresh access token using refresh token
+     */
+    refreshToken(): Promise<TokenResponse | null>;
+    /**
+     * Logout - end session
+     */
+    logout(options?: LogoutOptions): Promise<void>;
+    /**
+     * Get current access token (refreshes if needed)
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Get current user from stored ID token
+     */
+    getUser(): User | null;
+    /**
+     * Fetch user info from userinfo endpoint
+     */
+    fetchUserInfo(accessToken?: string): Promise<User | null>;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get current auth state
+     */
+    getAuthState(): AuthState;
+    /**
+     * Subscribe to auth state changes
+     */
+    subscribe(listener: (state: AuthState) => void): () => void;
+    /**
+     * Store tokens in storage
+     */
+    private storeTokens;
+    /**
+     * Clear all stored tokens
+     */
+    private clearTokens;
+    /**
+     * Setup auto-refresh timer
+     */
+    private setupAutoRefresh;
+    /**
+     * Notify all listeners of state change
+     */
+    private notifyListeners;
+}
+/**
+ * Create a new Stuffle IAM client instance
+ */
+declare function createStuffleIAMClient(config: StuffleIAMConfig): StuffleIAMClient;
+
+export { type AuthState as A, type CallbackResult as C, type LoginOptions as L, type OIDCDiscovery as O, StuffleIAMClient as S, type TokenResponse as T, type User as U, type StuffleIAMConfig as a, type LogoutOptions as b, createStuffleIAMClient as c };

package/dist/client-CTKWBZ26.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Stuffle IAM SDK Types
+ */
+interface StuffleIAMConfig {
+    /** IAM server base URL (e.g., http://localhost:5000) */
+    issuer: string;
+    /** OAuth2 client ID */
+    clientId: string;
+    /** Redirect URI after login */
+    redirectUri: string;
+    /** Requested scopes (default: openid profile email) */
+    scopes?: string[];
+    /** Post-logout redirect URI */
+    postLogoutRedirectUri?: string;
+    /** Enable PKCE (default: true, recommended for SPAs) */
+    usePkce?: boolean;
+    /** Storage type for tokens (default: sessionStorage) */
+    storage?: 'localStorage' | 'sessionStorage' | 'memory';
+    /** Auto-refresh tokens before expiry (default: true) */
+    autoRefresh?: boolean;
+    /** Seconds before expiry to trigger refresh (default: 60) */
+    refreshThreshold?: number;
+}
+interface TokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+interface User {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    picture?: string;
+    username?: string;
+    roles?: string[];
+    tenantId?: string;
+    [key: string]: unknown;
+}
+interface AuthState {
+    isAuthenticated: boolean;
+    isLoading: boolean;
+    user: User | null;
+    accessToken: string | null;
+    idToken: string | null;
+    error: Error | null;
+}
+interface LoginOptions {
+    /** Additional scopes to request */
+    scopes?: string[];
+    /** State parameter (auto-generated if not provided) */
+    state?: string;
+    /** Nonce for ID token validation */
+    nonce?: string;
+    /** Redirect to signup instead of login */
+    signup?: boolean;
+    /** Prompt parameter (none, login, consent, select_account) */
+    prompt?: 'none' | 'login' | 'consent' | 'select_account';
+    /** Login hint (email or username) */
+    loginHint?: string;
+}
+interface LogoutOptions {
+    /** Post-logout redirect URI */
+    returnTo?: string;
+    /** Include id_token_hint in logout request */
+    idTokenHint?: string;
+}
+interface CallbackResult {
+    success: boolean;
+    user?: User;
+    accessToken?: string;
+    idToken?: string;
+    refreshToken?: string;
+    error?: string;
+    errorDescription?: string;
+}
+interface OIDCDiscovery {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    jwks_uri: string;
+    end_session_endpoint?: string;
+    registration_endpoint?: string;
+    scopes_supported: string[];
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    code_challenge_methods_supported?: string[];
+}
+
+/**
+ * Stuffle IAM Client
+ *
+ * OIDC/OAuth2 client for browser-based applications.
+ * Supports authorization code flow with PKCE.
+ */
+
+declare class StuffleIAMClient {
+    private config;
+    private storage;
+    private discovery;
+    private refreshTimer;
+    private listeners;
+    constructor(config: StuffleIAMConfig);
+    /**
+     * Fetch OIDC discovery document
+     */
+    getDiscovery(): Promise<OIDCDiscovery>;
+    /**
+     * Start login flow - redirects to authorization endpoint
+     */
+    login(options?: LoginOptions): Promise<void>;
+    /**
+     * Alias for login({ signup: true })
+     */
+    signup(options?: Omit<LoginOptions, 'signup'>): Promise<void>;
+    /**
+     * Handle callback from authorization server
+     */
+    handleCallback(url?: string): Promise<CallbackResult>;
+    /**
+     * Exchange authorization code for tokens
+     */
+    private exchangeCode;
+    /**
+     * Refresh access token using refresh token
+     */
+    refreshToken(): Promise<TokenResponse | null>;
+    /**
+     * Logout - end session
+     */
+    logout(options?: LogoutOptions): Promise<void>;
+    /**
+     * Get current access token (refreshes if needed)
+     */
+    getAccessToken(): Promise<string | null>;
+    /**
+     * Get current user from stored ID token
+     */
+    getUser(): User | null;
+    /**
+     * Fetch user info from userinfo endpoint
+     */
+    fetchUserInfo(accessToken?: string): Promise<User | null>;
+    /**
+     * Check if user is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get current auth state
+     */
+    getAuthState(): AuthState;
+    /**
+     * Subscribe to auth state changes
+     */
+    subscribe(listener: (state: AuthState) => void): () => void;
+    /**
+     * Store tokens in storage
+     */
+    private storeTokens;
+    /**
+     * Clear all stored tokens
+     */
+    private clearTokens;
+    /**
+     * Setup auto-refresh timer
+     */
+    private setupAutoRefresh;
+    /**
+     * Notify all listeners of state change
+     */
+    private notifyListeners;
+}
+/**
+ * Create a new Stuffle IAM client instance
+ */
+declare function createStuffleIAMClient(config: StuffleIAMConfig): StuffleIAMClient;
+
+export { type AuthState as A, type CallbackResult as C, type LoginOptions as L, type OIDCDiscovery as O, StuffleIAMClient as S, type TokenResponse as T, type User as U, type StuffleIAMConfig as a, type LogoutOptions as b, createStuffleIAMClient as c };

package/dist/index.d.mts

@@ -0,0 +1,41 @@
+export { A as AuthState, C as CallbackResult, L as LoginOptions, b as LogoutOptions, O as OIDCDiscovery, S as StuffleIAMClient, a as StuffleIAMConfig, T as TokenResponse, U as User, c as createStuffleIAMClient } from './client-CTKWBZ26.mjs';
+
+/**
+ * Utility functions for PKCE and crypto operations
+ */
+/**
+ * Generate a random string for state/nonce
+ */
+declare function generateRandomString(length?: number): string;
+/**
+ * Generate PKCE code verifier (43-128 characters)
+ */
+declare function generateCodeVerifier(): string;
+/**
+ * Generate PKCE code challenge from verifier
+ */
+declare function generateCodeChallenge(verifier: string): Promise<string>;
+/**
+ * Decode JWT payload (without verification)
+ */
+declare function decodeJwtPayload<T = Record<string, unknown>>(token: string): T | null;
+/**
+ * Check if token is expired
+ */
+declare function isTokenExpired(token: string, thresholdSeconds?: number): boolean;
+
+/**
+ * Token storage abstraction
+ */
+interface TokenStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/**
+ * Get storage adapter based on type
+ */
+declare function getStorage(type: 'localStorage' | 'sessionStorage' | 'memory'): TokenStorage;
+
+export { type TokenStorage, decodeJwtPayload, generateCodeChallenge, generateCodeVerifier, generateRandomString, getStorage, isTokenExpired };

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+export { A as AuthState, C as CallbackResult, L as LoginOptions, b as LogoutOptions, O as OIDCDiscovery, S as StuffleIAMClient, a as StuffleIAMConfig, T as TokenResponse, U as User, c as createStuffleIAMClient } from './client-CTKWBZ26.js';
+
+/**
+ * Utility functions for PKCE and crypto operations
+ */
+/**
+ * Generate a random string for state/nonce
+ */
+declare function generateRandomString(length?: number): string;
+/**
+ * Generate PKCE code verifier (43-128 characters)
+ */
+declare function generateCodeVerifier(): string;
+/**
+ * Generate PKCE code challenge from verifier
+ */
+declare function generateCodeChallenge(verifier: string): Promise<string>;
+/**
+ * Decode JWT payload (without verification)
+ */
+declare function decodeJwtPayload<T = Record<string, unknown>>(token: string): T | null;
+/**
+ * Check if token is expired
+ */
+declare function isTokenExpired(token: string, thresholdSeconds?: number): boolean;
+
+/**
+ * Token storage abstraction
+ */
+interface TokenStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/**
+ * Get storage adapter based on type
+ */
+declare function getStorage(type: 'localStorage' | 'sessionStorage' | 'memory'): TokenStorage;
+
+export { type TokenStorage, decodeJwtPayload, generateCodeChallenge, generateCodeVerifier, generateRandomString, getStorage, isTokenExpired };