@drmhse/authos-react 0.1.3 → 0.1.5

package/README.md

@@ -5,293 +5,404 @@
 
 React adapter for [AuthOS](https://authos.dev) - the multi-tenant authentication platform. Provides React hooks, components, and Next.js integration.
 
-## Installation
+## Quick Start (5 minutes)
 
 ```bash
 npm install @drmhse/authos-react
 ```
 
-Peer dependencies:
-```bash
-npm install react react-dom
+Wrap your app with `AuthOSProvider` and you're ready to go:
+
+```tsx
+import { AuthOSProvider, SignIn, SignedIn, SignedOut, UserButton } from '@drmhse/authos-react';
+
+function App() {
+  return (
+    <AuthOSProvider config={{ baseURL: 'https://sso.example.com' }}>
+      <SignedOut>
+        <SignIn onSuccess={(user) => console.log('Welcome', user.email)} />
+      </SignedOut>
+      <SignedIn>
+        <UserButton />
+        <p>You're signed in!</p>
+      </SignedIn>
+    </AuthOSProvider>
+  );
+}
+```
+
+That's it. You now have:
+- Email/password authentication with MFA support
+- Automatic session management
+- User dropdown with logout
+- Conditional rendering based on auth state
+
+## Usage Modes
+
+AuthOS supports two usage modes:
+
+### Platform-Level Access
+
+For platform owners and administrators, use without `org`/`service`:
+
+```tsx
+<AuthOSProvider config={{ baseURL: 'https://sso.example.com' }}>
+  <SignIn />
+</AuthOSProvider>
+```
+
+### Multi-Tenant Access (Organizations)
+
+For tenant applications with OAuth support, add `org` and `service`:
+
+```tsx
+<AuthOSProvider config={{
+  baseURL: 'https://sso.example.com',
+  org: 'acme-corp',    // Organization slug
+  service: 'main-app', // Service slug  
+}}>
+  <SignIn providers={['github', 'google']} />
+</AuthOSProvider>
+```
+
+To use OAuth providers (GitHub, Google, Microsoft), you need to configure your organization and service in the provider:
+
+```tsx
+<AuthOSProvider config={{
+  baseURL: 'https://sso.example.com',
+  org: 'my-org',           // Your organization slug
+  service: 'my-app',       // Your service slug
+  redirectUri: 'https://app.example.com/callback', // Optional
+}}>
+  <SignIn providers={['github', 'google', 'microsoft']} />
+</AuthOSProvider>
 ```
 
-## Quick Start
+### Using an Existing Client
 
-Wrap your app with `AuthOSProvider`, then use the hooks and components throughout your app.
+For advanced use cases, you can pass a pre-configured `SsoClient`:
 
 ```tsx
+import { SsoClient } from '@drmhse/sso-sdk';
 import { AuthOSProvider } from '@drmhse/authos-react';
 
+// Create client with custom configuration
+const client = new SsoClient({
+  baseURL: 'https://sso.example.com',
+  storage: customStorage,
+});
+
 function App() {
   return (
-    <AuthOSProvider
-      config={{
-        baseURL: 'https://sso.example.com'
-      }}
-    >
-      <YourApp />
+    <AuthOSProvider client={client}>
+      <SignIn />
     </AuthOSProvider>
   );
 }
+
+Or use individual OAuth buttons:
+
+```tsx
+import { OAuthButton } from '@drmhse/authos-react';
+
+<OAuthButton provider="github">Sign in with GitHub</OAuthButton>
+<OAuthButton provider="google" />
+<OAuthButton provider="microsoft" />
 ```
 
 ## Components
 
 ### SignIn
 
-Pre-built sign-in form with email/password and OAuth provider buttons.
+Complete sign-in form with email/password authentication and optional OAuth buttons.
 
 ```tsx
-import { SignIn } from '@drmhse/authos-react';
-
-function LoginPage() {
-  return (
-    <SignIn
-      onSuccess={() => console.log('Logged in!')}
-      onError={(err) => console.error(err)}
-    />
-  );
-}
+<SignIn
+  onSuccess={(user) => console.log('Logged in:', user)}
+  onError={(error) => console.error(error)}
+  providers={['github', 'google']}   // Optional OAuth buttons
+  showForgotPassword={true}          // Show forgot password link
+  showSignUp={true}                  // Show sign up link
+  showDivider={true}                 // Show "or" divider between OAuth and email form
+/>
 ```
 
 **Props:**
-| Prop | Type | Description |
-|------|------|-------------|
-| `onSuccess` | `() => void` | Callback after successful login |
-| `onError` | `(error: Error) => void` | Callback on login error |
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `onSuccess` | `(user: UserProfile) => void` | - | Callback after successful login |
+| `onError` | `(error: Error) => void` | - | Callback on login error |
+| `providers` | `('github' \| 'google' \| 'microsoft')[] \| false` | `false` | OAuth providers to display |
+| `showForgotPassword` | `boolean` | `true` | Show forgot password link |
+| `showSignUp` | `boolean` | `true` | Show sign up link |
+| `showDivider` | `boolean` | `true` | Show divider between OAuth and email form |
+| `className` | `string` | - | Custom class name |
 
 ### SignUp
 
 Registration form for new users.
 
 ```tsx
-import { SignUp } from '@drmhse/authos-react';
+<SignUp
+  onSuccess={() => console.log('Check your email!')}
+  onError={(error) => console.error(error)}
+  orgSlug="my-org"  // Optional: pre-fill organization
+/>
+```
 
-function RegisterPage() {
-  return (
-    <SignUp
-      onSuccess={() => console.log('Registered!')}
-      onError={(err) => console.error(err)}
-    />
-  );
-}
+### MagicLinkSignIn
+
+Sign-in component for Magic Links (passwordless).
+
+```tsx
+<MagicLinkSignIn onSuccess={() => console.log('Magic link sent!')} />
 ```
 
-**Props:** Same as `SignIn`
+### PasskeySignIn
 
-### UserButton
+Sign-in component for Passkeys (WebAuthn).
 
-User menu button that shows avatar/name and dropdown with profile/signout.
+```tsx
+<PasskeySignIn onSuccess={() => console.log('Authenticated!')} />
+```
+
+### SignedIn / SignedOut
+
+Conditional rendering based on authentication state. Inspired by Clerk's API.
 
 ```tsx
-import { UserButton } from '@drmhse/authos-react';
+<SignedIn>
+  {/* Only shown when user is logged in */}
+  <UserButton />
+</SignedIn>
+
+<SignedOut>
+  {/* Only shown when user is logged out */}
+  <SignIn />
+</SignedOut>
+```
 
-function Header() {
-  return <UserButton />;
-}
+### UserButton
+
+User menu button with avatar initials and dropdown with profile/signout.
+
+```tsx
+<UserButton
+  showEmail={true}
+  onLogout={() => router.push('/')}
+/>
 ```
 
 ### OrganizationSwitcher
 
 Dropdown to switch between organizations (for multi-tenant users).
 
-```tsx
-import { OrganizationSwitcher } from '@drmhse/authos-react';
+When switching organizations, the SDK automatically issues new JWT tokens with the new organization context, enabling seamless multi-tenant switching without re-authentication.
 
-function Sidebar() {
-  return <OrganizationSwitcher />;
-}
+```tsx
+<OrganizationSwitcher
+  onSwitch={(org) => console.log('Switched to:', org.name)}
+/>
 ```
 
 ### Protect
 
-Conditional rendering based on user permissions.
+Conditional rendering based on user permissions or roles.
 
 ```tsx
-import { Protect } from '@drmhse/authos-react';
+<Protect permission="admin:access" fallback={<p>Access denied</p>}>
+  <AdminDashboard />
+</Protect>
 
-function AdminPanel() {
-  return (
-    <Protect
-      permission="admin:access"
-      fallback={<p>Access denied. Admins only.</p>}
-    >
-      <AdminDashboard />
-    </Protect>
-  );
-}
+<Protect role="owner">
+  <DangerZone />
+</Protect>
 ```
 
-**Props:**
-| Prop | Type | Description |
-|------|------|-------------|
-| `permission` | `string` | Required permission to access content |
-| `fallback` | `ReactNode` | Shown when user lacks permission |
-| `children` | `ReactNode` | Protected content |
+### OAuthButton
+
+Individual OAuth provider button. Requires `org` and `service` in provider config.
+
+```tsx
+<OAuthButton provider="github" />
+<OAuthButton provider="google">Continue with Google</OAuthButton>
+```
 
 ## Hooks
 
 ### useAuthOS
 
-Access the AuthOS client directly.
+Access the AuthOS client and auth state.
 
 ```tsx
-import { useAuthOS } from '@drmhse/authos-react';
-
-function Profile() {
-  const { client, isAuthenticated, isLoading } = useAuthOS();
-
-  if (isLoading) return <div>Loading...</div>;
-  if (!isAuthenticated) return <div>Please log in</div>;
-
-  const handleLogout = async () => {
-    await client.auth.logout();
-  };
+const { client, config, isAuthenticated, isLoading } = useAuthOS();
 
-  return (
-    <div>
-      <button onClick={handleLogout}>Logout</button>
-    </div>
-  );
-}
+// Use the client directly
+await client.auth.logout();
 ```
 
-**Returns:**
-| Property | Type | Description |
-|----------|------|-------------|
-| `client` | `SsoClient` | The AuthOS SDK client |
-| `isLoading` | `boolean` | True while checking auth state |
-| `isAuthenticated` | `boolean` | True if user is logged in |
-
 ### useUser
 
 Get the current user's profile.
 
 ```tsx
-import { useUser } from '@drmhse/authos-react';
+const { user, isLoading } = useUser();
 
-function UserProfile() {
-  const { user, isLoading } = useUser();
+if (isLoading) return <Spinner />;
+if (!user) return <SignIn />;
 
-  if (isLoading) return <div>Loading...</div>;
-  return <div>Welcome, {user?.email}</div>;
-}
+return <p>Welcome, {user.email}</p>;
 ```
 
-**Returns:**
-| Property | Type | Description |
-|----------|------|-------------|
-| `user` | `UserProfile \| null` | Current user profile |
-| `isLoading` | `boolean` | True while checking auth state |
-
 ### useOrganization
 
-Get the current organization and list of organizations.
+Get and switch between organizations.
 
 ```tsx
-import { useOrganization } from '@drmhse/authos-react';
-
-function OrgInfo() {
-  const { currentOrganization, organizations } = useOrganization();
-
-  return (
-    <div>
-      <h3>{currentOrganization?.name}</h3>
-      <ul>
-        {organizations.map((org) => (
-          <li key={org.id}>{org.name}</li>
-        ))}
-      </ul>
-    </div>
-  );
-}
+const { 
+  currentOrganization, 
+  organizations, 
+  switchOrganization, 
+  isSwitching 
+} = useOrganization();
+
+// Switch to a different org
+await switchOrganization('other-org-slug');
 ```
 
-**Returns:**
-| Property | Type | Description |
-|----------|------|-------------|
-| `currentOrganization` | `Organization \| null` | Current organization |
-| `organizations` | `Organization[]` | All user's organizations |
-| `switchOrganization` | `(slug: string) => Promise<void>` | Switch to a different org |
-| `isSwitching` | `boolean` | True while switching |
-
-### usePermission, useAnyPermission, useAllPermissions
+### usePermission / useAnyPermission / useAllPermissions
 
 Check user permissions.
 
 ```tsx
-import { usePermission } from '@drmhse/authos-react';
+const canAccessAdmin = usePermission('admin:access');
+const canReadOrWrite = useAnyPermission(['read:data', 'write:data']);
+const hasFullAccess = useAllPermissions(['read:data', 'write:data', 'delete:data']);
 
-function AdminButton() {
-  const canAccessAdmin = usePermission('admin:access');
-
-  if (!canAccessAdmin) return null;
-
-  return <button>Admin Panel</button>;
-}
+if (!canAccessAdmin) return <AccessDenied />;
 ```
 
 ## Next.js Integration
 
-For Next.js App Router, use the middleware and server utilities:
+### App Router
 
 ```tsx
-// middleware.ts
-import { authMiddleware } from '@drmhse/authos-react/nextjs';
+// app/layout.tsx
+import { AuthOSProvider } from '@drmhse/authos-react';
+import { cookies } from 'next/headers';
+
+export default async function RootLayout({ children }) {
+  const cookieStore = cookies();
+  const token = cookieStore.get('authos_token')?.value;
+
+  return (
+    <html>
+      <body>
+        <AuthOSProvider
+          config={{ baseURL: process.env.NEXT_PUBLIC_SSO_URL! }}
+          initialSessionToken={token}
+        >
+          {children}
+        </AuthOSProvider>
+      </body>
+    </html>
+  );
+}
+```
 
-export default authMiddleware();
+### Middleware (Next.js)
+
+```ts
+// middleware.ts
+import { authMiddleware, getJwksUrl } from '@drmhse/authos-react/nextjs';
+
+export default authMiddleware({
+  jwksUrl: getJwksUrl(process.env.NEXT_PUBLIC_SSO_URL!),
+  protectedRoutes: ['/dashboard/*', '/settings/*'],
+  publicRoutes: ['/', '/about', '/pricing'],
+  signInUrl: '/signin',
+});
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+};
 ```
 
+### Server Components
+
 ```tsx
 // app/dashboard/page.tsx
 import { currentUser } from '@drmhse/authos-react/nextjs';
 
 export default async function Dashboard() {
   const user = await currentUser();
-
+  
   if (!user) {
-    return <div>Please log in</div>;
+    redirect('/login');
   }
 
   return <div>Welcome, {user.email}</div>;
 }
 ```
 
-## API Reference
+## Configuration Reference
 
 ### AuthOSProvider Props
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `config.baseURL` | `string` | **required** | AuthOS API URL (e.g., `https://sso.example.com`) |
-| `config.storage` | `TokenStorage` | `localStorage` | Custom token storage |
-| `config.autoRefresh` | `boolean` | `true` | Auto-refresh expired tokens |
-| `config.onAuthStateChange` | `(user) => void` | - | Callback when auth state changes |
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `config.baseURL` | `string` | ✅ | AuthOS API URL |
+| `config.org` | `string` | For OAuth | Organization slug for OAuth flows |
+| `config.service` | `string` | For OAuth | Service slug for OAuth flows |
+| `config.redirectUri` | `string` | - | OAuth redirect URI (defaults to origin + '/callback') |
+| `config.afterSignInUrl` | `string` | - | Redirect URL after sign-in |
+| `config.afterSignUpUrl` | `string` | - | Redirect URL after sign-up |
+| `config.storage` | `TokenStorage` | - | Custom token storage |
+| `client` | `SsoClient` | - | Use existing client instance |
+| `initialSessionToken` | `string` | - | SSR token for hydration |
+
+## Styling
+
+All components use data attributes for styling hooks. Use CSS selectors:
+
+```css
+[data-authos-signin] { /* Container */ }
+[data-authos-field="email"] { /* Email field wrapper */ }
+[data-authos-field="password"] { /* Password field wrapper */ }
+[data-authos-submit] { /* Submit button */ }
+[data-authos-error] { /* Error message */ }
+[data-authos-oauth] { /* OAuth button */ }
+[data-authos-oauth][data-provider="github"] { /* GitHub button */ }
+[data-authos-divider] { /* "or" divider */ }
+```
 
-### SsoClient
+## Security Considerations
 
-The underlying client from `@drmhse/sso-sdk`. See [SDK docs](https://www.npmjs.com/package/@drmhse/sso-sdk) for full API.
+### Token Storage
 
-```tsx
-const { client } = useAuthOS();
+The SDK offers multiple storage options:
 
-// Authentication
-await client.auth.login({ email, password });
-await client.auth.logout();
-await client.auth.register({ email, password, org_slug });
+| Storage | Environment | Security Notes |
+|---------|-------------|----------------|
+| `BrowserStorage` | Client-side | Uses localStorage, accessible to JS |
+| `CookieStorage` | SSR (Next.js) | Non-httpOnly cookies, accessible to JS |
+| `MemoryStorage` | SSR/Testing | In-memory, lost on page refresh |
 
-// User
-await client.user.getProfile();
-await client.user.updateProfile({ name });
-await client.user.changePassword({ old, new });
+> [!WARNING]
+> `CookieStorage` and `BrowserStorage` store tokens accessible to JavaScript.
+> For maximum security in production, consider:
+> - Using httpOnly cookies set by your backend
+> - Implementing a Backend-for-Frontend (BFF) pattern
+> - Ensuring proper CSP headers to mitigate XSS
 
-// Organizations
-await client.organizations.list();
-await client.organizations.get(slug);
+### JWT Verification
 
-// And more...
-```
+The Next.js middleware and Node adapter provide independent JWT verification:
+- **Next.js middleware**: Uses Web Crypto API (`crypto.subtle`) for Edge Runtime
+- **Node adapter**: Uses Node.js `crypto` module
+
+This duplication is intentional due to runtime differences. Both implementations
+verify signatures using your JWKS endpoint.
 
 ## License