@mdxui/auth 1.1.0

package/README.md

@@ -0,0 +1,319 @@
+# @mdxui/auth
+
+Authentication components and WorkOS AuthKit wrappers for mdxui applications. Provides a complete authentication solution with type-safe Zod schemas that extend mdxui's type system.
+
+## Installation
+
+```bash
+pnpm add @mdxui/auth
+```
+
+## Quick Start
+
+```tsx
+import {
+  IdentityProvider,
+  AuthGate,
+  useAuth,
+  UserProfile,
+} from '@mdxui/auth'
+
+function App() {
+  return (
+    <IdentityProvider clientId="client_xxx">
+      <AuthGate>
+        <Dashboard />
+      </AuthGate>
+    </IdentityProvider>
+  )
+}
+
+function Dashboard() {
+  const { user, getAccessToken } = useAuth()
+
+  return (
+    <div>
+      <h1>Welcome, {user?.firstName}!</h1>
+      <UserProfile authToken={getAccessToken} />
+    </div>
+  )
+}
+```
+
+## Features
+
+- **Authentication Providers** - `IdentityProvider` and `AuthGate` for managing auth state
+- **WorkOS Widgets** - Pre-built components for user management (profile, security, API keys)
+- **Type-Safe Schemas** - Zod schemas extending mdxui's `UserIdentity` and `Session` types
+- **React Hooks** - `useAuth` and `useWidgetToken` for accessing auth state
+- **UI Components** - Sign in/out buttons, user menu, team switcher
+
+## Exports
+
+### Main Entry (`@mdxui/auth`)
+
+Everything you need for most use cases:
+
+```tsx
+import {
+  // Providers
+  IdentityProvider,
+  IdentityProviderMinimal,
+  AuthGate,
+  WidgetsProvider,
+
+  // Widgets
+  UserProfile,
+  UserSecurity,
+  UserSessions,
+  ApiKeys,
+  UsersManagement,
+  OrganizationSwitcher,
+
+  // Components
+  SignInButton,
+  SignOutButton,
+  UserMenu,
+  TeamSwitcher,
+
+  // Hooks
+  useAuth,
+  useWidgetToken,
+
+  // Schemas
+  AuthUserSchema,
+  AuthSessionSchema,
+  AuthOrganizationSchema,
+} from '@mdxui/auth'
+
+// Types
+import type {
+  AuthUser,
+  AuthSession,
+  AuthOrganization,
+  AuthToken,
+} from '@mdxui/auth'
+```
+
+### Subpath Exports
+
+For more granular imports:
+
+```tsx
+// Only providers
+import { IdentityProvider, AuthGate } from '@mdxui/auth/providers'
+
+// Only widgets
+import { UserProfile, ApiKeys } from '@mdxui/auth/widgets'
+
+// Only components
+import { SignInButton, UserMenu } from '@mdxui/auth/components'
+
+// Only hooks
+import { useAuth, useWidgetToken } from '@mdxui/auth/hooks'
+
+// Only schemas (for runtime validation)
+import { AuthUserSchema, AuthSessionSchema } from '@mdxui/auth/schemas'
+
+// Only types
+import type { AuthUser, AuthGateProps } from '@mdxui/auth/types'
+```
+
+## Type System
+
+### AuthUser extends UserIdentity
+
+`AuthUser` extends mdxui's `UserIdentity` with WorkOS-specific fields:
+
+```tsx
+import type { UserIdentity } from 'mdxui/admin'
+import type { AuthUser } from '@mdxui/auth'
+
+// AuthUser includes all UserIdentity fields plus WorkOS extras
+const user: AuthUser = {
+  // From UserIdentity
+  id: 'user_123',
+  email: 'john@example.com',
+  firstName: 'John',
+  lastName: 'Doe',
+  roles: ['admin'],
+  permissions: ['users:read', 'users:write'],
+  organizationId: 'org_123',
+
+  // WorkOS-specific
+  emailVerified: true,
+  createdAt: '2024-01-01T00:00:00Z',
+  updatedAt: '2024-01-15T00:00:00Z',
+}
+
+// AuthUser is assignable to UserIdentity
+const identity: UserIdentity = user // Works!
+```
+
+### Runtime Validation with Zod
+
+Use schemas for validating API responses:
+
+```tsx
+import { AuthUserSchema, AuthSessionSchema } from '@mdxui/auth/schemas'
+
+// Validate user data
+const result = AuthUserSchema.safeParse(apiResponse)
+if (result.success) {
+  console.log('Valid user:', result.data.email)
+} else {
+  console.error('Invalid user:', result.error)
+}
+
+// Session with impersonation support
+const sessionResult = AuthSessionSchema.safeParse({
+  id: 'session_123',
+  userId: 'user_123',
+  createdAt: '2024-01-01T00:00:00Z',
+  expiresAt: '2024-01-02T00:00:00Z',
+  impersonator: {
+    email: 'admin@example.com',
+    reason: 'Customer support',
+  },
+})
+```
+
+## Components
+
+### IdentityProvider
+
+Wraps your app with authentication context:
+
+```tsx
+<IdentityProvider
+  clientId="client_xxx"
+  devMode={process.env.NODE_ENV === 'development'}
+  redirectUri="http://localhost:3000/callback"
+>
+  <App />
+</IdentityProvider>
+```
+
+### AuthGate
+
+Protects routes requiring authentication:
+
+```tsx
+// Redirect unauthenticated users
+<AuthGate onUnauthenticated="redirect" redirectUrl="/login">
+  <ProtectedContent />
+</AuthGate>
+
+// Show landing page for unauthenticated users
+<AuthGate
+  onUnauthenticated="landing"
+  landingComponent={<LandingPage />}
+  loadingComponent={<LoadingSpinner />}
+>
+  <Dashboard />
+</AuthGate>
+
+// Allow access but with different content
+<AuthGate onUnauthenticated="allow">
+  {({ user }) => user ? <Dashboard /> : <PublicView />}
+</AuthGate>
+```
+
+### Widgets
+
+Pre-built WorkOS widgets for user management:
+
+```tsx
+function SettingsPage() {
+  const { getAccessToken } = useAuth()
+
+  return (
+    <WidgetsProvider appearance="dark">
+      <Tabs>
+        <TabPanel label="Profile">
+          <UserProfile authToken={getAccessToken} />
+        </TabPanel>
+        <TabPanel label="Security">
+          <UserSecurity authToken={getAccessToken} />
+        </TabPanel>
+        <TabPanel label="Sessions">
+          <UserSessions authToken={getAccessToken} />
+        </TabPanel>
+        <TabPanel label="API Keys">
+          <ApiKeys authToken={getAccessToken} />
+        </TabPanel>
+      </Tabs>
+    </WidgetsProvider>
+  )
+}
+```
+
+### Hooks
+
+#### useAuth
+
+Access authentication state and methods:
+
+```tsx
+function ProfileButton() {
+  const {
+    user,           // Current user or null
+    isLoading,      // Loading state
+    isAuthenticated,// Boolean auth status
+    signIn,         // Sign in method
+    signOut,        // Sign out method
+    getAccessToken, // Get access token for API calls
+  } = useAuth()
+
+  if (isLoading) return <Spinner />
+  if (!isAuthenticated) return <SignInButton />
+
+  return <UserMenu user={user} onSignOut={signOut} />
+}
+```
+
+#### useWidgetToken
+
+Fetch tokens for WorkOS widgets:
+
+```tsx
+function ApiKeysWidget() {
+  const { token, loading, error, refetch } = useWidgetToken({
+    widget: 'api-keys',
+    organizationId: 'org_123',
+    endpoint: '/api/workos/widget-token', // default
+  })
+
+  if (loading) return <Spinner />
+  if (error) return <Error message={error} onRetry={refetch} />
+
+  return <ApiKeys authToken={token} />
+}
+```
+
+## API Reference
+
+### Schemas
+
+| Schema | Extends | Description |
+|--------|---------|-------------|
+| `AuthUserSchema` | `UserIdentitySchema` | User with WorkOS fields |
+| `AuthSessionSchema` | `SessionSchema` | Session with impersonation |
+| `AuthOrganizationSchema` | - | WorkOS organization |
+| `ImpersonatorSchema` | - | Admin impersonation info |
+| `AuthGatePropsSchema` | - | AuthGate component props |
+| `WidgetsProviderPropsSchema` | - | WidgetsProvider props |
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `AuthUser` | Inferred from `AuthUserSchema` |
+| `AuthSession` | Inferred from `AuthSessionSchema` |
+| `AuthOrganization` | WorkOS organization |
+| `AuthToken` | `string \| (() => Promise<string>)` |
+| `Impersonator` | Admin performing impersonation |
+
+## License
+
+MIT

package/dist/auth-Ba2f778e.d.ts

@@ -0,0 +1,116 @@
+import { ReactNode } from 'react';
+
+/**
+ * Authentication & Authorization Types
+ *
+ * Types for WorkOS AuthKit integration and identity management.
+ *
+ * Core types (AuthUser, AuthSession, AuthOrganization) are inferred
+ * from Zod schemas and extend mdxui's base types.
+ *
+ * React-specific props types include ReactNode fields that can't be
+ * represented in Zod schemas.
+ */
+
+/**
+ * Props for IdentityProvider
+ *
+ * Extends the schema type with React-specific fields.
+ */
+interface IdentityProviderProps {
+    /** WorkOS client ID */
+    clientId: string;
+    /** Optional API hostname override */
+    apiHostname?: string;
+    /** Enable dev mode for local development */
+    devMode?: boolean;
+    /** Redirect URI after authentication */
+    redirectUri?: string;
+    /** Callback after redirect */
+    onRedirectCallback?: () => void;
+    /** Children to render */
+    children: ReactNode;
+}
+/**
+ * Props for AuthGate
+ *
+ * Extends the schema type with React-specific fields.
+ */
+interface AuthGateProps {
+    /** Children to show when authenticated */
+    children: ReactNode;
+    /** Whether authentication is required (default: true) */
+    required?: boolean;
+    /** Component to show while loading */
+    loadingComponent?: ReactNode;
+    /** Component to show when not authenticated (landing page) */
+    landingComponent?: ReactNode;
+    /** What to do when unauthenticated */
+    onUnauthenticated?: 'landing' | 'redirect' | 'allow';
+    /** URL to redirect to when unauthenticated (if onUnauthenticated is 'redirect') */
+    redirectUrl?: string;
+}
+/**
+ * Props for WidgetsProvider
+ *
+ * Extends the schema type with React-specific fields.
+ */
+interface WidgetsProviderProps {
+    /** Children to render */
+    children: ReactNode;
+    /** Theme appearance mode */
+    appearance?: 'light' | 'dark' | 'inherit';
+    /** Border radius style */
+    radius?: 'none' | 'small' | 'medium' | 'large' | 'full';
+    /** Scaling factor */
+    scaling?: '90%' | '95%' | '100%' | '105%' | '110%';
+}
+/**
+ * Auth token type - can be a string or a function that returns a Promise<string>
+ *
+ * Note: This matches WorkOS's AuthToken type. For functions, the return type
+ * must be Promise<string>, not string | Promise<string>.
+ */
+type AuthToken = string | (() => Promise<string>);
+/**
+ * Common props for widget wrappers
+ */
+interface BaseWidgetProps {
+    /** Auth token for the widget (string or getter function) */
+    authToken: AuthToken;
+    /** CSS class name */
+    className?: string;
+}
+/**
+ * Props for widgets that support organization context
+ */
+interface OrganizationWidgetProps extends BaseWidgetProps {
+    /** Organization ID for org-scoped widgets */
+    organizationId?: string;
+}
+/**
+ * Props for useWidgetToken hook
+ */
+interface UseWidgetTokenOptions {
+    /** Widget type to fetch token for */
+    widget: string;
+    /** Organization ID for org-scoped widgets */
+    organizationId?: string;
+    /** Custom endpoint for fetching widget token (default: /api/workos/widget-token) */
+    endpoint?: string;
+}
+/**
+ * Result from useWidgetToken hook
+ */
+interface UseWidgetTokenResult {
+    /** The fetched token */
+    token: string | null;
+    /** Whether token is being fetched */
+    loading: boolean;
+    /** Error message if fetch failed */
+    error: string | null;
+    /** Function to manually refetch token */
+    refetch: () => Promise<void>;
+}
+
+export type { AuthGateProps as A, BaseWidgetProps as B, IdentityProviderProps as I, OrganizationWidgetProps as O, UseWidgetTokenOptions as U, WidgetsProviderProps as W, AuthToken as a, UseWidgetTokenResult as b };

package/dist/auth-organization-CN1WpGnL.d.ts

@@ -0,0 +1,126 @@
+import * as zod_v4_core from 'zod/v4/core';
+import * as zod from 'zod';
+import { z } from 'zod';
+
+/**
+ * AuthUserSchema - Extended user identity for WorkOS AuthKit
+ *
+ * Extends UserIdentitySchema with WorkOS-specific fields like
+ * verification status and timestamps.
+ *
+ * @example
+ * ```tsx
+ * import { AuthUserSchema } from '@mdxui/auth/schemas'
+ *
+ * const result = AuthUserSchema.safeParse(user)
+ * if (result.success) {
+ *   console.log(result.data.emailVerified)
+ * }
+ * ```
+ */
+declare const AuthUserSchema: zod.ZodObject<{
+    fullName: zod.ZodOptional<zod.ZodString>;
+    avatar: zod.ZodOptional<zod.ZodString>;
+    firstName: zod.ZodOptional<zod.ZodString>;
+    lastName: zod.ZodOptional<zod.ZodString>;
+    profilePictureUrl: zod.ZodOptional<zod.ZodString>;
+    roles: zod.ZodOptional<zod.ZodArray<zod.ZodString>>;
+    permissions: zod.ZodOptional<zod.ZodArray<zod.ZodString>>;
+    organizationId: zod.ZodOptional<zod.ZodString>;
+    organizationName: zod.ZodOptional<zod.ZodString>;
+    metadata: zod.ZodOptional<zod.ZodRecord<zod.ZodString, zod.ZodUnknown>>;
+    id: z.ZodString;
+    email: z.ZodString;
+    emailVerified: z.ZodBoolean;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    lastSignInAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, zod_v4_core.$strip>;
+/**
+ * AuthUser type inferred from schema
+ *
+ * This type is compatible with UserIdentity - an AuthUser can be
+ * assigned to a variable of type UserIdentity.
+ */
+type AuthUser = z.infer<typeof AuthUserSchema>;
+
+/**
+ * ImpersonatorSchema - Info about admin impersonating a user
+ */
+declare const ImpersonatorSchema: z.ZodObject<{
+    email: z.ZodString;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type Impersonator = z.infer<typeof ImpersonatorSchema>;
+/**
+ * AuthSessionSchema - Extended session for WorkOS AuthKit
+ *
+ * Extends SessionSchema with WorkOS-specific fields like
+ * impersonation support.
+ *
+ * @example
+ * ```tsx
+ * import { AuthSessionSchema } from '@mdxui/auth/schemas'
+ *
+ * const result = AuthSessionSchema.safeParse(session)
+ * if (result.success && result.data.impersonator) {
+ *   console.log('Being impersonated by:', result.data.impersonator.email)
+ * }
+ * ```
+ */
+declare const AuthSessionSchema: zod.ZodObject<{
+    id: zod.ZodString;
+    createdAt: zod.ZodString;
+    expiresAt: zod.ZodString;
+    ipAddress: zod.ZodOptional<zod.ZodString>;
+    userAgent: zod.ZodOptional<zod.ZodString>;
+    organizationId: zod.ZodOptional<zod.ZodString>;
+    accessToken: zod.ZodOptional<zod.ZodString>;
+    refreshToken: zod.ZodOptional<zod.ZodString>;
+    userId: z.ZodString;
+    impersonator: z.ZodOptional<z.ZodObject<{
+        email: z.ZodString;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, zod_v4_core.$strip>;
+/**
+ * AuthSession type inferred from schema
+ */
+type AuthSession = z.infer<typeof AuthSessionSchema>;
+
+/**
+ * AuthOrganization Schema
+ *
+ * Organization type for WorkOS AuthKit.
+ */
+
+/**
+ * AuthOrganizationSchema - WorkOS organization
+ *
+ * Represents an organization/workspace in WorkOS.
+ *
+ * @example
+ * ```tsx
+ * import { AuthOrganizationSchema } from '@mdxui/auth/schemas'
+ *
+ * const result = AuthOrganizationSchema.safeParse(org)
+ * if (result.success) {
+ *   console.log('Organization:', result.data.name)
+ * }
+ * ```
+ */
+declare const AuthOrganizationSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    slug: z.ZodOptional<z.ZodString>;
+    logoUrl: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    domains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * AuthOrganization type inferred from schema
+ */
+type AuthOrganization = z.infer<typeof AuthOrganizationSchema>;
+
+export { type AuthUser as A, type Impersonator as I, type AuthOrganization as a, type AuthSession as b, AuthUserSchema as c, AuthSessionSchema as d, AuthOrganizationSchema as e, ImpersonatorSchema as f };