@douvery/auth 0.1.0

package/README.md

@@ -0,0 +1,231 @@
+# @douvery/auth
+
+OAuth 2.0/OIDC client library for Douvery authentication.
+
+## Packages
+
+| Package | Description |
+|---------|-------------|
+| [@douvery/auth](./packages/core) | Core client library (vanilla TypeScript) |
+| [@douvery/auth-react](./packages/react) | React hooks and components |
+| [@douvery/auth-qwik](./packages/qwik) | Qwik hooks and components |
+
+## Installation
+
+### React
+
+```bash
+npm install @douvery/auth-react
+# or
+pnpm add @douvery/auth-react
+```
+
+### Qwik
+
+```bash
+npm install @douvery/auth-qwik
+# or
+pnpm add @douvery/auth-qwik
+```
+
+### Vanilla TypeScript
+
+```bash
+npm install @douvery/auth
+# or
+pnpm add @douvery/auth
+```
+
+## Quick Start
+
+### React
+
+```tsx
+import { DouveryAuthProvider, useDouveryAuth } from '@douvery/auth-react';
+
+// Wrap your app with the provider
+function App() {
+  return (
+    <DouveryAuthProvider
+      config={{
+        clientId: 'your-client-id',
+        redirectUri: 'http://localhost:3000/callback',
+        issuer: 'https://auth.douvery.com',
+        scopes: ['openid', 'profile', 'email'],
+      }}
+    >
+      <YourApp />
+    </DouveryAuthProvider>
+  );
+}
+
+// Use the hook in your components
+function LoginButton() {
+  const { login, logout, isAuthenticated, user } = useDouveryAuth();
+
+  if (isAuthenticated) {
+    return (
+      <div>
+        <p>Welcome, {user?.name}!</p>
+        <button onClick={() => logout()}>Logout</button>
+      </div>
+    );
+  }
+
+  return <button onClick={() => login()}>Login</button>;
+}
+```
+
+### Qwik
+
+```tsx
+import { DouveryAuthProvider, useDouveryAuth } from '@douvery/auth-qwik';
+import { component$ } from '@builder.io/qwik';
+
+// Wrap your app with the provider
+export default component$(() => {
+  return (
+    <DouveryAuthProvider
+      config={{
+        clientId: 'your-client-id',
+        redirectUri: 'http://localhost:5173/callback',
+        issuer: 'https://auth.douvery.com',
+        scopes: ['openid', 'profile', 'email'],
+      }}
+    >
+      <Slot />
+    </DouveryAuthProvider>
+  );
+});
+
+// Use the hook in your components
+export const LoginButton = component$(() => {
+  const { login, logout, isAuthenticated, user } = useDouveryAuth();
+
+  return (
+    <>
+      {isAuthenticated.value ? (
+        <div>
+          <p>Welcome, {user.value?.name}!</p>
+          <button onClick$={() => logout()}>Logout</button>
+        </div>
+      ) : (
+        <button onClick$={() => login()}>Login</button>
+      )}
+    </>
+  );
+});
+```
+
+### Vanilla TypeScript
+
+```typescript
+import { createDouveryAuth } from '@douvery/auth';
+
+const auth = createDouveryAuth({
+  clientId: 'your-client-id',
+  redirectUri: 'http://localhost:3000/callback',
+  issuer: 'https://auth.douvery.com',
+  scopes: ['openid', 'profile', 'email'],
+});
+
+// Initialize (checks for existing session or handles callback)
+await auth.initialize();
+
+// Login
+await auth.login();
+
+// After callback, get user
+const user = auth.getUser();
+console.log(user);
+
+// Get access token (auto-refreshes if needed)
+const token = await auth.getAccessToken();
+
+// Logout
+await auth.logout();
+```
+
+## Configuration Options
+
+```typescript
+interface DouveryAuthConfig {
+  /** OAuth Client ID */
+  clientId: string;
+
+  /** Authorization server base URL (default: "https://auth.douvery.com") */
+  issuer?: string;
+
+  /** Redirect URI after authentication */
+  redirectUri: string;
+
+  /** Post-logout redirect URI */
+  postLogoutRedirectUri?: string;
+
+  /** OAuth scopes to request (default: ["openid", "profile", "email"]) */
+  scopes?: string[];
+
+  /** Token storage strategy (default: "localStorage") */
+  storage?: "localStorage" | "sessionStorage" | "memory" | "cookie";
+
+  /** Auto-refresh tokens before expiry (default: true) */
+  autoRefresh?: boolean;
+
+  /** Seconds before expiry to trigger refresh (default: 60) */
+  refreshThreshold?: number;
+
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+```
+
+## Login Options
+
+```typescript
+await auth.login({
+  // URL to return to after login
+  returnTo: '/dashboard',
+
+  // Force re-authentication
+  prompt: 'login',
+
+  // Pre-fill email
+  loginHint: 'user@example.com',
+
+  // UI locale
+  uiLocales: 'es',
+});
+```
+
+## Features
+
+- ✅ **PKCE Support** - Secure authorization code flow with PKCE
+- ✅ **Auto Token Refresh** - Automatic token refresh before expiry
+- ✅ **Multiple Storage Options** - localStorage, sessionStorage, memory, or cookies
+- ✅ **TypeScript First** - Full TypeScript support with comprehensive types
+- ✅ **Framework Adapters** - React and Qwik adapters with hooks
+- ✅ **Event System** - Subscribe to auth events (login, logout, token refresh, etc.)
+- ✅ **SSR Compatible** - Works with server-side rendering
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build all packages
+pnpm build
+
+# Run in development mode
+pnpm dev
+
+# Type check
+pnpm typecheck
+
+# Clean build outputs
+pnpm clean
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,352 @@
+/**
+ * @douvery/auth - Core Types
+ * OAuth 2.0/OIDC type definitions
+ */
+interface DouveryAuthConfig {
+    /** OAuth Client ID */
+    clientId: string;
+    /** Authorization server base URL @default "https://auth.douvery.com" */
+    issuer?: string;
+    /** Redirect URI after authentication */
+    redirectUri: string;
+    /** Post-logout redirect URI */
+    postLogoutRedirectUri?: string;
+    /** OAuth scopes to request @default ["openid", "profile", "email"] */
+    scopes?: string[];
+    /** Token storage strategy @default "localStorage" */
+    storage?: "localStorage" | "sessionStorage" | "memory" | "cookie";
+    /** Custom storage implementation */
+    customStorage?: TokenStorage;
+    /** Auto-refresh tokens before expiry @default true */
+    autoRefresh?: boolean;
+    /** Seconds before expiry to trigger refresh @default 60 */
+    refreshThreshold?: number;
+    /** Enable debug logging @default false */
+    debug?: boolean;
+}
+interface TokenSet {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+}
+interface TokenInfo {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    expiresAt: number;
+    tokenType: string;
+    scope: string[];
+}
+interface DecodedIdToken {
+    iss: string;
+    sub: string;
+    aud: string;
+    exp: number;
+    iat: number;
+    auth_time?: number;
+    nonce?: string;
+    acr?: string;
+    amr?: string[];
+    azp?: string;
+    at_hash?: string;
+    c_hash?: string;
+    name?: string;
+    given_name?: string;
+    family_name?: string;
+    middle_name?: string;
+    nickname?: string;
+    preferred_username?: string;
+    profile?: string;
+    picture?: string;
+    website?: string;
+    email?: string;
+    email_verified?: boolean;
+    gender?: string;
+    birthdate?: string;
+    zoneinfo?: string;
+    locale?: string;
+    phone_number?: string;
+    phone_number_verified?: boolean;
+    address?: {
+        formatted?: string;
+        street_address?: string;
+        locality?: string;
+        region?: string;
+        postal_code?: string;
+        country?: string;
+    };
+    updated_at?: number;
+    [key: string]: unknown;
+}
+interface User {
+    id: string;
+    email?: string;
+    emailVerified?: boolean;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    picture?: string;
+    phoneNumber?: string;
+    phoneNumberVerified?: boolean;
+    locale?: string;
+    [key: string]: unknown;
+}
+type AuthStatus = "loading" | "authenticated" | "unauthenticated";
+interface AuthState {
+    status: AuthStatus;
+    user: User | null;
+    tokens: TokenInfo | null;
+    error: AuthError | null;
+}
+interface PKCEPair {
+    codeVerifier: string;
+    codeChallenge: string;
+    codeChallengeMethod: "S256";
+}
+interface TokenStorage {
+    get(key: string): string | null | Promise<string | null>;
+    set(key: string, value: string): void | Promise<void>;
+    remove(key: string): void | Promise<void>;
+    clear(): void | Promise<void>;
+}
+interface StorageKeys {
+    accessToken: string;
+    refreshToken: string;
+    idToken: string;
+    expiresAt: string;
+    state: string;
+    nonce: string;
+    codeVerifier: string;
+    returnTo: string;
+}
+type AuthEvent = {
+    type: "INITIALIZED";
+} | {
+    type: "LOGIN_STARTED";
+} | {
+    type: "LOGIN_SUCCESS";
+    user: User;
+    tokens: TokenInfo;
+} | {
+    type: "LOGIN_ERROR";
+    error: AuthError;
+} | {
+    type: "LOGOUT_STARTED";
+} | {
+    type: "LOGOUT_SUCCESS";
+} | {
+    type: "LOGOUT_ERROR";
+    error: AuthError;
+} | {
+    type: "TOKEN_REFRESHED";
+    tokens: TokenInfo;
+} | {
+    type: "TOKEN_REFRESH_ERROR";
+    error: AuthError;
+} | {
+    type: "SESSION_EXPIRED";
+};
+type AuthEventHandler = (event: AuthEvent) => void;
+declare class AuthError extends Error {
+    code: AuthErrorCode;
+    cause?: Error | undefined;
+    constructor(code: AuthErrorCode, message: string, cause?: Error | undefined);
+}
+type AuthErrorCode = "invalid_request" | "invalid_client" | "invalid_grant" | "unauthorized_client" | "unsupported_grant_type" | "invalid_scope" | "access_denied" | "server_error" | "temporarily_unavailable" | "login_required" | "consent_required" | "interaction_required" | "invalid_token" | "insufficient_scope" | "token_expired" | "token_refresh_failed" | "pkce_error" | "state_mismatch" | "nonce_mismatch" | "network_error" | "configuration_error" | "unknown_error";
+interface OIDCDiscovery {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    userinfo_endpoint: string;
+    jwks_uri: string;
+    revocation_endpoint?: string;
+    introspection_endpoint?: string;
+    end_session_endpoint?: string;
+    registration_endpoint?: string;
+    scopes_supported: string[];
+    response_types_supported: string[];
+    response_modes_supported?: string[];
+    grant_types_supported: string[];
+    token_endpoint_auth_methods_supported?: string[];
+    subject_types_supported: string[];
+    id_token_signing_alg_values_supported: string[];
+    claims_supported?: string[];
+    code_challenge_methods_supported?: string[];
+}
+interface CallbackResult {
+    success: boolean;
+    user?: User;
+    tokens?: TokenInfo;
+    error?: AuthError;
+    returnTo?: string;
+}
+interface LoginOptions {
+    /** URL to return to after login */
+    returnTo?: string;
+    /** Additional authorization parameters */
+    authorizationParams?: Record<string, string>;
+    /** Prompt parameter (none, login, consent, select_account) */
+    prompt?: "none" | "login" | "consent" | "select_account";
+    /** Login hint (email or identifier) */
+    loginHint?: string;
+    /** UI locales preference */
+    uiLocales?: string;
+    /** Maximum authentication age in seconds */
+    maxAge?: number;
+    /** ACR values requested */
+    acrValues?: string;
+}
+interface LogoutOptions {
+    /** URL to return to after logout */
+    returnTo?: string;
+    /** Whether to federate logout (end session at IdP) @default true */
+    federated?: boolean;
+    /** Only clear local session, don't redirect @default false */
+    localOnly?: boolean;
+}
+
+/**
+ * @douvery/auth - Auth Client
+ * Main OAuth 2.0/OIDC client implementation
+ */
+
+declare class DouveryAuthClient {
+    private config;
+    private tokenManager;
+    private discovery;
+    private eventHandlers;
+    private refreshTimer;
+    private state;
+    constructor(config: DouveryAuthConfig);
+    /** Initialize the auth client */
+    initialize(): Promise<AuthState>;
+    /** Start the login flow */
+    login(options?: LoginOptions): Promise<void>;
+    /** Logout the user */
+    logout(options?: LogoutOptions): Promise<void>;
+    /** Check if current URL is an OAuth callback */
+    isCallback(): boolean;
+    /** Handle the OAuth callback */
+    handleCallback(): Promise<CallbackResult>;
+    private exchangeCode;
+    /** Refresh the access token */
+    refreshTokens(): Promise<TokenInfo>;
+    /** Get current access token (auto-refreshes if needed) */
+    getAccessToken(): Promise<string | null>;
+    private tokenSetToInfo;
+    private fetchUser;
+    private extractUserFromIdToken;
+    private normalizeUser;
+    private getDiscovery;
+    private setupAutoRefresh;
+    private clearAutoRefresh;
+    getState(): AuthState;
+    isAuthenticated(): boolean;
+    getUser(): User | null;
+    subscribe(handler: AuthEventHandler): () => void;
+    private updateState;
+    private emit;
+    private log;
+}
+/** Create a new DouveryAuthClient instance */
+declare function createDouveryAuth(config: DouveryAuthConfig): DouveryAuthClient;
+
+/**
+ * @douvery/auth - PKCE Utilities
+ * RFC 7636 - Proof Key for Code Exchange
+ */
+
+/** Generate a cryptographically random string for use as code_verifier */
+declare function generateCodeVerifier(length?: number): string;
+/** Generate a random state parameter for CSRF protection */
+declare function generateState(): string;
+/** Generate a random nonce for replay attack protection */
+declare function generateNonce(): string;
+/** Create SHA-256 hash and encode as base64url */
+declare function generateCodeChallenge(verifier: string): Promise<string>;
+/** Encode ArrayBuffer as base64url (RFC 4648 Section 5) */
+declare function base64UrlEncode(buffer: ArrayBuffer): string;
+/** Decode base64url string to ArrayBuffer */
+declare function base64UrlDecode(input: string): ArrayBuffer;
+/** Generate a complete PKCE pair (verifier + challenge) */
+declare function generatePKCEPair(): Promise<PKCEPair>;
+/** Verify a code_verifier against a code_challenge */
+declare function verifyCodeChallenge(verifier: string, challenge: string, method?: "S256" | "plain"): Promise<boolean>;
+/** Parse and decode a JWT token (without verification) */
+declare function decodeJWT<T = Record<string, unknown>>(token: string): T;
+/** Check if a JWT token is expired */
+declare function isTokenExpired(token: string, clockSkew?: number): boolean;
+/** Get token expiration timestamp */
+declare function getTokenExpiration(token: string): number | null;
+
+/**
+ * @douvery/auth - Token Storage
+ * Abstraction for token persistence
+ */
+
+declare const STORAGE_KEYS: StorageKeys;
+/** In-memory storage implementation */
+declare class MemoryStorage implements TokenStorage {
+    private store;
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/** LocalStorage implementation */
+declare class LocalStorage implements TokenStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/** SessionStorage implementation */
+declare class SessionStorage implements TokenStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/** Cookie storage implementation (for SSR compatibility) */
+declare class CookieStorage implements TokenStorage {
+    private options;
+    constructor(options?: {
+        path?: string;
+        domain?: string;
+        secure?: boolean;
+        sameSite?: "Strict" | "Lax" | "None";
+        maxAge?: number;
+    });
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+    clear(): void;
+}
+/** Create storage instance based on type */
+declare function createStorage(type: "localStorage" | "sessionStorage" | "memory" | "cookie"): TokenStorage;
+/** Token manager for handling token persistence */
+declare class TokenManager {
+    private storage;
+    constructor(storage: TokenStorage);
+    getTokens(): Promise<TokenInfo | null>;
+    setTokens(tokens: TokenInfo): Promise<void>;
+    clearTokens(): Promise<void>;
+    saveState(state: string): Promise<void>;
+    getState(): Promise<string | null>;
+    clearState(): Promise<void>;
+    saveNonce(nonce: string): Promise<void>;
+    getNonce(): Promise<string | null>;
+    clearNonce(): Promise<void>;
+    saveCodeVerifier(verifier: string): Promise<void>;
+    getCodeVerifier(): Promise<string | null>;
+    clearCodeVerifier(): Promise<void>;
+    saveReturnTo(url: string): Promise<void>;
+    getReturnTo(): Promise<string | null>;
+    clearReturnTo(): Promise<void>;
+    clearAll(): Promise<void>;
+}
+
+export { AuthError, type AuthErrorCode, type AuthEvent, type AuthEventHandler, type AuthState, type AuthStatus, type CallbackResult, CookieStorage, type DecodedIdToken, DouveryAuthClient, type DouveryAuthConfig, LocalStorage, type LoginOptions, type LogoutOptions, MemoryStorage, type OIDCDiscovery, type PKCEPair, STORAGE_KEYS, SessionStorage, type StorageKeys, type TokenInfo, TokenManager, type TokenSet, type TokenStorage, type User, base64UrlDecode, base64UrlEncode, createDouveryAuth, createStorage, decodeJWT, generateCodeChallenge, generateCodeVerifier, generateNonce, generatePKCEPair, generateState, getTokenExpiration, isTokenExpired, verifyCodeChallenge };