@revealui/auth 0.2.0 → 0.3.0

package/README.md

@@ -1,21 +1,17 @@
 # @revealui/auth
 
-**Status:** 🟡 Active Development | ⚠️ NOT Production Ready
-
-See [Project Status](../../docs/PROJECT_STATUS.md) for framework readiness.
-
-Authentication system for RevealUI - database-backed sessions with Better Auth patterns.
-
-> **⚠️ Security Note:** Auth implementation exists but requires independent security audit before production use.
+Session-based authentication for RevealUI — database-backed sessions, rate limiting, brute force protection, and password reset.
 
 ## Features
 
-- ✅ Database-backed sessions (PostgreSQL/NeonDB)
-- ✅ Secure token handling (SHA-256 hashing, HTTP-only cookies)
-- ✅ CSRF protection (SameSite cookies)
-- ✅ Type-safe (TypeScript)
-- ✅ Framework agnostic (Next.js, TanStack Start)
-- ✅ React hooks for client-side usage
+- **Database Sessions** — PostgreSQL/NeonDB-backed sessions with SHA-256 token hashing
+- **Secure Cookies** — HTTP-only, SameSite, secure flag, cross-subdomain support
+- **Rate Limiting** — Configurable per-endpoint rate limits stored in database
+- **Brute Force Protection** — Progressive lockout on failed sign-in attempts
+- **Password Reset** — Token-based password reset flow with email integration
+- **Password Validation** — Strength requirements and common password checks
+- **React Hooks** — Client-side session management (`useSession`, `useSignIn`, `useSignOut`)
+- **Framework Agnostic** — Works with Next.js, Hono, and other Node.js frameworks
 
 ## Installation
 
@@ -25,36 +21,34 @@ pnpm add @revealui/auth
 
 ## Usage
 
-### Server-side (Next.js API Routes)
+### Server-Side
 
 ```typescript
-import { getSession } from '@revealui/auth/server'
-import { type NextRequest, NextResponse } from 'next/server'
+import { getSession, signIn, signOut, createSession } from '@revealui/auth/server'
 
-export async function GET(request: NextRequest) {
-  const session = await getSession(request.headers)
-  
-  if (!session) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-  }
+// Validate session from request headers
+const session = await getSession(request.headers)
 
-  return NextResponse.json({ user: session.user })
-}
+// Sign in with email/password
+const result = await signIn({ email, password })
+
+// Sign out (invalidate session)
+await signOut(sessionToken)
 ```
 
-### Client-side (React Hooks)
+### Client-Side (React)
 
 ```typescript
 'use client'
 import { useSession, useSignIn, useSignOut } from '@revealui/auth/react'
 
-function MyComponent() {
+function AuthComponent() {
   const { data: session, isLoading } = useSession()
   const { signIn } = useSignIn()
   const { signOut } = useSignOut()
 
   if (isLoading) return <div>Loading...</div>
-  if (!session) return <div>Not signed in</div>
+  if (!session) return <button onClick={() => signIn({ email, password })}>Sign In</button>
 
   return (
     <div>
@@ -65,13 +59,43 @@ function MyComponent() {
 }
 ```
 
-## API Routes
+## Exports
+
+| Subpath | Contents |
+|---------|----------|
+| `@revealui/auth/server` | Server-side auth (session CRUD, sign in/out, rate limiting, brute force) |
+| `@revealui/auth/client` | Client-side utilities |
+| `@revealui/auth/react` | React hooks (`useSession`, `useSignIn`, `useSignOut`) |
+
+## Security
+
+- Passwords hashed with bcrypt
+- Session tokens hashed with SHA-256 before storage
+- HTTP-only cookies prevent XSS token theft
+- SameSite cookie attribute prevents CSRF
+- Rate limiting prevents abuse (configurable per endpoint)
+- Brute force protection with progressive lockout
+- Cookie domain supports cross-subdomain auth (e.g. `.revealui.com`)
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Type check
+pnpm typecheck
+
+# Run tests
+pnpm test
+```
+
+## Related
 
-- `GET /api/auth/session` - Get current session
-- `POST /api/auth/sign-in` - Sign in with email/password
-- `POST /api/auth/sign-up` - Create new account
-- `POST /api/auth/sign-out` - Sign out
+- [Core Package](../core/README.md) — CMS engine (uses auth for access control)
+- [DB Package](../db/README.md) — Database schema (sessions, users, rate_limits tables)
+- [Auth Guide](../../docs/AUTH.md) — Architecture, usage patterns, and security design
 
-## Documentation
+## License
 
-See [Auth System Design](../../docs/reference/auth/AUTH_SYSTEM_DESIGN.md) for comprehensive documentation.
+MIT

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAA;AAEhC,cAAc,mBAAmB,CAAA;AAGjC,YAAY,EACV,WAAW,EACX,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,IAAI,GACL,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,kBAAkB,CAAC;AAEjC,cAAc,mBAAmB,CAAC;AAGlC,YAAY,EACV,WAAW,EACX,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,IAAI,GACL,MAAM,YAAY,CAAC"}

package/dist/react/index.d.ts

@@ -4,6 +4,10 @@
  * Client-side React hooks for authentication.
  * Inspired by Better Auth and TanStack Start patterns.
  */
+export type { MFASetupData, UseMFASetupResult, UseMFAVerifyResult, } from './useMFA.js';
+export { useMFASetup, useMFAVerify } from './useMFA.js';
+export type { PasskeyRegisterOptions, PasskeyRegisterResult, UsePasskeyRegisterResult, UsePasskeySignInResult, } from './usePasskey.js';
+export { usePasskeyRegister, usePasskeySignIn } from './usePasskey.js';
 export type { UseSessionResult } from './useSession.js';
 export { useSession } from './useSession.js';
 export type { SignInInput, UseSignInResult } from './useSignIn.js';

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACxD,YAAY,EACV,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACvE,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/react/index.js

@@ -4,6 +4,8 @@
  * Client-side React hooks for authentication.
  * Inspired by Better Auth and TanStack Start patterns.
  */
+export { useMFASetup, useMFAVerify } from './useMFA.js';
+export { usePasskeyRegister, usePasskeySignIn } from './usePasskey.js';
 export { useSession } from './useSession.js';
 export { useSignIn } from './useSignIn.js';
 export { useSignOut } from './useSignOut.js';

package/dist/react/useMFA.d.ts

@@ -0,0 +1,83 @@
+/**
+ * MFA Hooks
+ *
+ * React hooks for Multi-Factor Authentication setup and verification.
+ */
+/**
+ * MFA setup data returned when initiating TOTP setup.
+ */
+export interface MFASetupData {
+    /** Base32-encoded TOTP secret */
+    secret: string;
+    /** otpauth:// URI for QR code generation */
+    uri: string;
+    /** One-time backup codes for account recovery */
+    backupCodes: string[];
+}
+export interface UseMFASetupResult {
+    /** Initiate MFA setup — returns secret, QR URI, and backup codes */
+    setup: () => Promise<MFASetupData | null>;
+    /** Verify a TOTP code to confirm setup */
+    verifySetup: (code: string) => Promise<boolean>;
+    isLoading: boolean;
+    error: string | null;
+}
+/**
+ * Hook for MFA setup on the security settings page.
+ *
+ * @returns Setup and verify functions, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function SecuritySettings() {
+ *   const { setup, verifySetup, isLoading, error } = useMFASetup();
+ *
+ *   const handleEnable = async () => {
+ *     const data = await setup();
+ *     if (data) {
+ *       // Show QR code using data.uri, display backup codes
+ *     }
+ *   };
+ *
+ *   const handleVerify = async (code: string) => {
+ *     const success = await verifySetup(code);
+ *     if (success) {
+ *       // MFA is now enabled
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export declare function useMFASetup(): UseMFASetupResult;
+export interface UseMFAVerifyResult {
+    /** Verify a TOTP code during login */
+    verify: (code: string) => Promise<boolean>;
+    /** Verify a backup code during login */
+    verifyBackupCode: (code: string) => Promise<boolean>;
+    isLoading: boolean;
+    error: string | null;
+}
+/**
+ * Hook for MFA verification during the login flow.
+ *
+ * After sign-in returns `requiresMfa: true`, redirect to the MFA page
+ * and use this hook to complete authentication.
+ *
+ * @returns Verify functions, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function MFAPage() {
+ *   const { verify, verifyBackupCode, isLoading, error } = useMFAVerify();
+ *
+ *   const handleSubmit = async (code: string) => {
+ *     const success = await verify(code);
+ *     if (success) {
+ *       router.push('/admin');
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export declare function useMFAVerify(): UseMFAVerifyResult;
+//# sourceMappingURL=useMFA.d.ts.map

package/dist/react/useMFA.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useMFA.d.ts","sourceRoot":"","sources":["../../src/react/useMFA.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,oEAAoE;IACpE,KAAK,EAAE,MAAM,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC1C,0CAA0C;IAC1C,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAChD,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,WAAW,IAAI,iBAAiB,CAqE/C;AAED,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,wCAAwC;IACxC,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACrD,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,IAAI,kBAAkB,CAsEjD"}

package/dist/react/useMFA.js

@@ -0,0 +1,182 @@
+/**
+ * MFA Hooks
+ *
+ * React hooks for Multi-Factor Authentication setup and verification.
+ */
+'use client';
+import { useState } from 'react';
+/**
+ * Hook for MFA setup on the security settings page.
+ *
+ * @returns Setup and verify functions, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function SecuritySettings() {
+ *   const { setup, verifySetup, isLoading, error } = useMFASetup();
+ *
+ *   const handleEnable = async () => {
+ *     const data = await setup();
+ *     if (data) {
+ *       // Show QR code using data.uri, display backup codes
+ *     }
+ *   };
+ *
+ *   const handleVerify = async (code: string) => {
+ *     const success = await verifySetup(code);
+ *     if (success) {
+ *       // MFA is now enabled
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export function useMFASetup() {
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const setup = async () => {
+        try {
+            setIsLoading(true);
+            setError(null);
+            const response = await fetch('/api/auth/mfa/setup', {
+                method: 'POST',
+                credentials: 'include',
+            });
+            const json = await response.json();
+            if (!response.ok) {
+                const errorData = json;
+                setError(errorData.error ?? 'Failed to set up MFA');
+                return null;
+            }
+            const data = json;
+            return data;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            setError(message);
+            return null;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    };
+    const verifySetup = async (code) => {
+        try {
+            setIsLoading(true);
+            setError(null);
+            const response = await fetch('/api/auth/mfa/verify-setup', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                credentials: 'include',
+                body: JSON.stringify({ code }),
+            });
+            const json = await response.json();
+            if (!response.ok) {
+                const errorData = json;
+                setError(errorData.error ?? 'Failed to verify MFA code');
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            setError(message);
+            return false;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    };
+    return {
+        setup,
+        verifySetup,
+        isLoading,
+        error,
+    };
+}
+/**
+ * Hook for MFA verification during the login flow.
+ *
+ * After sign-in returns `requiresMfa: true`, redirect to the MFA page
+ * and use this hook to complete authentication.
+ *
+ * @returns Verify functions, loading state, and error
+ *
+ * @example
+ * ```tsx
+ * function MFAPage() {
+ *   const { verify, verifyBackupCode, isLoading, error } = useMFAVerify();
+ *
+ *   const handleSubmit = async (code: string) => {
+ *     const success = await verify(code);
+ *     if (success) {
+ *       router.push('/admin');
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export function useMFAVerify() {
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    const verify = async (code) => {
+        try {
+            setIsLoading(true);
+            setError(null);
+            const response = await fetch('/api/auth/mfa/verify', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                credentials: 'include',
+                body: JSON.stringify({ code }),
+            });
+            const json = await response.json();
+            if (!response.ok) {
+                const errorData = json;
+                setError(errorData.error ?? 'Invalid verification code');
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            setError(message);
+            return false;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    };
+    const verifyBackupCode = async (code) => {
+        try {
+            setIsLoading(true);
+            setError(null);
+            const response = await fetch('/api/auth/mfa/backup', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                credentials: 'include',
+                body: JSON.stringify({ code }),
+            });
+            const json = await response.json();
+            if (!response.ok) {
+                const errorData = json;
+                setError(errorData.error ?? 'Invalid backup code');
+                return false;
+            }
+            return true;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            setError(message);
+            return false;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    };
+    return {
+        verify,
+        verifyBackupCode,
+        isLoading,
+        error,
+    };
+}

package/dist/react/usePasskey.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Passkey Hooks
+ *
+ * React hooks for WebAuthn passkey registration and authentication.
+ * Uses dynamic imports for @simplewebauthn/browser to avoid SSR issues.
+ */
+export interface PasskeyRegisterOptions {
+    /** Email for passkey registration (sign-up flow) */
+    email?: string;
+    /** Display name for the credential */
+    name?: string;
+    /** Human-readable device name (e.g., "MacBook Pro") */
+    deviceName?: string;
+}
+export interface PasskeyRegisterResult {
+    /** Backup codes returned during sign-up flow */
+    backupCodes?: string[];
+}
+export interface UsePasskeyRegisterResult {
+    /** Register a new passkey credential */
+    register: (options?: PasskeyRegisterOptions) => Promise<PasskeyRegisterResult | null>;
+    isLoading: boolean;
+    error: string | null;
+    /** Whether the browser supports WebAuthn */
+    supported: boolean;
+}
+/**
+ * Hook for passkey registration (sign-up and security settings).
+ *
+ * @returns Register function, loading state, error, and browser support flag
+ *
+ * @example
+ * ```tsx
+ * function AddPasskey() {
+ *   const { register, isLoading, error, supported } = usePasskeyRegister();
+ *
+ *   if (!supported) return <p>Passkeys are not supported in this browser.</p>;
+ *
+ *   const handleAdd = async () => {
+ *     const result = await register({ deviceName: 'My Laptop' });
+ *     if (result) {
+ *       // Passkey registered successfully
+ *     }
+ *   };
+ * }
+ * ```
+ */
+export declare function usePasskeyRegister(): UsePasskeyRegisterResult;
+export interface UsePasskeySignInResult {
+    /** Authenticate with a passkey */
+    signIn: () => Promise<boolean>;
+    isLoading: boolean;
+    error: string | null;
+    /** Whether the browser supports WebAuthn */
+    supported: boolean;
+}
+/**
+ * Hook for passkey authentication (login page).
+ *
+ * @returns Sign-in function, loading state, error, and browser support flag
+ *
+ * @example
+ * ```tsx
+ * function LoginPage() {
+ *   const { signIn, isLoading, error, supported } = usePasskeySignIn();
+ *
+ *   const handlePasskeyLogin = async () => {
+ *     const success = await signIn();
+ *     if (success) {
+ *       router.push('/admin');
+ *     }
+ *   };
+ *
+ *   return (
+ *     <>
+ *       {supported && (
+ *         <button onClick={handlePasskeyLogin} disabled={isLoading}>
+ *           Sign in with Passkey
+ *         </button>
+ *       )}
+ *       {error && <p>{error}</p>}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePasskeySignIn(): UsePasskeySignInResult;
+//# sourceMappingURL=usePasskey.d.ts.map

package/dist/react/usePasskey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usePasskey.d.ts","sourceRoot":"","sources":["../../src/react/usePasskey.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,WAAW,sBAAsB;IACrC,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,sBAAsB,KAAK,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAC;IACtF,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,kBAAkB,IAAI,wBAAwB,CA0F7D;AAED,MAAM,WAAW,sBAAsB;IACrC,kCAAkC;IAClC,MAAM,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,4CAA4C;IAC5C,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,IAAI,sBAAsB,CA8EzD"}