mulguard 1.0.1

package/README.md

@@ -0,0 +1,368 @@
+# Mukey - Modern Authentication Library
+
+> Backend-first authentication library for Next.js and modern web applications
+
+[![License](https://img.shields.io/badge/license-MUV-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue.svg)](https://www.typescriptlang.org/)
+
+Mukey is a modern, secure authentication library designed for Next.js applications with a backend-first architecture. It provides a simple API similar to `better-auth` and `auth.js`, while maintaining full control over your backend authentication logic.
+
+## ✨ Features
+
+- 🔐 **Multiple Auth Methods**
+  - Email/Password authentication
+  - OAuth 2.1 (Google, GitHub, etc.)
+  - PassKey/WebAuthn support
+  - Two-Factor Authentication (2FA/TOTP)
+
+- 🎯 **Account Picker**
+  - Remember last logged-in users
+  - Quick re-login experience
+  - Encrypted local storage
+
+- 🔒 **Security First**
+  - CSRF protection
+  - XSS prevention
+  - Input validation & sanitization
+  - Security headers
+  - Rate limiting utilities
+
+- ⚡ **Next.js Optimized**
+  - Server Components support
+  - Client hooks (`useAuth`, `useSession`)
+  - Middleware integration
+  - API route handlers
+
+- 🔌 **Backend-First**
+  - No database adapter required
+  - Works with your existing backend API
+  - Mulink integration support
+  - Full TypeScript support
+
+## 📦 Installation
+
+```bash
+npm install mukey
+```
+
+## 🚀 Quick Start
+
+### 1. Create Auth Configuration
+
+```typescript
+// lib/auth.ts
+import { mukey } from 'mukey'
+// import { apiClient } from '@mulink/client' // Optional: Use Mulink
+
+export const auth = mukey({
+  // Option 1: Use Mulink API client
+  // apiClient: apiClient,
+
+  // Option 2: Use baseURL
+  baseURL: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3001',
+  
+  session: {
+    cookieName: '__mukey_session',
+    expiresIn: 60 * 60 * 24 * 7, // 7 days
+  },
+  
+  providers: {
+    oauth: {
+      google: {
+        clientId: process.env.GOOGLE_CLIENT_ID!,
+        redirectUri: `${process.env.NEXT_PUBLIC_URL}/api/auth/callback/google`,
+        scopes: ['openid', 'profile', 'email'],
+      },
+    },
+  },
+  
+  accountPicker: {
+    enabled: true,
+    maxAccounts: 3,
+  },
+})
+```
+
+### 2. Server-Side Usage
+
+```typescript
+// app/dashboard/page.tsx
+import { getServerSession } from 'mukey/server'
+import { auth } from '@/lib/auth'
+import { redirect } from 'next/navigation'
+
+export default async function DashboardPage() {
+  const session = await getServerSession(auth)
+  
+  if (!session) {
+    redirect('/login')
+  }
+  
+  return <div>Welcome, {session.user.name}!</div>
+}
+```
+
+### 3. Client-Side Usage
+
+```typescript
+// app/login/page.tsx
+'use client'
+
+import { useAuth } from 'mukey/client'
+import { auth } from '@/lib/auth'
+import { useState } from 'react'
+
+export default function LoginPage() {
+  const { signIn, session, isLoading } = useAuth(auth)
+  const [email, setEmail] = useState('')
+  const [password, setPassword] = useState('')
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault()
+    const result = await signIn.email({ email, password })
+    if (result.success) {
+      // Redirect to dashboard
+    }
+  }
+
+  if (isLoading) return <div>Loading...</div>
+  if (session) return <div>Already logged in</div>
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input
+        type="email"
+        value={email}
+        onChange={(e) => setEmail(e.target.value)}
+        placeholder="Email"
+      />
+      <input
+        type="password"
+        value={password}
+        onChange={(e) => setPassword(e.target.value)}
+        placeholder="Password"
+      />
+      <button type="submit">Sign In</button>
+    </form>
+  )
+}
+```
+
+### 4. Middleware (Optional)
+
+```typescript
+// middleware.ts
+import { createAuthMiddleware } from 'mukey/middleware'
+import { auth } from '@/lib/auth'
+
+export default createAuthMiddleware(auth, {
+  protectedRoutes: ['/dashboard', '/profile'],
+  redirectTo: '/login',
+  redirectIfAuthenticated: '/dashboard',
+})
+```
+
+## 📚 Documentation
+
+- [Getting Started](./docs/GETTING_STARTED.md)
+- [Authentication Methods](./docs/AUTH_METHODS.md)
+- [Server-Side Usage](./docs/SERVER_USAGE.md)
+- [Client-Side Usage](./docs/CLIENT_USAGE.md)
+- [Security](./docs/SECURITY.md)
+- [Backend Integration](./docs/BACKEND_INTEGRATION.md)
+- [API Reference](./docs/API_REFERENCE.md)
+
+## 🔧 Configuration
+
+### Full Configuration Options
+
+```typescript
+import { mukey } from 'mukey'
+
+export const auth = mukey({
+  // API Client (from Mulink) or baseURL
+  apiClient: apiClient, // Optional
+  baseURL: 'http://localhost:3001', // Required if apiClient not provided
+  
+  // Session configuration
+  session: {
+    cookieName: '__mukey_session',
+    expiresIn: 60 * 60 * 24 * 7, // 7 days in seconds
+    httpOnly: true,
+    secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax',
+  },
+  
+  // OAuth providers
+  providers: {
+    oauth: {
+      google: {
+        clientId: '...',
+        redirectUri: '...',
+        scopes: ['openid', 'profile', 'email'],
+        name: 'Google',
+      },
+      github: {
+        clientId: '...',
+        redirectUri: '...',
+        scopes: ['user:email'],
+      },
+    },
+  },
+  
+  // 2FA configuration
+  twoFactor: {
+    enabled: true,
+  },
+  
+  // Account Picker
+  accountPicker: {
+    enabled: true,
+    maxAccounts: 3,
+    encryptStorage: true,
+    storageKey: '__mukey_accounts',
+  },
+  
+  // Security
+  security: {
+    csrfProtection: true,
+    rateLimiting: {
+      maxAttempts: 5,
+      windowMs: 15 * 60 * 1000, // 15 minutes
+    },
+  },
+})
+```
+
+## 🎨 Components
+
+### Account Picker
+
+```typescript
+import { AccountPicker } from 'mukey'
+
+<AccountPicker
+  auth={auth}
+  onSelectUser={(user) => {
+    // Pre-fill email or handle quick login
+    setEmail(user.email)
+  }}
+  onUseDifferentAccount={() => {
+    // Show full login form
+  }}
+/>
+```
+
+### OAuth Button
+
+```typescript
+import { OAuthButton } from 'mukey'
+
+<OAuthButton
+  auth={auth}
+  provider="google"
+  onSuccess={() => {
+    // Handle success
+  }}
+/>
+```
+
+### 2FA Setup
+
+```typescript
+import { TwoFactorSetup } from 'mukey'
+
+<TwoFactorSetup
+  auth={auth}
+  onSuccess={() => {
+    // 2FA enabled
+  }}
+/>
+```
+
+## 🔌 Backend Integration
+
+Mukey expects your backend to provide the following endpoints:
+
+### Authentication Endpoints
+
+- `POST /api/auth/sign-in` - Sign in with email/password
+- `POST /api/auth/sign-up` - Register new user
+- `POST /api/auth/sign-out` - Sign out
+- `GET /api/auth/session` - Get current session
+- `POST /api/auth/reset-password` - Request password reset
+- `POST /api/auth/verify-email` - Verify email address
+
+### OAuth Endpoints
+
+- `GET /api/auth/oauth/:provider` - Initiate OAuth flow
+- `POST /api/auth/oauth/:provider/callback` - Handle OAuth callback
+
+### 2FA Endpoints
+
+- `POST /api/auth/2fa/enable` - Enable 2FA
+- `POST /api/auth/2fa/verify` - Verify 2FA code
+- `POST /api/auth/2fa/disable` - Disable 2FA
+- `POST /api/auth/2fa/regenerate` - Generate backup codes
+- `GET /api/auth/2fa/status` - Check 2FA status
+
+### PassKey Endpoints
+
+- `POST /api/auth/passkey/register` - Register PassKey
+- `POST /api/auth/passkey/authenticate` - Authenticate with PassKey
+- `GET /api/auth/passkey/list` - List registered PassKeys
+- `DELETE /api/auth/passkey/:id` - Remove PassKey
+
+See [Backend Integration Guide](./docs/BACKEND_INTEGRATION.md) for detailed API specifications.
+
+## 🔒 Security
+
+Mukey implements multiple security features:
+
+- **CSRF Protection** - Token-based CSRF protection
+- **XSS Prevention** - Input sanitization and HTML escaping
+- **Rate Limiting** - Client-side rate limit tracking
+- **Security Headers** - Automatic security headers
+- **Input Validation** - Comprehensive input validation
+- **Secure Cookies** - HttpOnly, Secure, SameSite cookies
+
+See [Security Guide](./docs/SECURITY.md) for more details.
+
+## 🧪 Testing
+
+```bash
+# Run tests
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Coverage
+npm run test:coverage
+```
+
+## 🚀 CI/CD
+
+This project uses GitHub Actions with npm Trusted Publisher for secure publishing.
+
+- **CI**: Runs on every push/PR (lint, test, build)
+- **Publishing**: Automatic publishing via Changesets or manual release
+- **Security**: Uses OIDC (OpenID Connect) for authentication
+
+See [README_CI.md](./README_CI.md) for setup instructions.
+
+## 📝 License
+
+MUV License - See [LICENSE](./LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines first.
+
+## 📧 Support
+
+For questions and support, please open an issue on GitHub.
+
+---
+
+Made with ❤️ by the Mukey Team

package/dist/actions-CExpv_dD.js

@@ -0,0 +1 @@
+"use strict";const O=require("next/headers");var r=(s=>(s.INVALID_CREDENTIALS="INVALID_CREDENTIALS",s.ACCOUNT_LOCKED="ACCOUNT_LOCKED",s.ACCOUNT_INACTIVE="ACCOUNT_INACTIVE",s.TWO_FA_REQUIRED="TWO_FA_REQUIRED",s.INVALID_TWO_FA_CODE="INVALID_TWO_FA_CODE",s.SESSION_EXPIRED="SESSION_EXPIRED",s.UNAUTHORIZED="UNAUTHORIZED",s.NETWORK_ERROR="NETWORK_ERROR",s.VALIDATION_ERROR="VALIDATION_ERROR",s.RATE_LIMITED="RATE_LIMITED",s.UNKNOWN_ERROR="UNKNOWN_ERROR",s))(r||{});async function R(s){var n;try{return(n=(await O.cookies()).get(s))==null?void 0:n.value}catch(e){const o=(e==null?void 0:e.message)||"";if(o.includes("cookies")||o.includes("request scope")||o.includes("outside")||o.includes("dynamic"))return;throw e}}async function u(s){try{return(await O.cookies()).set({name:s.name,value:s.value,maxAge:s.maxAge,expires:s.expires,httpOnly:s.httpOnly??!0,secure:s.secure,sameSite:s.sameSite??"lax",path:s.path??"/",domain:s.domain}),{success:!0}}catch(n){const e=(n==null?void 0:n.message)||"";if(e.includes("cookies")||e.includes("request scope")||e.includes("outside")||e.includes("dynamic")){const o=`Cannot set cookie "${s.name}" outside request scope. Make sure this is called from a Server Action or Route Handler.`;return process.env.NODE_ENV==="development"&&console.warn(`[Mulguard] ${o}`),{success:!1,error:e,warning:o}}throw n}}async function f(s,n){try{(await O.cookies()).set({name:s,value:"",maxAge:0,expires:new Date(0),httpOnly:!0,path:(n==null?void 0:n.path)??"/",domain:n==null?void 0:n.domain})}catch(e){const o=(e==null?void 0:e.message)||"";if(o.includes("cookies")||o.includes("request scope")||o.includes("outside")||o.includes("dynamic")){process.env.NODE_ENV==="development"&&console.warn(`[Mulguard] Cannot delete cookie "${s}" outside request scope`);return}throw e}}function l(s,n,e){const o=process.env.NODE_ENV==="production";return{name:s,value:n,maxAge:e.expiresIn,httpOnly:e.httpOnly??!0,secure:e.secure??o,sameSite:e.sameSite??"lax",path:e.path??"/"}}async function g(s,n){if(!s.verify2FA)return{success:!1,error:"2FA verification is not configured",errorCode:r.VALIDATION_ERROR};try{const e=await s.verify2FA(n,{skipCookieSave:!0});if(e.success&&e.session)try{const{cookieName:o,config:t}=s._getSessionConfig(),c=typeof e.session=="object"&&"token"in e.session?String(e.session.token):JSON.stringify(e.session),i=l(o,c,t),a=await u(i);a.success||process.env.NODE_ENV==="development"&&console.warn("[Mulguard] Failed to save session after 2FA verification:",a.error||a.warning)}catch(o){process.env.NODE_ENV==="development"&&console.warn("[Mulguard] Failed to save session cookie:",o)}return e}catch(e){return{success:!1,error:e instanceof Error?e.message:"2FA verification failed",errorCode:r.UNKNOWN_ERROR}}}async function N(s){var n;try{const e=await s.getSession(),o=e==null?void 0:e.user;s.signOut&&await s.signOut();const{cookieName:t,config:c}=s._getSessionConfig();await f(t,{path:c.path||"/"});const i=(n=s._getCallbacks)==null?void 0:n.call(s);return o&&(i!=null&&i.onSignOut)&&await i.onSignOut(o),{success:!0}}catch(e){return{success:!1,error:e instanceof Error?e.message:"Sign out failed"}}}async function d(s,n){var e;if(!((e=s.signIn)!=null&&e.email))return{success:!1,error:"Email sign in is not configured",errorCode:r.VALIDATION_ERROR};try{const o=await s.signIn.email(n);if(o.success&&o.session)try{const{cookieName:t,config:c}=s._getSessionConfig(),i=typeof o.session=="object"&&"token"in o.session?String(o.session.token):JSON.stringify(o.session),a=l(t,i,c);await u(a)}catch(t){process.env.NODE_ENV==="development"&&console.warn("[Mulguard] Failed to save session cookie:",t)}return o}catch(o){return{success:!1,error:o instanceof Error?o.message:"Sign in failed",errorCode:r.UNKNOWN_ERROR}}}async function E(s,n){if(!s.signUp)return{success:!1,error:"Sign up is not configured",errorCode:r.VALIDATION_ERROR};try{const e=await s.signUp(n);if(e.success&&e.session)try{const{cookieName:o,config:t}=s._getSessionConfig(),c=typeof e.session=="object"&&"token"in e.session?String(e.session.token):JSON.stringify(e.session),i=l(o,c,t);await u(i)}catch(o){process.env.NODE_ENV==="development"&&console.warn("[Mulguard] Failed to save session cookie:",o)}return e}catch(e){return{success:!1,error:e instanceof Error?e.message:"Sign up failed",errorCode:r.UNKNOWN_ERROR}}}const _=Object.freeze(Object.defineProperty({__proto__:null,signInEmailAction:d,signOutAction:N,signUpAction:E,verify2FAAction:g},Symbol.toStringTag,{value:"Module"}));exports.AuthErrorCode=r;exports.actions=_;exports.buildCookieOptions=l;exports.deleteCookie=f;exports.getCookie=R;exports.setCookie=u;exports.signInEmailAction=d;exports.signOutAction=N;exports.signUpAction=E;exports.verify2FAAction=g;

package/dist/actions-DeCfLtHA.mjs

@@ -0,0 +1,184 @@
+import { cookies as u } from "next/headers";
+var c = /* @__PURE__ */ ((s) => (s.INVALID_CREDENTIALS = "INVALID_CREDENTIALS", s.ACCOUNT_LOCKED = "ACCOUNT_LOCKED", s.ACCOUNT_INACTIVE = "ACCOUNT_INACTIVE", s.TWO_FA_REQUIRED = "TWO_FA_REQUIRED", s.INVALID_TWO_FA_CODE = "INVALID_TWO_FA_CODE", s.SESSION_EXPIRED = "SESSION_EXPIRED", s.UNAUTHORIZED = "UNAUTHORIZED", s.NETWORK_ERROR = "NETWORK_ERROR", s.VALIDATION_ERROR = "VALIDATION_ERROR", s.RATE_LIMITED = "RATE_LIMITED", s.UNKNOWN_ERROR = "UNKNOWN_ERROR", s))(c || {});
+async function _(s) {
+  var o;
+  try {
+    return (o = (await u()).get(s)) == null ? void 0 : o.value;
+  } catch (e) {
+    const n = (e == null ? void 0 : e.message) || "";
+    if (n.includes("cookies") || n.includes("request scope") || n.includes("outside") || n.includes("dynamic"))
+      return;
+    throw e;
+  }
+}
+async function l(s) {
+  try {
+    return (await u()).set({
+      name: s.name,
+      value: s.value,
+      maxAge: s.maxAge,
+      expires: s.expires,
+      httpOnly: s.httpOnly ?? !0,
+      secure: s.secure,
+      sameSite: s.sameSite ?? "lax",
+      path: s.path ?? "/",
+      domain: s.domain
+    }), { success: !0 };
+  } catch (o) {
+    const e = (o == null ? void 0 : o.message) || "";
+    if (e.includes("cookies") || e.includes("request scope") || e.includes("outside") || e.includes("dynamic")) {
+      const n = `Cannot set cookie "${s.name}" outside request scope. Make sure this is called from a Server Action or Route Handler.`;
+      return process.env.NODE_ENV === "development" && console.warn(`[Mulguard] ${n}`), {
+        success: !1,
+        error: e,
+        warning: n
+      };
+    }
+    throw o;
+  }
+}
+async function O(s, o) {
+  try {
+    (await u()).set({
+      name: s,
+      value: "",
+      maxAge: 0,
+      expires: /* @__PURE__ */ new Date(0),
+      httpOnly: !0,
+      path: (o == null ? void 0 : o.path) ?? "/",
+      domain: o == null ? void 0 : o.domain
+    });
+  } catch (e) {
+    const n = (e == null ? void 0 : e.message) || "";
+    if (n.includes("cookies") || n.includes("request scope") || n.includes("outside") || n.includes("dynamic")) {
+      process.env.NODE_ENV === "development" && console.warn(`[Mulguard] Cannot delete cookie "${s}" outside request scope`);
+      return;
+    }
+    throw e;
+  }
+}
+function f(s, o, e) {
+  const n = process.env.NODE_ENV === "production";
+  return {
+    name: s,
+    value: o,
+    maxAge: e.expiresIn,
+    httpOnly: e.httpOnly ?? !0,
+    secure: e.secure ?? n,
+    sameSite: e.sameSite ?? "lax",
+    path: e.path ?? "/"
+  };
+}
+async function g(s, o) {
+  if (!s.verify2FA)
+    return {
+      success: !1,
+      error: "2FA verification is not configured",
+      errorCode: c.VALIDATION_ERROR
+    };
+  try {
+    const e = await s.verify2FA(o, { skipCookieSave: !0 });
+    if (e.success && e.session)
+      try {
+        const { cookieName: n, config: r } = s._getSessionConfig(), t = typeof e.session == "object" && "token" in e.session ? String(e.session.token) : JSON.stringify(e.session), i = f(n, t, r), a = await l(i);
+        a.success || process.env.NODE_ENV === "development" && console.warn("[Mulguard] Failed to save session after 2FA verification:", a.error || a.warning);
+      } catch (n) {
+        process.env.NODE_ENV === "development" && console.warn("[Mulguard] Failed to save session cookie:", n);
+      }
+    return e;
+  } catch (e) {
+    return {
+      success: !1,
+      error: e instanceof Error ? e.message : "2FA verification failed",
+      errorCode: c.UNKNOWN_ERROR
+    };
+  }
+}
+async function N(s) {
+  var o;
+  try {
+    const e = await s.getSession(), n = e == null ? void 0 : e.user;
+    s.signOut && await s.signOut();
+    const { cookieName: r, config: t } = s._getSessionConfig();
+    await O(r, {
+      path: t.path || "/"
+    });
+    const i = (o = s._getCallbacks) == null ? void 0 : o.call(s);
+    return n && (i != null && i.onSignOut) && await i.onSignOut(n), { success: !0 };
+  } catch (e) {
+    return {
+      success: !1,
+      error: e instanceof Error ? e.message : "Sign out failed"
+    };
+  }
+}
+async function d(s, o) {
+  var e;
+  if (!((e = s.signIn) != null && e.email))
+    return {
+      success: !1,
+      error: "Email sign in is not configured",
+      errorCode: c.VALIDATION_ERROR
+    };
+  try {
+    const n = await s.signIn.email(o);
+    if (n.success && n.session)
+      try {
+        const { cookieName: r, config: t } = s._getSessionConfig(), i = typeof n.session == "object" && "token" in n.session ? String(n.session.token) : JSON.stringify(n.session), a = f(r, i, t);
+        await l(a);
+      } catch (r) {
+        process.env.NODE_ENV === "development" && console.warn("[Mulguard] Failed to save session cookie:", r);
+      }
+    return n;
+  } catch (n) {
+    return {
+      success: !1,
+      error: n instanceof Error ? n.message : "Sign in failed",
+      errorCode: c.UNKNOWN_ERROR
+    };
+  }
+}
+async function E(s, o) {
+  if (!s.signUp)
+    return {
+      success: !1,
+      error: "Sign up is not configured",
+      errorCode: c.VALIDATION_ERROR
+    };
+  try {
+    const e = await s.signUp(o);
+    if (e.success && e.session)
+      try {
+        const { cookieName: n, config: r } = s._getSessionConfig(), t = typeof e.session == "object" && "token" in e.session ? String(e.session.token) : JSON.stringify(e.session), i = f(n, t, r);
+        await l(i);
+      } catch (n) {
+        process.env.NODE_ENV === "development" && console.warn("[Mulguard] Failed to save session cookie:", n);
+      }
+    return e;
+  } catch (e) {
+    return {
+      success: !1,
+      error: e instanceof Error ? e.message : "Sign up failed",
+      errorCode: c.UNKNOWN_ERROR
+    };
+  }
+}
+const m = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  signInEmailAction: d,
+  signOutAction: N,
+  signUpAction: E,
+  verify2FAAction: g
+}, Symbol.toStringTag, { value: "Module" }));
+export {
+  c as A,
+  d as a,
+  E as b,
+  l as c,
+  O as d,
+  f as e,
+  m as f,
+  _ as g,
+  N as s,
+  g as v
+};

package/dist/client/hooks.d.ts

@@ -0,0 +1,122 @@
+import { Session, AuthResult, EmailCredentials, RegisterData, RememberedUser, Verify2FAData } from '../core/types';
+import { MulguardInstance } from '../mulguard';
+export interface UseAuthReturn {
+    session: Session | null;
+    isLoading: boolean;
+    /**
+     * Unified sign in method - professional interface similar to auth.js
+     *
+     * @example
+     * ```typescript
+     * // OAuth providers
+     * await signIn('google')
+     * await signIn('github')
+     *
+     * // Credentials
+     * await signIn('credentials', { email: 'user@example.com', password: 'password' })
+     *
+     * // OTP
+     * await signIn('otp', { email: 'user@example.com', code: '123456' })
+     * ```
+     */
+    signIn(provider: 'google' | 'github' | 'apple' | 'facebook' | string): Promise<{
+        url: string;
+        state: string;
+    }>;
+    signIn(provider: 'credentials', credentials: EmailCredentials): Promise<AuthResult>;
+    signIn(provider: 'otp', options: {
+        email: string;
+        code?: string;
+    }): Promise<AuthResult>;
+    signIn(provider: 'passkey', options?: {
+        userId?: string;
+    }): Promise<AuthResult>;
+    /**
+     * Legacy sign in methods (for backward compatibility)
+     */
+    signInMethods: {
+        email(credentials: EmailCredentials): Promise<AuthResult>;
+        oauth(provider: string): Promise<{
+            url: string;
+            state: string;
+        }>;
+        passkey(options?: {
+            userId?: string;
+        }): Promise<AuthResult>;
+        otp(email: string, code?: string): Promise<AuthResult>;
+    };
+    signUp(data: RegisterData): Promise<AuthResult>;
+    signOut(): Promise<void>;
+    resetPassword(email: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    verifyEmail(token: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    verify2FA(data: Verify2FAData): Promise<AuthResult>;
+}
+export interface UseSessionReturn {
+    session: Session | null;
+    isLoading: boolean;
+    error: Error | null;
+}
+export interface UseAccountPickerReturn {
+    lastUsers: RememberedUser[];
+    isLoading: boolean;
+    rememberUser: (user: {
+        id: string;
+        email: string;
+        name: string;
+        avatar?: string;
+    }, provider?: 'email' | 'oauth' | 'passkey') => Promise<void>;
+    clearUser: (userId: string) => Promise<void>;
+    clearAll: () => Promise<void>;
+    refresh: () => Promise<void>;
+}
+/**
+ * Main authentication hook
+ *
+ * @example
+ * ```tsx
+ * import { useAuth } from 'mulguard/client'
+ * import { auth } from '@/auth'
+ *
+ * function LoginButton() {
+ *   const { session, signIn, signOut } = useAuth(auth)
+ *   // ...
+ * }
+ * ```
+ */
+export declare function useAuth(auth: MulguardInstance): UseAuthReturn;
+/**
+ * Session hook
+ *
+ * @example
+ * ```tsx
+ * import { useSession } from 'mulguard/client'
+ * import { auth } from '@/auth'
+ *
+ * function Profile() {
+ *   const { session, isLoading } = useSession(auth)
+ *   // ...
+ * }
+ * ```
+ */
+export declare function useSession(auth: MulguardInstance): UseSessionReturn;
+/**
+ * Account Picker hook
+ *
+ * @example
+ * ```tsx
+ * import { useAccountPicker } from 'mulguard/client'
+ * import { auth } from '@/auth'
+ *
+ * function AccountList() {
+ *   const { lastUsers, clearUser } = useAccountPicker(auth)
+ *   // ...
+ * }
+ * ```
+ */
+export declare function useAccountPicker(auth: MulguardInstance): UseAccountPickerReturn;

package/dist/client/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Client-side hooks and utilities for Next.js
+ */
+export * from './hooks';
+export * from './provider';