# AuthProvider
Source: https://docs.ouim.me/logto-authkit/api/components/auth-provider

The main authentication provider component that wraps your application with Logto authentication.

## Overview

The `AuthProvider` component is the root authentication provider that wraps your application and provides authentication context to all child components. It integrates with Logto's authentication service and manages user session state.

## Props

<ParamField type="React.ReactNode">
  The child components to be wrapped by the authentication provider.
</ParamField>

<ParamField type="LogtoConfig">
  Logto configuration object containing your application credentials and settings.

  ```typescript theme={null}
  interface LogtoConfig {
    endpoint: string
    appId: string
    resources?: string[]
    scopes?: string[]
    prompt?: string
  }
  ```
</ParamField>

<ParamField type="string">
  The URL to redirect to after successful authentication. Defaults to the current page URL if not specified.
</ParamField>

<ParamField type="(url: string, options?: NavigationOptions) => void">
  Custom navigation function to handle routing in your application. Useful for integration with client-side routers like Next.js or React Router.

  ```typescript theme={null}
  interface NavigationOptions {
    replace?: boolean // Use replaceState instead of pushState
    force?: boolean   // Force navigation even if already on the same page
  }
  ```
</ParamField>

<ParamField type="boolean">
  Enable popup-based sign-in flow instead of full-page redirect. When enabled, the sign-in page opens in a popup window.
</ParamField>

## Usage

### Basic Setup

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'

function App() {
  const logtoConfig = {
    endpoint: 'https://your-logto-endpoint.com',
    appId: 'your-app-id',
  }

  return (
    <AuthProvider config={logtoConfig}>
      <YourApp />
    </AuthProvider>
  )
}
```

### With Callback URL

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'

function App() {
  const logtoConfig = {
    endpoint: 'https://your-logto-endpoint.com',
    appId: 'your-app-id',
  }

  return (
    <AuthProvider 
      config={logtoConfig}
      callbackUrl="/dashboard"
    >
      <YourApp />
    </AuthProvider>
  )
}
```

### With Popup Sign-In

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'

function App() {
  const logtoConfig = {
    endpoint: 'https://your-logto-endpoint.com',
    appId: 'your-app-id',
  }

  return (
    <AuthProvider 
      config={logtoConfig}
      enablePopupSignIn={true}
    >
      <YourApp />
    </AuthProvider>
  )
}
```

### With Custom Navigation (Next.js)

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'

function App({ children }) {
  const router = useRouter()
  
  const logtoConfig = {
    endpoint: 'https://your-logto-endpoint.com',
    appId: 'your-app-id',
  }

  const customNavigate = (url: string, options?: NavigationOptions) => {
    if (options?.replace) {
      router.replace(url)
    } else {
      router.push(url)
    }
  }

  return (
    <AuthProvider 
      config={logtoConfig}
      customNavigate={customNavigate}
    >
      {children}
    </AuthProvider>
  )
}
```

## Features

* **Client-Side Only**: Automatically prevents SSR issues by rendering only on the client side
* **Cross-Tab Synchronization**: Auth state is synchronized across browser tabs and windows
* **Auto Token Management**: Automatically manages JWT tokens in cookies
* **Error Handling**: Built-in error recovery and automatic logout on auth failures
* **Popup Support**: Optional popup-based authentication flow
* **Rate Limiting**: Prevents excessive auth state refresh calls

## Notes

* The `AuthProvider` must be placed at the root of your component tree, above any components that use authentication
* Configuration is validated on mount to ensure all required fields are present
* Auth state changes trigger a custom `auth-state-changed` event on the window object
* The provider automatically handles token refresh and session management


# CallbackPage
Source: https://docs.ouim.me/logto-authkit/api/components/callback-page

Handles the OAuth callback after authentication with Logto.

## Overview

The `CallbackPage` component handles the OAuth callback flow after a user completes authentication with Logto. It processes the authorization code, exchanges it for tokens, and redirects the user appropriately.

## Props

<ParamField type="string">
  Additional CSS classes to apply to the container element.
</ParamField>

<ParamField type="React.ReactNode">
  Custom component to display while the callback is being processed. If not provided, a default loading spinner with "Signing you in..." text is shown.
</ParamField>

<ParamField type="React.ReactNode">
  Custom component to display after successful authentication. If not provided, a default spinner with "Authentication complete! Redirecting..." text is shown.
</ParamField>

<ParamField type="() => void">
  Callback function that is called after successful authentication, before any redirect or window close actions.
</ParamField>

<ParamField type="(error: Error) => void">
  Callback function that is called if an error occurs during the authentication callback.
</ParamField>

## Usage

### Basic Setup

Create a callback route in your application (e.g., `/callback` or `/auth/callback`):

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

function Callback() {
  return <CallbackPage />
}

export default Callback
```

### With Custom Loading Component

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

function Callback() {
  return (
    <CallbackPage 
      loadingComponent={
        <div className="text-center">
          <h1>Please wait...</h1>
          <p>Authenticating your account</p>
        </div>
      }
    />
  )
}
```

### With Callbacks

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'

function Callback() {
  const router = useRouter()

  return (
    <CallbackPage 
      onSuccess={() => {
        console.log('Authentication successful!')
        // Optionally track analytics, etc.
      }}
      onError={(error) => {
        console.error('Authentication failed:', error)
        router.push('/login?error=auth_failed')
      }}
    />
  )
}
```

### Fully Customized

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

function Callback() {
  return (
    <CallbackPage 
      className="custom-callback-page"
      loadingComponent={
        <div className="flex flex-col items-center gap-4">
          <div className="loader" />
          <h2>Signing you in...</h2>
        </div>
      }
      successComponent={
        <div className="flex flex-col items-center gap-4">
          <svg className="checkmark" /* ... */ />
          <h2>Success! Redirecting...</h2>
        </div>
      }
      onSuccess={() => {
        // Track authentication success
        analytics.track('user_signed_in')
      }}
      onError={(error) => {
        // Track authentication error
        analytics.track('auth_error', { error: error.message })
      }}
    />
  )
}
```

## Behavior

### Standard Flow

1. User is redirected to this page after authenticating with Logto
2. The component exchanges the authorization code for tokens
3. `onSuccess` callback is called (if provided)
4. User is redirected to the home page (`/`)

### Popup Flow

When authentication happens in a popup window:

1. Component detects it's running in a popup (via `window.opener` or `sessionStorage`)
2. Exchanges authorization code for tokens
3. `onSuccess` callback is called (if provided)
4. Sends `SIGNIN_SUCCESS` message to parent window via `postMessage`
5. Falls back to `localStorage` if `postMessage` fails
6. Closes the popup window after a 100ms delay

### Error Handling

If an error occurs during the callback:

1. Error is logged to console
2. `onError` callback is called (if provided)
3. Loading state continues (manual error handling required)

## Notes

* The component must be used within an `AuthProvider` context
* The callback URL must be registered in your Logto application settings
* The component handles both full-page redirects and popup authentication flows automatically
* A `simple_logto_popup_flow` sessionStorage flag persists the popup state across redirects
* The component prevents duplicate callback execution using a ref
* Spin animation keyframes are injected into the document head automatically

## Related

* [SignInPage](/logto-authkit/api/components/sign-in-page) - Initiates the sign-in flow
* [AuthProvider](/logto-authkit/api/components/auth-provider) - Required context provider


# SignInPage
Source: https://docs.ouim.me/logto-authkit/api/components/sign-in-page

A page component that initiates the authentication flow with Logto.

## Overview

The `SignInPage` component is a page-level component that automatically initiates the Logto authentication flow when rendered. It handles both standard redirects and popup-based authentication.

## Props

This component does not accept any props. All configuration is managed through the `AuthProvider`.

## Usage

### Basic Setup

Create a sign-in route in your application (e.g., `/signin` or `/login`):

```tsx theme={null}
import { SignInPage } from '@ouim/logto-authkit'

function SignIn() {
  return <SignInPage />
}

export default SignIn
```

### Next.js App Router

```tsx theme={null}
// app/signin/page.tsx
import { SignInPage } from '@ouim/logto-authkit'

export default function SignIn() {
  return <SignInPage />
}
```

### Next.js Pages Router

```tsx theme={null}
// pages/signin.tsx
import { SignInPage } from '@ouim/logto-authkit'

function SignIn() {
  return <SignInPage />
}

export default SignIn
```

### React Router

```tsx theme={null}
import { Routes, Route } from 'react-router-dom'
import { SignInPage } from '@ouim/logto-authkit'

function App() {
  return (
    <Routes>
      <Route path="/signin" element={<SignInPage />} />
    </Routes>
  )
}
```

## Behavior

### Standard Flow

1. Component checks if user is already authenticated
2. If not authenticated, initiates Logto sign-in flow
3. User is redirected to Logto's authentication page
4. After authentication, user is redirected to the callback URL

### Popup Flow

When popup sign-in is enabled (`enablePopupSignIn={true}` in `AuthProvider`):

1. Component detects it's opened in a popup window (via URL param `?popup=true`)
2. Sets `simple_logto_popup_flow` flag in sessionStorage
3. Initiates sign-in with popup disabled to prevent nested popups
4. After authentication, notifies parent window and closes popup

### Already Authenticated

If user is already signed in:

**Standard window:**

* Redirects to home page (`/`) if not already there
* Reloads the page if already on home page

**Popup window:**

* Sends `SIGNIN_COMPLETE` message to parent window
* Falls back to localStorage if `postMessage` fails
* Closes the popup after 100ms delay

### Loading State

While checking authentication state:

* Displays a centered loading spinner
* Prevents any sign-in actions until state is determined

## Features

* **Auto-Redirect**: Automatically initiates sign-in without user interaction
* **Popup Detection**: Intelligently detects and handles popup authentication
* **State Persistence**: Uses sessionStorage to maintain popup state across redirects
* **Fallback Messaging**: Multiple communication methods between popup and parent window
* **Prevents Nested Popups**: Disables popup mode when already in a popup
* **Loading Feedback**: Built-in loading state while determining auth status

## Implementation Details

### Popup Detection

The component detects popup mode through:

1. **URL Parameter**: `?popup=true` query string
2. **SessionStorage**: `simple_logto_popup_flow` flag (persists across redirects)
3. **Window Opener**: Presence of `window.opener` reference

### Parent Window Communication

When in popup mode, the component communicates with the parent window via:

1. **Primary**: `window.opener.postMessage()` with same-origin check
2. **Fallback**: `localStorage.setItem('simple_logto_signin_complete')` for broadcast

### Sign-In Prevention

The component uses a ref (`signInInProgress`) to prevent multiple simultaneous sign-in attempts.

## Notes

* The component must be used within an `AuthProvider` context
* No visual UI is rendered after the loading state (redirects immediately)
* The `/signin` route is expected by the default popup implementation in `AuthProvider`
* If you use a different route, update popup calls accordingly
* The component automatically handles cleanup of sessionStorage flags

## Related

* [CallbackPage](/logto-authkit/api/components/callback-page) - Handles the callback after authentication
* [AuthProvider](/logto-authkit/api/components/auth-provider) - Configure authentication behavior
* [useAuth](/logto-authkit/api/hooks/use-auth) - Access authentication state programmatically


# useAuth
Source: https://docs.ouim.me/logto-authkit/api/hooks/use-auth

React hook for managing authentication state and access control

## Overview

The `useAuth` hook provides access to authentication state and handles automatic redirects based on authentication status and middleware configuration.

## Signature

```typescript theme={null}
function useAuth(options?: AuthOptions): AuthContextType
```

## Parameters

<ParamField type="AuthOptions">
  Configuration options for authentication behavior

  <Expandable title="AuthOptions properties">
    <ParamField type="'auth' | 'guest' | undefined">
      Defines the authentication requirement for the current page:

      * `'auth'`: Requires authentication (redirects unauthenticated users)
      * `'guest'`: Guest-only page (redirects authenticated users)
      * `undefined`: No automatic redirects
    </ParamField>

    <ParamField type="string">
      URL to redirect to when `middleware: 'auth'` and user is not authenticated
    </ParamField>

    <ParamField type="string">
      URL to redirect to when `middleware: 'guest'` and user is authenticated
    </ParamField>

    <ParamField type="NavigationOptions">
      Navigation behavior options

      <Expandable title="NavigationOptions properties">
        <ParamField type="boolean">
          Use `replaceState` instead of `pushState` for navigation
        </ParamField>

        <ParamField type="boolean">
          Force navigation even if already on the same page
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Returns

<ResponseField name="AuthContextType" type="object">
  Authentication context object containing user state and authentication methods

  <Expandable title="AuthContextType properties">
    <ResponseField name="user" type="LogtoUser | null">
      Current authenticated user object, or `null` if not authenticated

      <Expandable title="LogtoUser properties">
        <ResponseField name="id" type="string">
          Unique user identifier
        </ResponseField>

        <ResponseField name="name" type="string">
          User's display name
        </ResponseField>

        <ResponseField name="email" type="string">
          User's email address
        </ResponseField>

        <ResponseField name="avatar" type="string">
          URL to user's avatar image
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="isLoadingUser" type="boolean">
      Loading state indicator for user authentication status
    </ResponseField>

    <ResponseField name="signIn" type="(callbackUrl?: string, usePopup?: boolean) => Promise<void>">
      Function to initiate sign-in flow
    </ResponseField>

    <ResponseField name="signOut" type="(options?: { callbackUrl?: string; global?: boolean }) => Promise<void>">
      Function to sign out the current user
    </ResponseField>

    <ResponseField name="refreshAuth" type="() => Promise<void>">
      Function to refresh authentication state
    </ResponseField>

    <ResponseField name="enablePopupSignIn" type="boolean">
      Whether popup sign-in is enabled
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

### Basic Usage

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function Profile() {
  const { user, isLoadingUser } = useAuth()

  if (isLoadingUser) {
    return <div>Loading...</div>
  }

  if (!user) {
    return <div>Not authenticated</div>
  }

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <p>Email: {user.email}</p>
    </div>
  )
}
```

### Protected Route

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function Dashboard() {
  const { user, signOut } = useAuth({
    middleware: 'auth',
    redirectTo: '/login'
  })

  return (
    <div>
      <h1>Dashboard</h1>
      <p>Welcome, {user?.name}</p>
      <button onClick={() => signOut()}>Sign Out</button>
    </div>
  )
}
```

### Guest-Only Route

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function Login() {
  const { signIn } = useAuth({
    middleware: 'guest',
    redirectIfAuthenticated: '/dashboard'
  })

  return (
    <div>
      <h1>Login</h1>
      <button onClick={() => signIn()}>Sign In</button>
    </div>
  )
}
```

### Custom Navigation Options

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function ProtectedPage() {
  const { user } = useAuth({
    middleware: 'auth',
    redirectTo: '/login',
    navigationOptions: {
      replace: true, // Use replace instead of push
      force: false
    }
  })

  return <div>Protected content</div>
}
```

## Behavior

* The hook automatically handles redirects based on the `middleware` option and authentication state
* Redirects only occur after the loading state completes (`isLoadingUser` is `false`)
* When `middleware: 'auth'` is set and user is not authenticated, redirects to `redirectTo` (defaults to `/404`)
* When `middleware: 'guest'` is set and user is authenticated, redirects to `redirectIfAuthenticated`
* The hook memoizes options to prevent infinite re-renders when the options object reference changes

## See Also

* [AuthProvider](/logto-authkit/api/components/auth-provider) - Provider component required to use this hook
* [verifyAuth](/logto-authkit/api/server/verify-auth) - Server authentication verification


# createExpressAuthMiddleware
Source: https://docs.ouim.me/logto-authkit/api/server/create-express-auth-middleware

Express middleware factory for Logto authentication

## Overview

The `createExpressAuthMiddleware` function creates an Express middleware that automatically verifies Logto authentication tokens and attaches authentication context to the request object.

## Signature

```typescript theme={null}
function createExpressAuthMiddleware(
  options: VerifyAuthOptions
): (req: ExpressRequest, res: ExpressResponse, next: ExpressNext) => void
```

## Parameters

<ParamField type="VerifyAuthOptions">
  Configuration options for token verification

  <Expandable title="VerifyAuthOptions properties">
    <ParamField type="string">
      Your Logto server URL (e.g., `https://your-logto.app`)
    </ParamField>

    <ParamField type="string">
      Expected audience claim in the token (your application identifier)
    </ParamField>

    <ParamField type="string">
      Name of the cookie containing the auth token
    </ParamField>

    <ParamField type="string">
      Required OAuth scope that must be present in the token
    </ParamField>

    <ParamField type="boolean">
      Allow guest access when no valid token is found. Attaches guest context instead of returning 401
    </ParamField>
  </Expandable>
</ParamField>

## Returns

<ResponseField name="middleware" type="ExpressMiddleware">
  Express middleware function that can be used with `app.use()` or route handlers
</ResponseField>

## Request Enhancement

The middleware adds an `auth` property to the Express request object:

```typescript theme={null}
req.auth: AuthContext
```

<Expandable title="AuthContext properties">
  <ResponseField name="userId" type="string | null">
    User ID from the token's `sub` claim, or `null` for guest users
  </ResponseField>

  <ResponseField name="isAuthenticated" type="boolean">
    Whether the user is authenticated (`true`) or guest (`false`)
  </ResponseField>

  <ResponseField name="payload" type="AuthPayload | null">
    Decoded JWT payload, or `null` for guest users
  </ResponseField>

  <ResponseField name="isGuest" type="boolean">
    `true` if this is a guest context (only when `allowGuest: true`)
  </ResponseField>

  <ResponseField name="guestId" type="string">
    Unique identifier for guest users (auto-generated UUID)
  </ResponseField>
</Expandable>

## Examples

### Basic Setup

```typescript theme={null}
import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

// Apply to all routes
app.use(authMiddleware)

app.get('/profile', (req, res) => {
  res.json({
    userId: req.auth.userId,
    authenticated: req.auth.isAuthenticated
  })
})

app.listen(3000)
```

### Protected Routes Only

```typescript theme={null}
import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

// Public route (no auth required)
app.get('/public', (req, res) => {
  res.json({ message: 'Public endpoint' })
})

// Protected routes
app.get('/api/user', authMiddleware, (req, res) => {
  res.json({ userId: req.auth.userId })
})

app.post('/api/data', authMiddleware, (req, res) => {
  const userId = req.auth.userId
  // Handle authenticated request
  res.json({ success: true })
})
```

### With Guest Support

```typescript theme={null}
import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  allowGuest: true // Allow unauthenticated access
})

app.use(authMiddleware)

app.get('/api/content', (req, res) => {
  if (req.auth.isGuest) {
    res.json({
      message: 'Limited content for guests',
      guestId: req.auth.guestId
    })
  } else {
    res.json({
      message: 'Full content for authenticated users',
      userId: req.auth.userId
    })
  }
})
```

### With Required Scope

```typescript theme={null}
import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const adminAuthMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  requiredScope: 'admin:write'
})

// Admin-only endpoint
app.delete('/api/users/:id', adminAuthMiddleware, (req, res) => {
  // Only users with admin:write scope can access this
  res.json({ success: true })
})
```

### Custom Cookie Name

```typescript theme={null}
import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  cookieName: 'my_custom_auth_cookie'
})

app.use(authMiddleware)
```

### Error Handling

```typescript theme={null}
import express from 'express'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const app = express()

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

app.use(authMiddleware)

// Authentication errors return 401 automatically
// Add error handler for custom error responses
app.use((err, req, res, next) => {
  if (err.status === 401) {
    res.status(401).json({
      error: 'Unauthorized',
      message: 'Please sign in to access this resource'
    })
  } else {
    next(err)
  }
})
```

## Behavior

### Token Extraction

The middleware extracts tokens in this order:

1. Cookie (using `cookieName` option, defaults to `logto_authtoken`)
2. Authorization header (Bearer token)

### Authentication Responses

**When `allowGuest: false` (default):**

* No token found: Returns 401 with error message
* Invalid token: Returns 401 with error details
* Valid token: Attaches `AuthContext` to `req.auth` and calls `next()`

**When `allowGuest: true`:**

* No token found: Attaches guest `AuthContext` to `req.auth` and calls `next()`
* Invalid token: Attaches guest `AuthContext` to `req.auth` and calls `next()`
* Valid token: Attaches authenticated `AuthContext` to `req.auth` and calls `next()`

### Cookie Parsing

The middleware automatically handles cookie parsing:

* If cookies are not already parsed, it applies `cookie-parser` internally
* No need to manually add `cookie-parser` middleware when using this middleware

## TypeScript Support

Extend the Express request type to include the `auth` property:

```typescript theme={null}
import type { AuthContext } from '@ouim/logto-authkit/server'

declare global {
  namespace Express {
    interface Request {
      auth: AuthContext
    }
  }
}
```

## See Also

* [verifyAuth](/logto-authkit/api/server/verify-auth) - Generic verification function
* [verifyNextAuth](/logto-authkit/api/server/verify-next-auth) - Next.js authentication helper
* [useAuth](/logto-authkit/api/hooks/use-auth) - React hook for client-side authentication


# verifyAuth
Source: https://docs.ouim.me/logto-authkit/api/server/verify-auth

Universal function for verifying Logto authentication tokens in any Node.js environment

## Overview

The `verifyAuth` function is a generic authentication verification utility that works in any Node.js environment. It can accept either a raw JWT token string or a request object with cookies and headers.

## Signature

```typescript theme={null}
async function verifyAuth(
  tokenOrRequest: string | { cookies?: any; headers?: any },
  options: VerifyAuthOptions
): Promise<AuthContext>
```

## Parameters

<ParamField type="string | object">
  Either a JWT token string or a request object containing cookies and headers

  When passing an object:

  * `cookies`: Cookie object (e.g., from cookie-parser)
  * `headers`: Headers object or Headers API
</ParamField>

<ParamField type="VerifyAuthOptions">
  Configuration options for token verification

  <Expandable title="VerifyAuthOptions properties">
    <ParamField type="string">
      Your Logto server URL (e.g., `https://your-logto.app`)
    </ParamField>

    <ParamField type="string">
      Expected audience claim in the token (your application identifier)
    </ParamField>

    <ParamField type="string">
      Name of the cookie containing the auth token
    </ParamField>

    <ParamField type="string">
      Required OAuth scope that must be present in the token
    </ParamField>

    <ParamField type="boolean">
      Allow guest access when no valid token is found. Returns guest context instead of throwing error
    </ParamField>
  </Expandable>
</ParamField>

## Returns

<ResponseField name="AuthContext" type="Promise<AuthContext>">
  Promise that resolves to authentication context

  <Expandable title="AuthContext properties">
    <ResponseField name="userId" type="string | null">
      User ID from the token's `sub` claim, or `null` for guest users
    </ResponseField>

    <ResponseField name="isAuthenticated" type="boolean">
      Whether the user is authenticated (`true`) or guest (`false`)
    </ResponseField>

    <ResponseField name="payload" type="AuthPayload | null">
      Decoded JWT payload, or `null` for guest users

      <Expandable title="AuthPayload properties">
        <ResponseField name="sub" type="string">
          User ID (subject claim)
        </ResponseField>

        <ResponseField name="scope" type="string">
          OAuth scopes granted to the token
        </ResponseField>

        <ResponseField name="[key: string]" type="any">
          Additional claims in the JWT payload
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="isGuest" type="boolean">
      `true` if this is a guest context (only when `allowGuest: true`)
    </ResponseField>

    <ResponseField name="guestId" type="string">
      Unique identifier for guest users (auto-generated UUID)
    </ResponseField>
  </Expandable>
</ResponseField>

## Throws

* Throws an error if no token is found and `allowGuest` is `false`
* Throws an error if token verification fails and `allowGuest` is `false`
* When `allowGuest: true`, returns guest context instead of throwing

## Examples

### With JWT Token String

```typescript theme={null}
import { verifyAuth } from '@ouim/logto-authkit/server'

const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

try {
  const auth = await verifyAuth(token, {
    logtoUrl: 'https://your-logto.app',
    audience: 'https://api.yourapp.com'
  })

  console.log('User ID:', auth.userId)
  console.log('Authenticated:', auth.isAuthenticated)
} catch (error) {
  console.error('Authentication failed:', error)
}
```

### With Request Object (Generic)

```typescript theme={null}
import { verifyAuth } from '@ouim/logto-authkit/server'

const request = {
  cookies: { logto_authtoken: 'eyJhbGciOiJ...' },
  headers: { authorization: 'Bearer eyJhbGciOiJ...' }
}

const auth = await verifyAuth(request, {
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE
})

if (auth.isAuthenticated) {
  console.log('User:', auth.userId)
  console.log('Scopes:', auth.payload?.scope)
}
```

### With Guest Support

```typescript theme={null}
import { verifyAuth } from '@ouim/logto-authkit/server'

const auth = await verifyAuth(request, {
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  allowGuest: true // Won't throw if no token found
})

if (auth.isGuest) {
  console.log('Guest user:', auth.guestId)
} else {
  console.log('Authenticated user:', auth.userId)
}
```

### With Required Scope

```typescript theme={null}
import { verifyAuth } from '@ouim/logto-authkit/server'

try {
  const auth = await verifyAuth(token, {
    logtoUrl: process.env.LOGTO_URL,
    audience: process.env.LOGTO_AUDIENCE,
    requiredScope: 'admin:write' // Requires this scope
  })

  // Token has admin:write scope
  console.log('Admin user:', auth.userId)
} catch (error) {
  console.error('Missing required scope')
}
```

### Custom Cookie Name

```typescript theme={null}
import { verifyAuth } from '@ouim/logto-authkit/server'

const auth = await verifyAuth(request, {
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_AUDIENCE,
  cookieName: 'my_custom_auth_cookie'
})
```

## Token Extraction Order

When a request object is provided, tokens are extracted in this order:

1. Cookie (using `cookieName` option, defaults to `logto_authtoken`)
2. Authorization header (Bearer token)

The first valid token found is used for verification.

## Verification Process

The function performs the following verification steps:

1. Fetches JWKS (JSON Web Key Set) from your Logto server
2. Decodes JWT header to identify the signing key
3. Verifies JWT signature using the public key
4. Validates token claims:
   * Issuer (`iss`) matches Logto URL
   * Audience (`aud`) matches provided audience
   * Token is not expired (`exp`)
   * Token is valid (`nbf` - not before)
   * Required scope is present (if specified)

## Caching

JWKS (signing keys) are cached for 5 minutes to reduce requests to the Logto server and improve performance.

## See Also

* [createExpressAuthMiddleware](/logto-authkit/api/server/create-express-auth-middleware) - Express.js middleware
* [verifyNextAuth](/logto-authkit/api/server/verify-next-auth) - Next.js authentication helper
* [useAuth](/logto-authkit/api/hooks/use-auth) - React hook for client-side authentication


# verifyNextAuth
Source: https://docs.ouim.me/logto-authkit/api/server/verify-next-auth

Next.js authentication verification helper for App Router middleware and API routes

## Overview

The `verifyNextAuth` function is designed specifically for Next.js App Router, providing authentication verification for middleware and API routes with Next.js-specific request handling.

## Signature

```typescript theme={null}
async function verifyNextAuth(
  request: NextRequest,
  options: VerifyAuthOptions
): Promise<
  | { success: true; auth: AuthContext }
  | { success: false; error: string; auth?: AuthContext }
>
```

## Parameters

<ParamField type="NextRequest">
  Next.js request object from middleware or API routes
</ParamField>

<ParamField type="VerifyAuthOptions">
  Configuration options for token verification

  <Expandable title="VerifyAuthOptions properties">
    <ParamField type="string">
      Your Logto server URL (e.g., `https://your-logto.app`)
    </ParamField>

    <ParamField type="string">
      Expected audience claim in the token (your application identifier)
    </ParamField>

    <ParamField type="string">
      Name of the cookie containing the auth token
    </ParamField>

    <ParamField type="string">
      Required OAuth scope that must be present in the token
    </ParamField>

    <ParamField type="boolean">
      Allow guest access when no valid token is found. Returns guest context in response
    </ParamField>
  </Expandable>
</ParamField>

## Returns

<ResponseField name="result" type="Promise<VerifyAuthResult>">
  Promise that resolves to a result object indicating success or failure

  **Success Response:**

  <Expandable title="Success object">
    <ResponseField name="success" type="true">
      Indicates successful authentication
    </ResponseField>

    <ResponseField name="auth" type="AuthContext">
      Authentication context with user information
    </ResponseField>
  </Expandable>

  **Failure Response:**

  <Expandable title="Failure object">
    <ResponseField name="success" type="false">
      Indicates authentication failed
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message describing why authentication failed
    </ResponseField>

    <ResponseField name="auth" type="AuthContext">
      Guest authentication context (only present when `allowGuest: true`)
    </ResponseField>
  </Expandable>
</ResponseField>

### AuthContext Properties

<Expandable title="AuthContext properties">
  <ResponseField name="userId" type="string | null">
    User ID from the token's `sub` claim, or `null` for guest users
  </ResponseField>

  <ResponseField name="isAuthenticated" type="boolean">
    Whether the user is authenticated (`true`) or guest (`false`)
  </ResponseField>

  <ResponseField name="payload" type="AuthPayload | null">
    Decoded JWT payload, or `null` for guest users

    <Expandable title="AuthPayload properties">
      <ResponseField name="sub" type="string">
        User ID (subject claim)
      </ResponseField>

      <ResponseField name="scope" type="string">
        OAuth scopes granted to the token
      </ResponseField>

      <ResponseField name="[key: string]" type="any">
        Additional claims in the JWT payload
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="isGuest" type="boolean">
    `true` if this is a guest context (only when `allowGuest: true`)
  </ResponseField>

  <ResponseField name="guestId" type="string">
    Unique identifier for guest users (auto-generated UUID)
  </ResponseField>
</Expandable>

## Examples

### Middleware Protection

```typescript theme={null}
import { NextRequest, NextResponse } from 'next/server'
import { verifyNextAuth } from '@ouim/logto-authkit/server'

export async function middleware(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_AUDIENCE!
  })

  if (!result.success) {
    return NextResponse.redirect(new URL('/login', request.url))
  }

  // User is authenticated, continue
  return NextResponse.next()
}

export const config = {
  matcher: ['/dashboard/:path*', '/api/protected/:path*']
}
```

### API Route Protection

```typescript theme={null}
import { NextRequest, NextResponse } from 'next/server'
import { verifyNextAuth } from '@ouim/logto-authkit/server'

export async function GET(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_AUDIENCE!
  })

  if (!result.success) {
    return NextResponse.json(
      { error: result.error },
      { status: 401 }
    )
  }

  // Access authenticated user
  const userId = result.auth.userId

  return NextResponse.json({
    message: 'Success',
    userId
  })
}
```

### With Guest Support

```typescript theme={null}
import { NextRequest, NextResponse } from 'next/server'
import { verifyNextAuth } from '@ouim/logto-authkit/server'

export async function GET(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_AUDIENCE!,
    allowGuest: true
  })

  if (!result.success) {
    // Guest user
    return NextResponse.json({
      message: 'Limited content for guests',
      guestId: result.auth?.guestId
    })
  }

  // Authenticated user
  return NextResponse.json({
    message: 'Full content',
    userId: result.auth.userId
  })
}
```

### Middleware with Guest Support

```typescript theme={null}
import { NextRequest, NextResponse } from 'next/server'
import { verifyNextAuth } from '@ouim/logto-authkit/server'

export async function middleware(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_AUDIENCE!,
    allowGuest: true
  })

  // Add auth context to request headers for use in app
  const requestHeaders = new Headers(request.headers)
  
  if (result.success) {
    requestHeaders.set('x-user-id', result.auth.userId || '')
    requestHeaders.set('x-is-authenticated', 'true')
  } else if (result.auth?.isGuest) {
    requestHeaders.set('x-guest-id', result.auth.guestId || '')
    requestHeaders.set('x-is-authenticated', 'false')
  }

  return NextResponse.next({
    request: {
      headers: requestHeaders
    }
  })
}
```

### Role-Based Access Control

```typescript theme={null}
import { NextRequest, NextResponse } from 'next/server'
import { verifyNextAuth } from '@ouim/logto-authkit/server'

export async function middleware(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_AUDIENCE!,
    requiredScope: 'admin:write'
  })

  if (!result.success) {
    return NextResponse.json(
      { error: 'Admin access required' },
      { status: 403 }
    )
  }

  return NextResponse.next()
}

export const config = {
  matcher: '/admin/:path*'
}
```

### Custom Error Handling

```typescript theme={null}
import { NextRequest, NextResponse } from 'next/server'
import { verifyNextAuth } from '@ouim/logto-authkit/server'

export async function GET(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_AUDIENCE!
  })

  if (!result.success) {
    // Detailed error handling
    const statusCode = result.error.includes('expired') ? 401 : 403
    
    return NextResponse.json(
      {
        error: 'Authentication failed',
        details: result.error,
        timestamp: new Date().toISOString()
      },
      { status: statusCode }
    )
  }

  return NextResponse.json({
    userId: result.auth.userId,
    scopes: result.auth.payload?.scope
  })
}
```

### Extracting User Info in Server Component

```typescript theme={null}
// app/dashboard/page.tsx
import { cookies, headers } from 'next/headers'
import { verifyAuth } from '@ouim/logto-authkit/server'

export default async function DashboardPage() {
  const cookieStore = cookies()
  const headersList = headers()

  const auth = await verifyAuth(
    {
      cookies: Object.fromEntries(cookieStore.getAll().map(c => [c.name, c.value])),
      headers: Object.fromEntries(headersList.entries())
    },
    {
      logtoUrl: process.env.LOGTO_URL!,
      audience: process.env.LOGTO_AUDIENCE!
    }
  )

  return (
    <div>
      <h1>Dashboard</h1>
      <p>User ID: {auth.userId}</p>
    </div>
  )
}
```

## Token Extraction Order

The function extracts tokens in this order:

1. Cookie (using `cookieName` option, defaults to `logto_authtoken`)
2. Authorization header (Bearer token)

## Response Patterns

### Authenticated User

```typescript theme={null}
{
  success: true,
  auth: {
    userId: 'user-123',
    isAuthenticated: true,
    payload: { sub: 'user-123', scope: 'profile email' },
    isGuest: false
  }
}
```

### Guest User (when `allowGuest: true`)

```typescript theme={null}
{
  success: false,
  error: 'No authentication token found',
  auth: {
    userId: null,
    isAuthenticated: false,
    payload: null,
    isGuest: true,
    guestId: 'a1b2c3d4-e5f6-4g7h-8i9j-0k1l2m3n4o5p'
  }
}
```

### Failed Authentication (when `allowGuest: false`)

```typescript theme={null}
{
  success: false,
  error: 'No token found in cookies or Authorization header'
}
```

## See Also

* [verifyAuth](/logto-authkit/api/server/verify-auth) - Generic verification function
* [createExpressAuthMiddleware](/logto-authkit/api/server/create-express-auth-middleware) - Express.js middleware
* [useAuth](/logto-authkit/api/hooks/use-auth) - React hook for client-side authentication


# Frontend Types
Source: https://docs.ouim.me/logto-authkit/api/types/frontend-types

TypeScript type definitions for logto-authkit frontend SDK

Frontend TypeScript types used in logto-authkit React components and hooks.

## User Types

### LogtoUser

Represents an authenticated user in the application.

<ResponseField name="id" type="string">
  Unique identifier for the user
</ResponseField>

<ResponseField name="name" type="string">
  Display name of the user
</ResponseField>

<ResponseField name="email" type="string">
  Email address of the user
</ResponseField>

<ResponseField name="avatar" type="string">
  URL to the user's avatar/profile picture
</ResponseField>

<ResponseField name="[key: string]" type="any">
  Additional custom properties from the identity provider
</ResponseField>

```typescript theme={null}
export type LogtoUser = {
  id: string
  name?: string
  email?: string
  avatar?: string
  [key: string]: any
}
```

## Authentication Types

### AuthMiddleware

Defines the authentication requirement level for a page or route.

```typescript theme={null}
export type AuthMiddleware = 'auth' | 'guest' | undefined
```

* `'auth'` - Requires authenticated user
* `'guest'` - Allows unauthenticated access (guest mode)
* `undefined` - No middleware applied

### NavigationOptions

Options for controlling navigation behavior.

<ResponseField name="replace" type="boolean">
  Use `replaceState` instead of `pushState` to avoid adding to browser history
</ResponseField>

<ResponseField name="force" type="boolean">
  Force navigation even if already on the same page
</ResponseField>

```typescript theme={null}
export interface NavigationOptions {
  replace?: boolean
  force?: boolean
}
```

### AuthOptions

Configuration options for authentication behavior and redirects.

<ResponseField name="middleware" type="AuthMiddleware">
  Authentication middleware type to apply
</ResponseField>

<ResponseField name="redirectTo" type="string">
  URL to redirect to after authentication
</ResponseField>

<ResponseField name="redirectIfAuthenticated" type="string">
  URL to redirect to if user is already authenticated
</ResponseField>

<ResponseField name="navigationOptions" type="NavigationOptions">
  Options for controlling navigation behavior
</ResponseField>

```typescript theme={null}
export interface AuthOptions {
  middleware?: AuthMiddleware
  redirectTo?: string
  redirectIfAuthenticated?: string
  navigationOptions?: NavigationOptions
}
```

## Context Types

### AuthContextType

The authentication context type provided by `useAuth()` hook.

<ResponseField name="user" type="LogtoUser | null">
  The currently authenticated user, or `null` if not authenticated
</ResponseField>

<ResponseField name="isLoadingUser" type="boolean">
  Indicates if user data is currently being loaded
</ResponseField>

<ResponseField name="signIn" type="(callbackUrl?: string, usePopup?: boolean) => Promise<void>">
  Function to initiate sign-in flow

  * `callbackUrl` - URL to redirect to after successful sign-in
  * `usePopup` - Whether to use popup sign-in instead of redirect
</ResponseField>

<ResponseField name="signOut" type="(options?: { callbackUrl?: string; global?: boolean }) => Promise<void>">
  Function to sign out the current user

  * `callbackUrl` - URL to redirect to after sign-out
  * `global` - Whether to perform global sign-out across all sessions
</ResponseField>

<ResponseField name="refreshAuth" type="() => Promise<void>">
  Function to refresh authentication state and user data
</ResponseField>

<ResponseField name="enablePopupSignIn" type="boolean">
  Whether popup sign-in is enabled
</ResponseField>

```typescript theme={null}
export interface AuthContextType {
  user: LogtoUser | null
  isLoadingUser: boolean
  signIn: (callbackUrl?: string, usePopup?: boolean) => Promise<void>
  signOut: (options?: { callbackUrl?: string; global?: boolean }) => Promise<void>
  refreshAuth: () => Promise<void>
  enablePopupSignIn?: boolean
}
```

## Component Props

### AuthProviderProps

Props for the `AuthProvider` component.

<ResponseField name="children" type="React.ReactNode">
  Child components to render within the auth context
</ResponseField>

<ResponseField name="config" type="LogtoConfig">
  Logto configuration object containing `endpoint`, `appId`, and `resources`
</ResponseField>

<ResponseField name="callbackUrl" type="string">
  Default callback URL for authentication redirects
</ResponseField>

<ResponseField name="customNavigate" type="(url: string, options?: NavigationOptions) => void">
  Custom navigation function (e.g., for React Router integration)
</ResponseField>

<ResponseField name="enablePopupSignIn" type="boolean">
  Enable popup-based sign-in flow
</ResponseField>

```typescript theme={null}
export interface AuthProviderProps {
  children: React.ReactNode
  config: LogtoConfig
  callbackUrl?: string
  customNavigate?: (url: string, options?: NavigationOptions) => void
  enablePopupSignIn?: boolean
}
```

### CallbackPageProps

Props for the `CallbackPage` component.

<ResponseField name="className" type="string">
  CSS class name for styling the callback page
</ResponseField>

<ResponseField name="loadingComponent" type="React.ReactNode">
  Custom component to display during authentication callback processing
</ResponseField>

<ResponseField name="successComponent" type="React.ReactNode">
  Custom component to display on successful authentication
</ResponseField>

<ResponseField name="onSuccess" type="() => void">
  Callback function executed on successful authentication
</ResponseField>

<ResponseField name="onError" type="(error: Error) => void">
  Callback function executed on authentication error
</ResponseField>

```typescript theme={null}
export interface CallbackPageProps {
  className?: string
  loadingComponent?: React.ReactNode
  successComponent?: React.ReactNode
  onSuccess?: () => void
  onError?: (error: Error) => void
}
```

### AdditionalPage

Defines additional pages/links for UI components.

<ResponseField name="link" type="string">
  URL or path for the page
</ResponseField>

<ResponseField name="text" type="string">
  Display text for the link
</ResponseField>

<ResponseField name="icon" type="React.ReactNode">
  Optional icon element to display with the link
</ResponseField>

```typescript theme={null}
export interface AdditionalPage {
  link: string
  text: string
  icon?: React.ReactNode
}
```

## Usage Example

```typescript theme={null}
import type { LogtoUser, AuthOptions, AuthContextType } from '@ouim/logto-authkit'
import { useAuth } from '@ouim/logto-authkit'

function UserProfile() {
  const { user, signOut }: AuthContextType = useAuth()
  
  if (!user) return null
  
  const logtoUser: LogtoUser = user
  
  return (
    <div>
      <h1>{logtoUser.name}</h1>
      <p>{logtoUser.email}</p>
      <button onClick={() => signOut({ callbackUrl: '/' })}>
        Sign Out
      </button>
    </div>
  )
}
```


# Server Types
Source: https://docs.ouim.me/logto-authkit/api/types/server-types

TypeScript type definitions for logto-authkit server SDK

Server TypeScript types used in logto-authkit server-side authentication and middleware.

## Authentication Types

### AuthPayload

JWT payload structure returned after token verification.

<ResponseField name="sub" type="string">
  Subject - the user ID from Logto
</ResponseField>

<ResponseField name="scope" type="string">
  OAuth scopes granted to the token
</ResponseField>

<ResponseField name="[key: string]" type="any">
  Additional claims from the JWT token
</ResponseField>

```typescript theme={null}
export interface AuthPayload {
  sub: string // user ID
  scope: string
  [key: string]: any
}
```

### AuthContext

Authentication context attached to requests after verification.

<ResponseField name="userId" type="string | null">
  The authenticated user ID, or `null` if not authenticated
</ResponseField>

<ResponseField name="isAuthenticated" type="boolean">
  Whether the request has a valid authentication token
</ResponseField>

<ResponseField name="payload" type="AuthPayload | null">
  The full JWT payload if authenticated, otherwise `null`
</ResponseField>

<ResponseField name="isGuest" type="boolean">
  Whether the request is from a guest user (when `allowGuest` is enabled)
</ResponseField>

<ResponseField name="guestId" type="string">
  The guest user ID (when in guest mode)
</ResponseField>

```typescript theme={null}
export interface AuthContext {
  userId: string | null
  isAuthenticated: boolean
  payload: AuthPayload | null
  isGuest?: boolean
  guestId?: string
}
```

### VerifyAuthOptions

Configuration options for token verification.

<ResponseField name="logtoUrl" type="string">
  The Logto tenant URL (e.g., `https://your-tenant.logto.app`)
</ResponseField>

<ResponseField name="audience" type="string">
  The API resource identifier configured in Logto
</ResponseField>

<ResponseField name="cookieName" type="string">
  Name of the cookie containing the JWT token
</ResponseField>

<ResponseField name="requiredScope" type="string">
  Required OAuth scope for authorization (e.g., `"read:users"`)
</ResponseField>

<ResponseField name="allowGuest" type="boolean">
  Allow unauthenticated guest users with guest IDs
</ResponseField>

```typescript theme={null}
export interface VerifyAuthOptions {
  logtoUrl: string
  audience: string
  cookieName?: string
  requiredScope?: string
  allowGuest?: boolean
}
```

## Express Types

### ExpressRequest

Extended Express request interface with authentication context.

<ResponseField name="cookies" type="{ [key: string]: string }">
  Parsed cookies from the request
</ResponseField>

<ResponseField name="headers" type="{ [key: string]: string | string[] | undefined }">
  HTTP headers from the request
</ResponseField>

<ResponseField name="auth" type="AuthContext">
  Authentication context added by the middleware
</ResponseField>

```typescript theme={null}
export interface ExpressRequest {
  cookies?: { [key: string]: string }
  headers: { [key: string]: string | string[] | undefined }
  auth?: AuthContext
}
```

### ExpressResponse

Express response interface for middleware.

<ResponseField name="status" type="(code: number) => ExpressResponse">
  Set HTTP status code
</ResponseField>

<ResponseField name="json" type="(obj: any) => ExpressResponse">
  Send JSON response
</ResponseField>

```typescript theme={null}
export interface ExpressResponse {
  status: (code: number) => ExpressResponse
  json: (obj: any) => ExpressResponse
}
```

### ExpressNext

Express next function type.

```typescript theme={null}
export type ExpressNext = (err?: any) => void
```

## Next.js Types

### NextRequest

Next.js request interface for route handlers and middleware.

<ResponseField name="cookies" type="{ get: (name: string) => { value: string } | undefined }">
  Cookie accessor for Next.js requests
</ResponseField>

<ResponseField name="headers" type="{ get: (name: string) => string | null }">
  Header accessor for Next.js requests
</ResponseField>

```typescript theme={null}
export interface NextRequest {
  cookies: {
    get: (name: string) => { value: string } | undefined
  }
  headers: {
    get: (name: string) => string | null
  }
}
```

### NextResponse

Next.js response interface for route handlers.

<ResponseField name="json" type="(body: any, init?: { status?: number }) => NextResponse">
  Send JSON response with optional status code
</ResponseField>

```typescript theme={null}
export interface NextResponse {
  json: (body: any, init?: { status?: number }) => NextResponse
}
```

## Usage Examples

### Express Middleware

```typescript theme={null}
import type { ExpressRequest, ExpressResponse } from '@ouim/logto-authkit/server'
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: 'https://your-tenant.logto.app',
  audience: 'https://api.example.com',
  requiredScope: 'read:users'
})

app.get('/api/protected', authMiddleware, (req: ExpressRequest, res: ExpressResponse) => {
  const userId = req.auth?.userId
  res.json({ userId, message: 'Protected data' })
})
```

### Next.js Route Handler

```typescript theme={null}
import type { NextRequest } from '@ouim/logto-authkit/server'
import { verifyNextAuth } from '@ouim/logto-authkit/server'
import { NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_AUDIENCE!,
  })
  
  if (!result.success || !result.auth.isAuthenticated) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }
  
  return NextResponse.json({ userId: result.auth.userId })
}
```

### Guest Mode

```typescript theme={null}
import { verifyAuth } from '@ouim/logto-authkit/server'

const guestMiddleware = createExpressAuthMiddleware({
  logtoUrl: 'https://your-tenant.logto.app',
  audience: 'https://api.example.com',
  allowGuest: true
})

app.get('/api/content', guestMiddleware, (req, res) => {
  if (req.auth?.isGuest) {
    // Handle guest user
    console.log('Guest ID:', req.auth.guestId)
  } else {
    // Handle authenticated user
    console.log('User ID:', req.auth?.userId)
  }
  
  res.json({ message: 'Content accessible to all' })
})
```


# Bundler Configuration
Source: https://docs.ouim.me/logto-authkit/api/utilities/bundler-config

Configuration utilities for resolving jose library issues in different bundlers

Utilities to help configure your bundler (Vite, Webpack, or Next.js) to properly resolve the `jose` library dependency.

## Overview

logto-authkit uses the `jose` library for JWT operations. Some bundlers require special configuration to properly resolve this dependency. These utilities provide the necessary configuration for different build tools.

## Functions

### getBundlerConfig

Returns bundler-specific configuration for resolving the `jose` library.

```typescript theme={null}
getBundlerConfig(bundler?: 'vite' | 'webpack' | 'nextjs'): BundlerConfig
```

<ResponseField name="bundler" type="'vite' | 'webpack' | 'nextjs'">
  The bundler type to generate configuration for
</ResponseField>

**Returns:** `BundlerConfig` - Configuration object specific to the bundler

## Pre-configured Exports

### viteConfig

Pre-configured settings for Vite projects.

```typescript theme={null}
export const viteConfig: BundlerConfig
```

### webpackConfig

Pre-configured settings for Webpack projects.

```typescript theme={null}
export const webpackConfig: BundlerConfig
```

### nextjsConfig

Pre-configured settings for Next.js projects.

```typescript theme={null}
export const nextjsConfig: BundlerConfig
```

## Type Definitions

### BundlerConfig

```typescript theme={null}
interface BundlerConfig {
  optimizeDeps?: {
    include: string[]
  }
  resolve?: {
    alias: Record<string, string>
  }
  alias?: Record<string, string>
}
```

<ResponseField name="optimizeDeps" type="{ include: string[] }">
  Vite-specific dependency optimization settings
</ResponseField>

<ResponseField name="resolve" type="{ alias: Record<string, string> }">
  Module resolution aliases
</ResponseField>

<ResponseField name="alias" type="Record<string, string>">
  Alternative alias format for some bundlers
</ResponseField>

## Usage Examples

### Vite

Add to your `vite.config.ts`:

```typescript theme={null}
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { viteConfig } from '@ouim/logto-authkit/bundler-config'

export default defineConfig({
  plugins: [react()],
  ...viteConfig,
})
```

Or use the function:

```typescript theme={null}
import { getBundlerConfig } from '@ouim/logto-authkit/bundler-config'

const bundlerConfig = getBundlerConfig('vite')

export default defineConfig({
  plugins: [react()],
  optimizeDeps: bundlerConfig.optimizeDeps,
  resolve: bundlerConfig.resolve,
})
```

### Webpack

Add to your `webpack.config.js`:

```javascript theme={null}
const { webpackConfig } = require('@ouim/logto-authkit/bundler-config')

module.exports = {
  // ... other webpack config
  resolve: webpackConfig.resolve,
}
```

### Next.js

Add to your `next.config.js`:

```javascript theme={null}
const { nextjsConfig } = require('@ouim/logto-authkit/bundler-config')

module.exports = {
  // ... other Next.js config
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      ...nextjsConfig.resolve.alias,
    }
    return config
  },
}
```

Or in TypeScript (`next.config.ts`):

```typescript theme={null}
import type { NextConfig } from 'next'
import { nextjsConfig } from '@ouim/logto-authkit/bundler-config'

const config: NextConfig = {
  webpack: (config) => {
    config.resolve.alias = {
      ...config.resolve.alias,
      ...nextjsConfig.resolve?.alias,
    }
    return config
  },
}

export default config
```

### Custom Bundler

For other bundlers, use the `getBundlerConfig` function:

```typescript theme={null}
import { getBundlerConfig } from '@ouim/logto-authkit/bundler-config'

// Get the base jose alias
const config = getBundlerConfig() // Returns { alias: { jose: 'jose/dist/node/cjs' } }

// Apply to your custom bundler configuration
customBundler.setAlias(config.alias)
```

## What Does This Fix?

The `jose` library has different builds for different environments. These configurations ensure that:

1. The correct CommonJS build is used (`jose/dist/node/cjs`)
2. Dependencies are properly optimized for Vite
3. Module resolution works correctly across different bundlers

Without this configuration, you may encounter errors like:

* `Cannot find module 'jose'`
* `Error: Package subpath './jwt/verify' is not defined`
* Module resolution failures during build

## Configuration Details

### Vite Configuration

```typescript theme={null}
{
  optimizeDeps: {
    include: ['@logto/react', '@ouim/better-logto-react'],
  },
  resolve: {
    alias: {
      jose: 'jose/dist/node/cjs',
    },
  },
}
```

### Webpack/Next.js Configuration

```typescript theme={null}
{
  resolve: {
    alias: {
      jose: 'jose/dist/node/cjs',
    },
  },
}
```


# Cookie Utilities
Source: https://docs.ouim.me/logto-authkit/api/utilities/cookie-utils

Client-side cookie management utilities for authentication

Utilities for managing cookies and JWT tokens in logto-authkit applications.

## Cookie Utilities

General-purpose cookie management functions.

### cookieUtils.setCookie

Set a cookie with the given name, value, and options.

```typescript theme={null}
cookieUtils.setCookie(
  name: string,
  value: string,
  options?: CookieOptions
): void
```

<ResponseField name="name" type="string">
  The cookie name
</ResponseField>

<ResponseField name="value" type="string">
  The cookie value
</ResponseField>

<ResponseField name="options" type="CookieOptions">
  Cookie configuration options
</ResponseField>

#### CookieOptions

<ResponseField name="expires" type="Date | number">
  Expiration date (Date object) or number of days until expiration
</ResponseField>

<ResponseField name="maxAge" type="number">
  Maximum age in seconds
</ResponseField>

<ResponseField name="domain" type="string">
  Cookie domain
</ResponseField>

<ResponseField name="path" type="string">
  Cookie path
</ResponseField>

<ResponseField name="secure" type="boolean">
  Whether cookie requires HTTPS
</ResponseField>

<ResponseField name="sameSite" type="'strict' | 'lax' | 'none'">
  SameSite cookie attribute
</ResponseField>

<ResponseField name="httpOnly" type="boolean">
  Whether cookie is HTTP-only (not accessible via JavaScript)
</ResponseField>

**Example:**

```typescript theme={null}
import { cookieUtils } from '@ouim/logto-authkit'

// Set a cookie that expires in 7 days
cookieUtils.setCookie('user_preference', 'dark-mode', {
  expires: 7,
  secure: true,
  sameSite: 'strict'
})

// Set a cookie with a specific expiration date
cookieUtils.setCookie('session', 'abc123', {
  expires: new Date('2026-12-31'),
  path: '/'
})
```

### cookieUtils.getCookie

Get a cookie value by name.

```typescript theme={null}
cookieUtils.getCookie(name: string): string | null
```

<ResponseField name="name" type="string">
  The cookie name to retrieve
</ResponseField>

**Returns:** `string | null` - The cookie value, or `null` if not found

**Example:**

```typescript theme={null}
import { cookieUtils } from '@ouim/logto-authkit'

const preference = cookieUtils.getCookie('user_preference')
if (preference === 'dark-mode') {
  // Enable dark mode
}
```

### cookieUtils.removeCookie

Remove a cookie by name.

```typescript theme={null}
cookieUtils.removeCookie(
  name: string,
  options?: RemoveCookieOptions
): void
```

<ResponseField name="name" type="string">
  The cookie name to remove
</ResponseField>

<ResponseField name="options" type="RemoveCookieOptions">
  Cookie removal options (domain and path must match the original cookie)
</ResponseField>

#### RemoveCookieOptions

<ResponseField name="domain" type="string">
  Cookie domain (must match original)
</ResponseField>

<ResponseField name="path" type="string">
  Cookie path (must match original)
</ResponseField>

**Example:**

```typescript theme={null}
import { cookieUtils } from '@ouim/logto-authkit'

cookieUtils.removeCookie('user_preference', { path: '/' })
```

## JWT Token Utilities

Specialized utilities for managing JWT authentication tokens.

### jwtCookieUtils.saveToken

Save a JWT token to a secure cookie.

```typescript theme={null}
jwtCookieUtils.saveToken(token: string): void
```

<ResponseField name="token" type="string">
  The JWT token to save
</ResponseField>

**Cookie details:**

* Name: `logto_authtoken`
* Expires: 7 days
* Secure: true (HTTPS only)
* SameSite: strict
* Path: /

**Example:**

```typescript theme={null}
import { jwtCookieUtils } from '@ouim/logto-authkit'

// After successful authentication
const token = await getAccessToken()
jwtCookieUtils.saveToken(token)
```

### jwtCookieUtils.getToken

Retrieve the JWT token from the cookie.

```typescript theme={null}
jwtCookieUtils.getToken(): string | null
```

**Returns:** `string | null` - The JWT token, or `null` if not found

**Example:**

```typescript theme={null}
import { jwtCookieUtils } from '@ouim/logto-authkit'

const token = jwtCookieUtils.getToken()
if (token) {
  // Make authenticated API request
  fetch('/api/user', {
    headers: {
      Authorization: `Bearer ${token}`
    }
  })
}
```

### jwtCookieUtils.removeToken

Remove the JWT token cookie.

```typescript theme={null}
jwtCookieUtils.removeToken(): void
```

**Example:**

```typescript theme={null}
import { jwtCookieUtils } from '@ouim/logto-authkit'

// On sign out
function handleSignOut() {
  jwtCookieUtils.removeToken()
  // Redirect to login page
}
```

## Configuration Validation

### validateLogtoConfig

Validate Logto configuration for required fields.

```typescript theme={null}
validateLogtoConfig(config: LogtoConfig): void
```

<ResponseField name="config" type="LogtoConfig">
  The Logto configuration object to validate
</ResponseField>

**Throws:** `Error` if configuration is invalid or missing required fields

**Example:**

```typescript theme={null}
import { validateLogtoConfig } from '@ouim/logto-authkit'
import type { LogtoConfig } from '@logto/react'

const config: LogtoConfig = {
  endpoint: 'https://your-tenant.logto.app',
  appId: 'your-app-id',
  resources: ['https://api.example.com']
}

try {
  validateLogtoConfig(config)
  console.log('Config is valid')
} catch (error) {
  console.error('Invalid config:', error.message)
}
```

<Note>
  The library uses internal utilities for transforming user data and generating guest IDs. These utilities are used automatically by the AuthProvider and do not need to be called directly.
</Note>


# Bundler Configuration
Source: https://docs.ouim.me/logto-authkit/configuration/bundler-setup

Configure Vite, Webpack, or Next.js to work with logto-authkit

logto-authkit provides pre-configured bundler settings to resolve common issues with the `jose` library and optimize dependencies.

## Why Bundler Configuration?

The underlying Logto SDK uses the `jose` library for JWT handling, which can cause bundling issues in some environments. logto-authkit provides ready-to-use configurations that:

* Resolve `jose` library compatibility issues
* Optimize dependency bundling
* Ensure proper module resolution

## Vite Configuration

<Warning>
  When editing a Vite config or other build-time script, import directly from the `bundler-config` subpath. This avoids executing the main library bundle (which pulls in React and may cause issues during Node startup).
</Warning>

```javascript vite.config.js theme={null}
import { viteConfig } from '@ouim/logto-authkit/bundler-config'

export default {
  ...viteConfig,
  // your other config
}
```

### What's Included

The Vite configuration provides:

```javascript theme={null}
{
  optimizeDeps: {
    include: ['@logto/react', '@ouim/better-logto-react'],
  },
  resolve: {
    alias: {
      jose: 'jose/dist/node/cjs',
    },
  },
}
```

## Webpack Configuration

```javascript webpack.config.js theme={null}
import { webpackConfig } from '@ouim/logto-authkit'

module.exports = {
  ...webpackConfig,
  // your other config
}
```

### What's Included

The Webpack configuration provides:

```javascript theme={null}
{
  resolve: {
    alias: {
      jose: 'jose/dist/node/cjs',
    },
  },
}
```

## Next.js Configuration

```javascript next.config.js theme={null}
import { nextjsConfig } from '@ouim/logto-authkit'

module.exports = {
  ...nextjsConfig,
  // your other config
}
```

### What's Included

The Next.js configuration provides the same alias configuration as Webpack:

```javascript theme={null}
{
  resolve: {
    alias: {
      jose: 'jose/dist/node/cjs',
    },
  },
}
```

## Custom Configuration

If you need more control or want to integrate the configuration differently, you can use the `getBundlerConfig` helper:

```javascript theme={null}
import { getBundlerConfig } from '@ouim/logto-authkit/bundler-config'

// Get configuration for specific bundler
const viteConfig = getBundlerConfig('vite')
const webpackConfig = getBundlerConfig('webpack')
const nextConfig = getBundlerConfig('nextjs')
```

### Parameters

The `getBundlerConfig` function accepts one parameter:

<ParamField type="'vite' | 'webpack' | 'nextjs'">
  The bundler type to get configuration for
</ParamField>

### Merging with Existing Config

You can merge the provided configuration with your existing setup:

```javascript vite.config.js theme={null}
import { getBundlerConfig } from '@ouim/logto-authkit/bundler-config'
import { defineConfig } from 'vite'

const logtoConfig = getBundlerConfig('vite')

export default defineConfig({
  // Merge optimize deps
  optimizeDeps: {
    ...logtoConfig.optimizeDeps,
    include: [
      ...logtoConfig.optimizeDeps.include,
      'your-other-deps',
    ],
  },
  // Merge resolve aliases
  resolve: {
    ...logtoConfig.resolve,
    alias: {
      ...logtoConfig.resolve.alias,
      '@': '/src',
    },
  },
  // Your other config
  plugins: [...],
})
```

<Tip>
  The bundler configuration is minimal and designed to be easily merged with your existing setup. It only modifies what's necessary for logto-authkit to work properly.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Module not found: jose">
    Make sure you've applied the bundler configuration. The `jose` alias resolves to the CommonJS distribution which is more compatible with bundlers.
  </Accordion>

  <Accordion title="React errors during build">
    If you're importing from the main package in your build config, switch to importing from `@ouim/logto-authkit/bundler-config` instead. This avoids loading React during the build process.
  </Accordion>

  <Accordion title="Vite optimization errors">
    If you see errors about pre-bundling dependencies, make sure the `optimizeDeps.include` array includes both `@logto/react` and `@ouim/better-logto-react`.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Guest Mode" icon="user" href="/logto-authkit/configuration/guest-mode">
    Learn how to enable guest mode for unauthenticated users
  </Card>

  <Card title="Custom Navigation" icon="route" href="/logto-authkit/configuration/custom-navigation">
    Set up custom navigation with your router
  </Card>
</CardGroup>


# Custom Navigation
Source: https://docs.ouim.me/logto-authkit/configuration/custom-navigation

Integrate logto-authkit with React Router, Next.js, or other routing libraries

logto-authkit supports custom navigation to integrate seamlessly with your routing library, preventing full page reloads during authentication flows.

## Why Custom Navigation?

By default, Logto uses `window.location.href` for navigation, which causes full page reloads. Custom navigation allows you to:

* Use client-side routing (React Router, Next.js, etc.)
* Maintain application state during auth flows
* Provide a smoother user experience
* Control navigation behavior in SPAs

## Basic Setup

Pass a `customNavigate` function to the `AuthProvider`:

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'

const config = {
  endpoint: 'https://your-logto-endpoint.com',
  appId: 'your-app-id',
}

function App() {
  const customNavigate = (url, options) => {
    // Your navigation logic here
    console.log('Navigating to:', url, options)
  }

  return (
    <AuthProvider
      config={config}
      callbackUrl="http://localhost:3000/callback"
      customNavigate={customNavigate}
    >
      <YourApp />
    </AuthProvider>
  )
}
```

## React Router Integration

### React Router v6

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'
import { BrowserRouter, useNavigate } from 'react-router-dom'

function AppProviders({ children }) {
  const navigate = useNavigate()

  const customNavigate = (url, options) => {
    // Handle both relative and absolute URLs
    if (url.startsWith('http://') || url.startsWith('https://')) {
      // External URL - use window.location
      window.location.href = url
    } else {
      // Internal URL - use React Router
      navigate(url, { replace: options?.replace })
    }
  }

  return (
    <AuthProvider
      config={logtoConfig}
      callbackUrl="/callback"
      customNavigate={customNavigate}
    >
      {children}
    </AuthProvider>
  )
}

function App() {
  return (
    <BrowserRouter>
      <AppProviders>
        <YourApp />
      </AppProviders>
    </BrowserRouter>
  )
}
```

### React Router v5

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'
import { BrowserRouter, useHistory } from 'react-router-dom'

function AppProviders({ children }) {
  const history = useHistory()

  const customNavigate = (url, options) => {
    if (url.startsWith('http://') || url.startsWith('https://')) {
      window.location.href = url
    } else {
      if (options?.replace) {
        history.replace(url)
      } else {
        history.push(url)
      }
    }
  }

  return (
    <AuthProvider
      config={logtoConfig}
      callbackUrl="/callback"
      customNavigate={customNavigate}
    >
      {children}
    </AuthProvider>
  )
}
```

## Next.js Integration

### App Router (Next.js 13+)

```tsx theme={null}
'use client'

import { AuthProvider } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'

function Providers({ children }) {
  const router = useRouter()

  const customNavigate = (url, options) => {
    if (url.startsWith('http://') || url.startsWith('https://')) {
      window.location.href = url
    } else {
      if (options?.replace) {
        router.replace(url)
      } else {
        router.push(url)
      }
    }
  }

  return (
    <AuthProvider
      config={logtoConfig}
      callbackUrl="/callback"
      customNavigate={customNavigate}
    >
      {children}
    </AuthProvider>
  )
}
```

### Pages Router (Next.js 12 and earlier)

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'
import { useRouter } from 'next/router'

function MyApp({ Component, pageProps }) {
  const router = useRouter()

  const customNavigate = (url, options) => {
    if (url.startsWith('http://') || url.startsWith('https://')) {
      window.location.href = url
    } else {
      if (options?.replace) {
        router.replace(url)
      } else {
        router.push(url)
      }
    }
  }

  return (
    <AuthProvider
      config={logtoConfig}
      callbackUrl="/callback"
      customNavigate={customNavigate}
    >
      <Component {...pageProps} />
    </AuthProvider>
  )
}
```

## Navigation Options

The `customNavigate` function receives two parameters:

<ParamField type="string">
  The URL to navigate to (can be relative or absolute)
</ParamField>

<ParamField type="NavigationOptions">
  Navigation options object:

  <Expandable title="properties">
    <ParamField type="boolean">
      Whether to replace the current history entry instead of pushing a new one
    </ParamField>
  </Expandable>
</ParamField>

## How It Works

<Steps>
  <Step title="Provider Registration">
    When you pass `customNavigate` to `AuthProvider`, it registers your navigation function globally for the library.
  </Step>

  <Step title="Internal Navigation Calls">
    When logto-authkit needs to navigate (e.g., after sign-in, during callback), it uses your custom function instead of `window.location.href`.
  </Step>

  <Step title="Cleanup on Unmount">
    When the `AuthProvider` unmounts, it automatically unregisters the custom navigation function.
  </Step>
</Steps>

## Implementation Details

The custom navigation is set using the `setCustomNavigate` utility from the library:

```typescript theme={null}
// From context.tsx (line 360-365)
useEffect(() => {
  setCustomNavigate(customNavigate || null)

  // Cleanup on unmount
  return () => setCustomNavigate(null)
}, [customNavigate])
```

This ensures that:

* The navigation function is available throughout the library
* It's properly cleaned up when the component unmounts
* You can dynamically change the navigation function if needed

## Best Practices

<AccordionGroup>
  <Accordion title="Handle External URLs">
    Always check if the URL is external (starts with `http://` or `https://`) and use `window.location.href` for those cases. Authentication flows may redirect to external Logto servers.

    ```tsx theme={null}
    const customNavigate = (url, options) => {
      if (url.startsWith('http://') || url.startsWith('https://')) {
        window.location.href = url
      } else {
        // Use your router
      }
    }
    ```
  </Accordion>

  <Accordion title="Support Replace Option">
    Respect the `options.replace` parameter to allow the library to replace history entries when appropriate.

    ```tsx theme={null}
    const customNavigate = (url, options) => {
      if (options?.replace) {
        router.replace(url)
      } else {
        router.push(url)
      }
    }
    ```
  </Accordion>

  <Accordion title="Use Stable Functions">
    Make sure your `customNavigate` function is stable (use `useCallback` if needed) to prevent unnecessary re-renders.

    ```tsx theme={null}
    const customNavigate = useCallback((url, options) => {
      // navigation logic
    }, [router])
    ```
  </Accordion>
</AccordionGroup>

## Popup Sign-In

Custom navigation works seamlessly with popup sign-in mode:

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'
import { useNavigate } from 'react-router-dom'

function AppProviders({ children }) {
  const navigate = useNavigate()

  const customNavigate = (url, options) => {
    if (url.startsWith('http://') || url.startsWith('https://')) {
      window.location.href = url
    } else {
      navigate(url, { replace: options?.replace })
    }
  }

  return (
    <AuthProvider
      config={logtoConfig}
      callbackUrl="/callback"
      customNavigate={customNavigate}
      enablePopupSignIn={true} // Popup mode
    >
      {children}
    </AuthProvider>
  )
}
```

<Info>
  When using popup sign-in, the main window navigation is handled by your custom function, while the popup window uses its own navigation context.
</Info>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Full page reload after sign-in">
    Make sure your `customNavigate` function is properly handling relative URLs. Check that you're not falling back to `window.location.href` for internal routes.
  </Accordion>

  <Accordion title="Navigation not working">
    Verify that your router hook is available in the component where you define `customNavigate`. For React Router, ensure you're inside a `<BrowserRouter>`. For Next.js, make sure you're in a client component (`'use client'`).
  </Accordion>

  <Accordion title="Infinite redirects">
    Check that your callback URL matches the route where you render `<CallbackPage />`. Mismatched URLs can cause redirect loops.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="AuthProvider" icon="layer-group" href="/logto-authkit/frontend/auth-provider">
    Learn more about AuthProvider configuration
  </Card>

  <Card title="useAuth Hook" icon="code" href="/logto-authkit/frontend/use-auth">
    Learn more about the useAuth hook
  </Card>
</CardGroup>


# Guest Mode
Source: https://docs.ouim.me/logto-authkit/configuration/guest-mode

Enable guest mode to support unauthenticated users with fingerprinting

Guest mode allows your application to work with both authenticated and unauthenticated users, providing a seamless experience with built-in fingerprint-based guest IDs.

## Overview

When guest mode is enabled:

* Unauthenticated users automatically get a unique guest ID
* Guest IDs are stored in the `guest_logto_authtoken` cookie for persistence
* Your app can track guest users across sessions
* Guest users can later sign in without losing their data

## Frontend Setup

Use the `useAuth` hook with the `guest` middleware:

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function MixedContent() {
  const { user } = useAuth({
    middleware: 'guest', // Allow guest users
  })

  return (
    <div>
      {user ? (
        <p>Welcome back, {user.name}!</p>
      ) : (
        <p>You're browsing as a guest</p>
      )}
    </div>
  )
}
```

### Middleware Options

The `useAuth` hook supports different middleware modes:

<ParamField type="'auth' | 'guest'">
  * `'auth'`: Require authentication (redirect if not logged in)
  * `'guest'`: Allow both authenticated and guest users
</ParamField>

<ParamField type="string">
  URL to redirect to when authentication is required (used with `middleware: 'auth'`)
</ParamField>

### Route Protection with Auth Middleware

```tsx theme={null}
function ProtectedPage() {
  const { user } = useAuth({
    middleware: 'auth',
    redirectTo: '/login', // Redirect if not authenticated
  })

  if (!user) return null // or loading indicator
  
  return <div>Protected content for {user.name}</div>
}
```

## Server Setup

Enable guest mode in your server authentication middleware:

### Express.js

```javascript theme={null}
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server'

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: 'https://your-logto-domain.com',
  audience: 'your-api-resource-identifier',
  cookieName: 'logto_authtoken',
  allowGuest: true, // Enable guest mode
})

app.get('/api/content', authMiddleware, (req, res) => {
  res.json({
    userId: req.auth.userId,
    isAuthenticated: req.auth.isAuthenticated,
    isGuest: req.auth.isGuest,
    guestId: req.auth.guestId, // Available when isGuest is true
  })
})
```

### Next.js API Routes

```javascript theme={null}
import { verifyNextAuth } from '@ouim/logto-authkit/server'

export async function GET(request) {
  const authResult = await verifyNextAuth(request, {
    logtoUrl: 'https://your-logto-domain.com',
    audience: 'your-api-resource-identifier',
    allowGuest: true, // Enable guest mode
  })

  if (!authResult.success) {
    return Response.json({ error: authResult.error }, { status: 401 })
  }

  return Response.json({
    userId: authResult.auth.userId,
    isAuthenticated: authResult.auth.isAuthenticated,
    isGuest: authResult.auth.isGuest,
    guestId: authResult.auth.guestId,
  })
}
```

## Auth Context Structure

When guest mode is enabled, the auth context includes additional fields:

```typescript theme={null}
interface AuthContext {
  userId: string | null        // User ID from token (null for guests)
  isAuthenticated: boolean     // true for authenticated users
  isGuest: boolean            // true for guest users
  payload: AuthPayload | null // Full JWT payload (null for guests)
  guestId?: string            // Guest fingerprint ID (when allowGuest is true)
}
```

## How Guest IDs Work

<Steps>
  <Step title="Guest ID Generation">
    When a user visits your site without authentication, logto-authkit automatically generates a unique guest ID using browser fingerprinting.
  </Step>

  <Step title="Persistence">
    The guest ID is stored in the browser's `guest_logto_authtoken` cookie, ensuring the same ID is used across sessions.
  </Step>

  <Step title="Server Verification">
    When `allowGuest: true` is set, the server helpers can return a guest auth context when no valid JWT token is available, using the guest cookie to persist the guest ID.
  </Step>

  <Step title="Upgrade to Authenticated">
    When a guest user signs in, they receive a proper JWT token. You can associate their previous guest activity with their authenticated account using the guest ID.
  </Step>
</Steps>

## Use Cases

<CardGroup>
  <Card title="Shopping Cart" icon="cart-shopping">
    Allow users to add items to cart before signing in, then associate the cart with their account after login.
  </Card>

  <Card title="Content Personalization" icon="sparkles">
    Track guest preferences and browsing history, then merge with their profile when they sign in.
  </Card>

  <Card title="Analytics" icon="chart-line">
    Track user behavior for both authenticated and guest users with a consistent identifier.
  </Card>

  <Card title="Gradual Onboarding" icon="stairs">
    Let users explore your app as guests, then prompt them to sign in when they need advanced features.
  </Card>
</CardGroup>

## Example: Tracking Guest to User Conversion

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'
import { useEffect, useState } from 'react'

function ProductPage() {
  const { user, isLoadingUser } = useAuth({ middleware: 'guest' })
  const [guestId, setGuestId] = useState<string | null>(null)

  useEffect(() => {
    // Store guest ID before user signs in
    if (!user && typeof window !== 'undefined') {
      const storedGuestId = document.cookie
        .split('; ')
        .find((entry) => entry.startsWith('guest_logto_authtoken='))
        ?.split('=')[1] ?? null
      setGuestId(storedGuestId)
    }
  }, [user])

  useEffect(() => {
    // User just signed in - migrate guest data
    if (user && guestId) {
      migrateGuestData(guestId, user.id)
      setGuestId(null)
    }
  }, [user, guestId])

  async function migrateGuestData(guestId: string, userId: string) {
    // Call your API to associate guest data with the user
    await fetch('/api/migrate-guest-data', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ guestId, userId }),
    })
  }

  if (isLoadingUser) return <div>Loading...</div>

  return (
    <div>
      {user ? (
        <p>Welcome back, {user.name}!</p>
      ) : (
        <p>Browsing as guest (ID: {guestId})</p>
      )}
    </div>
  )
}
```

<Warning>
  Guest IDs are stored in a browser cookie and can still be cleared by the user. Don't rely on them for critical functionality or security. They're best used for convenience features like cart persistence.
</Warning>

## Configuration Options

<ParamField type="boolean">
  Enable guest mode in server middleware
</ParamField>

<ParamField type="string">
  Custom cookie name for both JWT tokens and guest IDs
</ParamField>

## Next Steps

<CardGroup>
  <Card title="Server Authentication" icon="shield" href="/logto-authkit/server/overview">
    Learn more about server authentication
  </Card>

  <Card title="useAuth Hook" icon="hook" href="/logto-authkit/frontend/use-auth">
    Explore all useAuth hook options
  </Card>
</CardGroup>


# Next.js App Example
Source: https://docs.ouim.me/logto-authkit/examples/nextjs-app

Complete Next.js application example with logto-authkit

This example demonstrates how to integrate logto-authkit into a Next.js application with both client and server-side authentication.

## Complete Example

<Steps>
  <Step title="Install Dependencies">
    Install logto-authkit and required dependencies:

    ```bash theme={null}
    npm install @ouim/logto-authkit @logto/react
    ```
  </Step>

  <Step title="Create Root Layout">
    Set up the auth provider in your root layout:

    ```tsx app/layout.tsx theme={null}
    import { AuthProvider } from '@ouim/logto-authkit'
    import './globals.css'

    export default function RootLayout({
      children,
    }: {
      children: React.ReactNode
    }) {
      return (
        <html lang="en">
          <body>
            <AuthProvider
              config={{
                endpoint: process.env.NEXT_PUBLIC_LOGTO_ENDPOINT!,
                appId: process.env.NEXT_PUBLIC_LOGTO_APP_ID!,
                resources: [process.env.NEXT_PUBLIC_API_RESOURCE!],
                scopes: ['openid', 'profile', 'email'],
              }}
              callbackUrl={`${process.env.NEXT_PUBLIC_APP_URL}/callback`}
              enablePopupSignIn={true}
            >
              {children}
            </AuthProvider>
          </body>
        </html>
      )
    }
    ```
  </Step>

  <Step title="Create Home Page">
    Build your landing page with authentication:

    ```tsx app/page.tsx theme={null}
    'use client'

    import { useAuth, UserCenter } from '@ouim/logto-authkit'
    import Link from 'next/link'

    export default function Home() {
      const { user, isLoadingUser, signIn } = useAuth()

      return (
        <div className="min-h-screen bg-gradient-to-b from-gray-50 to-gray-100">
          <nav className="bg-white shadow-sm">
            <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
              <div className="flex justify-between h-16">
                <div className="flex items-center">
                  <Link href="/" className="text-xl font-bold text-gray-900">
                    logto-authkit App
                  </Link>
                </div>
                <div className="flex items-center gap-4">
                  {user && (
                    <Link
                      href="/dashboard"
                      className="text-gray-700 hover:text-gray-900"
                    >
                      Dashboard
                    </Link>
                  )}
                  <UserCenter />
                </div>
              </div>
            </div>
          </nav>

          <main className="max-w-7xl mx-auto py-16 px-4 sm:px-6 lg:px-8">
            <div className="text-center">
              <h1 className="text-5xl font-bold text-gray-900 mb-6">
                Welcome to logto-authkit
              </h1>
              <p className="text-xl text-gray-600 mb-8 max-w-2xl mx-auto">
                A simplified authentication solution for Next.js applications.
                Get started with secure, production-ready auth in minutes.
              </p>

              {isLoadingUser ? (
                <div className="flex justify-center">
                  <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600"></div>
                </div>
              ) : user ? (
                <div className="space-y-4">
                  <div className="bg-white rounded-lg shadow-md p-6 max-w-md mx-auto">
                    <p className="text-lg font-semibold text-gray-900 mb-2">
                      Welcome back, {user.name || user.email}!
                    </p>
                    <p className="text-gray-600">
                      You are successfully authenticated.
                    </p>
                  </div>
                  <Link
                    href="/dashboard"
                    className="inline-block bg-blue-600 text-white px-8 py-3 rounded-lg hover:bg-blue-700 font-semibold"
                  >
                    Go to Dashboard
                  </Link>
                </div>
              ) : (
                <div className="space-y-4">
                  <button
                    onClick={() => signIn()}
                    className="bg-blue-600 text-white px-8 py-3 rounded-lg hover:bg-blue-700 font-semibold"
                  >
                    Sign In
                  </button>
                  <p className="text-sm text-gray-500">
                    Sign in to access your personalized dashboard
                  </p>
                </div>
              )}
            </div>
          </main>
        </div>
      )
    }
    ```
  </Step>

  <Step title="Create Protected Dashboard">
    Build a dashboard with automatic authentication protection:

    ```tsx app/dashboard/page.tsx theme={null}
    'use client'

    import { useAuth, UserCenter } from '@ouim/logto-authkit'
    import Link from 'next/link'

    export default function Dashboard() {
      const { user, isLoadingUser } = useAuth({
        middleware: 'auth',
        redirectTo: '/signin',
      })

      if (isLoadingUser) {
        return (
          <div className="flex items-center justify-center min-h-screen">
            <div className="animate-spin rounded-full h-16 w-16 border-b-2 border-blue-600"></div>
          </div>
        )
      }

      return (
        <div className="min-h-screen bg-gray-50">
          <nav className="bg-white shadow-sm">
            <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
              <div className="flex justify-between h-16">
                <div className="flex items-center">
                  <Link href="/" className="text-xl font-bold text-gray-900">
                    logto-authkit App
                  </Link>
                </div>
                <div className="flex items-center">
                  <UserCenter />
                </div>
              </div>
            </div>
          </nav>

          <main className="max-w-7xl mx-auto py-8 px-4 sm:px-6 lg:px-8">
            <div className="mb-8">
              <h1 className="text-3xl font-bold text-gray-900">Dashboard</h1>
              <p className="text-gray-600 mt-2">Welcome to your protected dashboard</p>
            </div>

            <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
              <div className="bg-white rounded-lg shadow p-6">
                <h2 className="text-xl font-semibold mb-4 text-gray-900">
                  User Profile
                </h2>
                <dl className="space-y-3">
                  <div>
                    <dt className="text-sm font-medium text-gray-500">User ID</dt>
                    <dd className="mt-1 text-sm text-gray-900 font-mono">{user?.id}</dd>
                  </div>
                  <div>
                    <dt className="text-sm font-medium text-gray-500">Name</dt>
                    <dd className="mt-1 text-sm text-gray-900">
                      {user?.name || 'Not provided'}
                    </dd>
                  </div>
                  <div>
                    <dt className="text-sm font-medium text-gray-500">Email</dt>
                    <dd className="mt-1 text-sm text-gray-900">
                      {user?.email || 'Not provided'}
                    </dd>
                  </div>
                </dl>
              </div>

              <div className="bg-white rounded-lg shadow p-6">
                <h2 className="text-xl font-semibold mb-4 text-gray-900">
                  Authentication Status
                </h2>
                <div className="space-y-3">
                  <div className="flex items-center">
                    <div className="w-3 h-3 bg-green-500 rounded-full mr-3"></div>
                    <span className="text-sm text-gray-900">Authenticated</span>
                  </div>
                  <p className="text-sm text-gray-600">
                    You have successfully authenticated and can access protected
                    resources.
                  </p>
                  <Link
                    href="/api/user"
                    target="_blank"
                    className="inline-block text-sm text-blue-600 hover:text-blue-800"
                  >
                    View API Response →
                  </Link>
                </div>
              </div>
            </div>
          </main>
        </div>
      )
    }
    ```
  </Step>

  <Step title="Create API Route with Server-Side Auth">
    Add a protected API route using server-side authentication:

    ```ts app/api/user/route.ts theme={null}
    import { NextRequest, NextResponse } from 'next/server'
    import { verifyNextAuth } from '@ouim/logto-authkit/server'

    export async function GET(request: NextRequest) {
      const result = await verifyNextAuth(request, {
        logtoUrl: process.env.LOGTO_ENDPOINT!,
        audience: process.env.LOGTO_API_RESOURCE!,
      })

      if (!result.success) {
        return NextResponse.json(
          { error: result.error },
          { status: 401 }
        )
      }

      // Access authenticated user info
      const { auth } = result

      return NextResponse.json({
        userId: auth.userId,
        isAuthenticated: auth.isAuthenticated,
        payload: auth.payload,
      })
    }
    ```
  </Step>

  <Step title="Add Authentication Pages">
    Create the required callback and sign-in pages:

    <CodeGroup>
      ```tsx app/callback/page.tsx theme={null}
      'use client'

      import { CallbackPage } from '@ouim/logto-authkit'

      export default function Callback() {
        return (
          <CallbackPage
            onSuccess={() => {
              console.log('Authentication successful')
            }}
            onError={(error) => {
              console.error('Authentication failed:', error)
            }}
          />
        )
      }
      ```

      ```tsx app/signin/page.tsx theme={null}
      'use client'

      import { SignInPage } from '@ouim/logto-authkit'

      export default function SignIn() {
        return <SignInPage />
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure Environment Variables">
    Create a `.env.local` file with your Logto configuration:

    ```bash .env.local theme={null}
    NEXT_PUBLIC_LOGTO_ENDPOINT=https://your-tenant.logto.app
    NEXT_PUBLIC_LOGTO_APP_ID=your-app-id
    NEXT_PUBLIC_API_RESOURCE=https://api.yourapp.com
    NEXT_PUBLIC_APP_URL=http://localhost:3000

    # Server-side variables
    LOGTO_ENDPOINT=https://your-tenant.logto.app
    LOGTO_API_RESOURCE=https://api.yourapp.com
    ```
  </Step>
</Steps>

## Server-Side Authentication

logto-authkit supports server-side authentication for API routes and middleware:

<Tabs>
  <Tab title="API Routes">
    ```ts app/api/protected/route.ts theme={null}
    import { NextRequest, NextResponse } from 'next/server'
    import { verifyNextAuth } from '@ouim/logto-authkit/server'

    export async function GET(request: NextRequest) {
      const result = await verifyNextAuth(request, {
        logtoUrl: process.env.LOGTO_ENDPOINT!,
        audience: process.env.LOGTO_API_RESOURCE!,
      })

      if (!result.success) {
        return NextResponse.json(
          { error: 'Unauthorized' },
          { status: 401 }
        )
      }

      return NextResponse.json({
        message: 'Protected data',
        userId: result.auth.userId,
      })
    }
    ```
  </Tab>

  <Tab title="Middleware">
    ```ts middleware.ts theme={null}
    import { NextResponse } from 'next/server'
    import type { NextRequest } from 'next/server'
    import { verifyNextAuth } from '@ouim/logto-authkit/server'

    export async function middleware(request: NextRequest) {
      // Only protect API routes
      if (request.nextUrl.pathname.startsWith('/api/protected')) {
        const result = await verifyNextAuth(request, {
          logtoUrl: process.env.LOGTO_ENDPOINT!,
          audience: process.env.LOGTO_API_RESOURCE!,
        })

        if (!result.success) {
          return NextResponse.json(
            { error: 'Unauthorized' },
            { status: 401 }
          )
        }
      }

      return NextResponse.next()
    }

    export const config = {
      matcher: '/api/protected/:path*',
    }
    ```
  </Tab>
</Tabs>

## Features Demonstrated

* **Next.js App Router**: Full integration with App Router
* **Client-Side Auth**: Protected pages with automatic redirects
* **Server-Side Auth**: Secure API routes with JWT verification
* **Environment Variables**: Proper configuration management
* **Popup Sign-In**: Optional popup-based authentication
* **User Center**: Pre-built UI component for user management

## Running the Example

```bash theme={null}
npm run dev
```

Visit `http://localhost:3000` to see your Next.js app with authentication.

## Next Steps

<CardGroup>
  <Card title="Protected Routes" icon="lock" href="/logto-authkit/examples/protected-routes">
    Advanced route protection patterns
  </Card>

  <Card title="Server Integration" icon="server" href="/logto-authkit/server/overview">
    Learn more about server-side auth
  </Card>
</CardGroup>


# Protected Routes Example
Source: https://docs.ouim.me/logto-authkit/examples/protected-routes

Learn how to implement protected routes and access control

This guide demonstrates various patterns for protecting routes and implementing access control in your application using logto-authkit.

## Basic Route Protection

The simplest way to protect a route is using the `middleware` option in the `useAuth` hook:

```tsx pages/Dashboard.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

export default function Dashboard() {
  const { user, isLoadingUser } = useAuth({
    middleware: 'auth',
    redirectTo: '/signin',
  })

  if (isLoadingUser) {
    return <div>Loading...</div>
  }

  return (
    <div>
      <h1>Protected Dashboard</h1>
      <p>Welcome, {user?.name}!</p>
    </div>
  )
}
```

## Advanced Protection Patterns

<Tabs>
  <Tab title="Guest-Only Routes">
    Redirect authenticated users away from sign-in pages:

    ```tsx pages/Login.tsx theme={null}
    import { useAuth } from '@ouim/logto-authkit'

    export default function Login() {
      const { user, isLoadingUser } = useAuth({
        middleware: 'guest',
        redirectIfAuthenticated: '/dashboard',
      })

      if (isLoadingUser) {
        return <div>Loading...</div>
      }

      return (
        <div>
          <h1>Sign In</h1>
          <p>Please sign in to continue</p>
        </div>
      )
    }
    ```
  </Tab>

  <Tab title="Custom Navigation">
    Use custom navigation options for more control:

    ```tsx pages/Settings.tsx theme={null}
    import { useAuth } from '@ouim/logto-authkit'

    export default function Settings() {
      const { user, isLoadingUser } = useAuth({
        middleware: 'auth',
        redirectTo: '/signin',
        navigationOptions: {
          replace: true, // Use replaceState instead of pushState
          force: false,  // Only navigate if not already on target page
        },
      })

      if (isLoadingUser) {
        return <div>Loading...</div>
      }

      return (
        <div>
          <h1>Settings</h1>
          <p>User ID: {user?.id}</p>
        </div>
      )
    }
    ```
  </Tab>

  <Tab title="Conditional Protection">
    Implement complex access control logic:

    ```tsx pages/AdminPanel.tsx theme={null}
    import { useAuth } from '@ouim/logto-authkit'
    import { useEffect } from 'react'
    import { useNavigate } from 'react-router-dom'

    export default function AdminPanel() {
      const { user, isLoadingUser } = useAuth({
        middleware: 'auth',
        redirectTo: '/signin',
      })
      const navigate = useNavigate()

      useEffect(() => {
        // Custom role-based access control
        if (!isLoadingUser && user) {
          const isAdmin = user.roles?.includes('admin')
          if (!isAdmin) {
            navigate('/unauthorized')
          }
        }
      }, [user, isLoadingUser, navigate])

      if (isLoadingUser) {
        return <div>Loading...</div>
      }

      return (
        <div>
          <h1>Admin Panel</h1>
          <p>Welcome, Admin {user?.name}</p>
        </div>
      )
    }
    ```
  </Tab>
</Tabs>

## Route Guard Component

Create a reusable route guard component for cleaner code:

<Steps>
  <Step title="Create Route Guard Component">
    ```tsx components/RouteGuard.tsx theme={null}
    import { useAuth } from '@ouim/logto-authkit'
    import { ReactNode } from 'react'

    interface RouteGuardProps {
      children: ReactNode
      fallback?: ReactNode
      requireAuth?: boolean
      redirectTo?: string
    }

    export function RouteGuard({
      children,
      fallback = <div>Loading...</div>,
      requireAuth = true,
      redirectTo = '/signin',
    }: RouteGuardProps) {
      const { user, isLoadingUser } = useAuth({
        middleware: requireAuth ? 'auth' : undefined,
        redirectTo: requireAuth ? redirectTo : undefined,
      })

      if (isLoadingUser) {
        return <>{fallback}</>
      }

      if (requireAuth && !user) {
        return null // Will redirect
      }

      return <>{children}</>
    }
    ```
  </Step>

  <Step title="Use Route Guard">
    ```tsx pages/Profile.tsx theme={null}
    import { RouteGuard } from '../components/RouteGuard'
    import { useAuth } from '@ouim/logto-authkit'

    export default function Profile() {
      const { user } = useAuth()

      return (
        <RouteGuard>
          <div>
            <h1>User Profile</h1>
            <p>Name: {user?.name}</p>
            <p>Email: {user?.email}</p>
          </div>
        </RouteGuard>
      )
    }
    ```
  </Step>
</Steps>

## React Router Integration

Protect routes at the router level:

```tsx App.tsx theme={null}
import { AuthProvider, useAuth } from '@ouim/logto-authkit'
import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom'
import { ReactNode } from 'react'

// Protected route wrapper
function ProtectedRoute({ children }: { children: ReactNode }) {
  const { user, isLoadingUser } = useAuth()

  if (isLoadingUser) {
    return (
      <div className="flex items-center justify-center min-h-screen">
        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600"></div>
      </div>
    )
  }

  if (!user) {
    return <Navigate to="/signin" replace />
  }

  return <>{children}</>
}

function App() {
  return (
    <AuthProvider
      config={{
        endpoint: 'https://your-tenant.logto.app',
        appId: 'your-app-id',
      }}
    >
      <BrowserRouter>
        <Routes>
          <Route path="/" element={<Home />} />
          <Route path="/signin" element={<SignIn />} />
          <Route path="/callback" element={<Callback />} />
          
          {/* Protected routes */}
          <Route
            path="/dashboard"
            element={
              <ProtectedRoute>
                <Dashboard />
              </ProtectedRoute>
            }
          />
          <Route
            path="/profile"
            element={
              <ProtectedRoute>
                <Profile />
              </ProtectedRoute>
            }
          />
        </Routes>
      </BrowserRouter>
    </AuthProvider>
  )
}
```

## Next.js Route Protection

For Next.js applications, use client-side protection:

<Tabs>
  <Tab title="App Router">
    ```tsx app/dashboard/layout.tsx theme={null}
    'use client'

    import { useAuth } from '@ouim/logto-authkit'
    import { useRouter } from 'next/navigation'
    import { useEffect } from 'react'

    export default function DashboardLayout({
      children,
    }: {
      children: React.ReactNode
    }) {
      const { user, isLoadingUser } = useAuth()
      const router = useRouter()

      useEffect(() => {
        if (!isLoadingUser && !user) {
          router.push('/signin')
        }
      }, [user, isLoadingUser, router])

      if (isLoadingUser) {
        return (
          <div className="flex items-center justify-center min-h-screen">
            <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600"></div>
          </div>
        )
      }

      if (!user) {
        return null
      }

      return <>{children}</>
    }
    ```
  </Tab>

  <Tab title="Pages Router">
    ```tsx pages/dashboard.tsx theme={null}
    import { useAuth } from '@ouim/logto-authkit'
    import { useRouter } from 'next/router'
    import { useEffect } from 'react'

    export default function Dashboard() {
      const { user, isLoadingUser } = useAuth()
      const router = useRouter()

      useEffect(() => {
        if (!isLoadingUser && !user) {
          router.push('/signin')
        }
      }, [user, isLoadingUser, router])

      if (isLoadingUser) {
        return <div>Loading...</div>
      }

      if (!user) {
        return null
      }

      return (
        <div>
          <h1>Dashboard</h1>
          <p>Welcome, {user.name}!</p>
        </div>
      )
    }
    ```
  </Tab>
</Tabs>

## Role-Based Access Control

Implement role-based access control (RBAC):

```tsx hooks/useRBAC.ts theme={null}
import { useAuth } from '@ouim/logto-authkit'
import { useMemo } from 'react'

type Role = 'admin' | 'user' | 'moderator'

export function useRBAC() {
  const { user } = useAuth()

  const hasRole = useMemo(() => {
    return (role: Role) => {
      return user?.roles?.includes(role) ?? false
    }
  }, [user])

  const hasAnyRole = useMemo(() => {
    return (roles: Role[]) => {
      return roles.some(role => user?.roles?.includes(role))
    }
  }, [user])

  const hasAllRoles = useMemo(() => {
    return (roles: Role[]) => {
      return roles.every(role => user?.roles?.includes(role))
    }
  }, [user])

  return {
    hasRole,
    hasAnyRole,
    hasAllRoles,
    userRoles: user?.roles || [],
  }
}
```

Use the RBAC hook in your components:

```tsx pages/AdminDashboard.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'
import { useRBAC } from '../hooks/useRBAC'
import { useNavigate } from 'react-router-dom'
import { useEffect } from 'react'

export default function AdminDashboard() {
  const { user, isLoadingUser } = useAuth({
    middleware: 'auth',
    redirectTo: '/signin',
  })
  const { hasRole } = useRBAC()
  const navigate = useNavigate()

  useEffect(() => {
    if (!isLoadingUser && user && !hasRole('admin')) {
      navigate('/unauthorized')
    }
  }, [user, isLoadingUser, hasRole, navigate])

  if (isLoadingUser) {
    return <div>Loading...</div>
  }

  if (!hasRole('admin')) {
    return null
  }

  return (
    <div>
      <h1>Admin Dashboard</h1>
      <p>Admin-only content</p>
    </div>
  )
}
```

## Loading States

Handle loading states elegantly:

```tsx components/ProtectedPage.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'
import { ReactNode } from 'react'

interface ProtectedPageProps {
  children: ReactNode
  loadingComponent?: ReactNode
}

export function ProtectedPage({
  children,
  loadingComponent,
}: ProtectedPageProps) {
  const { user, isLoadingUser } = useAuth({
    middleware: 'auth',
    redirectTo: '/signin',
  })

  if (isLoadingUser) {
    return (
      <>
        {loadingComponent || (
          <div className="flex items-center justify-center min-h-screen">
            <div className="animate-spin rounded-full h-16 w-16 border-b-2 border-blue-600"></div>
          </div>
        )}
      </>
    )
  }

  if (!user) {
    return null // Will redirect
  }

  return <>{children}</>
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Always check loading state">
    Before checking if a user exists, always verify `isLoadingUser` is `false` to avoid race conditions:

    ```tsx theme={null}
    const { user, isLoadingUser } = useAuth()

    if (isLoadingUser) {
      return <LoadingSpinner />
    }

    if (!user) {
      // Safe to redirect or show login
    }
    ```
  </Accordion>

  <Accordion title="Use middleware option for automatic redirects">
    The `middleware` option in `useAuth` provides automatic redirects:

    ```tsx theme={null}
    useAuth({
      middleware: 'auth',      // Require authentication
      redirectTo: '/signin',    // Where to redirect if not authenticated
    })
    ```
  </Accordion>

  <Accordion title="Implement route guards at the router level">
    For cleaner code and better DX, implement protection at the router level rather than in each component.
  </Accordion>

  <Accordion title="Provide clear feedback during loading">
    Always show loading indicators while authentication state is being determined:

    ```tsx theme={null}
    if (isLoadingUser) {
      return <Skeleton />
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="React SPA Example" icon="react" href="/logto-authkit/examples/react-spa">
    See a complete React application
  </Card>

  <Card title="Next.js Example" icon="react" href="/logto-authkit/examples/nextjs-app">
    Explore Next.js integration
  </Card>

  <Card title="useAuth Hook" icon="code" href="/logto-authkit/frontend/use-auth">
    Learn more about the useAuth hook
  </Card>

  <Card title="Server auth" icon="server" href="/logto-authkit/server/overview">
    Implement server-side protection
  </Card>
</CardGroup>


# React SPA Example
Source: https://docs.ouim.me/logto-authkit/examples/react-spa

Complete React single-page application example with logto-authkit

This example demonstrates how to build a complete React SPA with authentication using logto-authkit. It includes user sign-in, protected routes, and user profile management.

## Complete Example

<Steps>
  <Step title="Install Dependencies">
    First, install logto-authkit and its peer dependencies:

    ```bash theme={null}
    npm install @ouim/logto-authkit @logto/react
    ```
  </Step>

  <Step title="Configure Logto Provider">
    Wrap your app with the `AuthProvider` to enable authentication throughout your application:

    ```tsx App.tsx theme={null}
    import { AuthProvider } from '@ouim/logto-authkit'
    import { BrowserRouter, Routes, Route } from 'react-router-dom'
    import Home from './pages/Home'
    import Dashboard from './pages/Dashboard'
    import CallbackPage from './pages/Callback'
    import SignIn from './pages/SignIn'

    function App() {
      return (
        <AuthProvider
          config={{
            endpoint: 'https://your-tenant.logto.app',
            appId: 'your-app-id',
            resources: ['https://api.yourapp.com'],
            scopes: ['openid', 'profile', 'email'],
          }}
          callbackUrl="http://localhost:3000/callback"
          enablePopupSignIn={true}
        >
          <BrowserRouter>
            <Routes>
              <Route path="/" element={<Home />} />
              <Route path="/dashboard" element={<Dashboard />} />
              <Route path="/callback" element={<CallbackPage />} />
              <Route path="/signin" element={<SignIn />} />
            </Routes>
          </BrowserRouter>
        </AuthProvider>
      )
    }

    export default App
    ```
  </Step>

  <Step title="Create Home Page">
    Build a landing page with sign-in functionality:

    ```tsx pages/Home.tsx theme={null}
    import { useAuth, UserCenter } from '@ouim/logto-authkit'
    import { useNavigate } from 'react-router-dom'

    export default function Home() {
      const { user, isLoadingUser, signIn } = useAuth()
      const navigate = useNavigate()

      if (isLoadingUser) {
        return (
          <div className="flex items-center justify-center min-h-screen">
            <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-gray-900"></div>
          </div>
        )
      }

      return (
        <div className="min-h-screen bg-gray-50">
          <nav className="bg-white shadow">
            <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
              <div className="flex justify-between h-16">
                <div className="flex items-center">
                  <h1 className="text-xl font-bold">My App</h1>
                </div>
                <div className="flex items-center">
                  <UserCenter
                    additionalPages={[
                      {
                        link: '/dashboard',
                        text: 'Dashboard',
                        icon: <span>📊</span>,
                      },
                    ]}
                  />
                </div>
              </div>
            </div>
          </nav>

          <main className="max-w-7xl mx-auto py-12 px-4 sm:px-6 lg:px-8">
            <div className="text-center">
              <h2 className="text-4xl font-bold text-gray-900 mb-4">
                Welcome to logto-authkit
              </h2>
              <p className="text-xl text-gray-600 mb-8">
                A simplified authentication solution for React applications
              </p>

              {user ? (
                <div>
                  <p className="text-lg mb-4">
                    Hello, {user.name || user.email}!
                  </p>
                  <button
                    onClick={() => navigate('/dashboard')}
                    className="bg-blue-600 text-white px-6 py-3 rounded-lg hover:bg-blue-700"
                  >
                    Go to Dashboard
                  </button>
                </div>
              ) : (
                <button
                  onClick={() => signIn()}
                  className="bg-blue-600 text-white px-6 py-3 rounded-lg hover:bg-blue-700"
                >
                  Sign In
                </button>
              )}
            </div>
          </main>
        </div>
      )
    }
    ```
  </Step>

  <Step title="Create Protected Dashboard">
    Build a protected dashboard page that requires authentication:

    ```tsx pages/Dashboard.tsx theme={null}
    import { useAuth, UserCenter } from '@ouim/logto-authkit'
    import { useNavigate } from 'react-router-dom'

    export default function Dashboard() {
      const { user, isLoadingUser } = useAuth({
        middleware: 'auth',
        redirectTo: '/signin',
      })
      const navigate = useNavigate()

      if (isLoadingUser) {
        return (
          <div className="flex items-center justify-center min-h-screen">
            <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-gray-900"></div>
          </div>
        )
      }

      return (
        <div className="min-h-screen bg-gray-50">
          <nav className="bg-white shadow">
            <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
              <div className="flex justify-between h-16">
                <div className="flex items-center">
                  <button
                    onClick={() => navigate('/')}
                    className="text-xl font-bold hover:text-blue-600"
                  >
                    My App
                  </button>
                </div>
                <div className="flex items-center">
                  <UserCenter />
                </div>
              </div>
            </div>
          </nav>

          <main className="max-w-7xl mx-auto py-12 px-4 sm:px-6 lg:px-8">
            <div className="bg-white shadow rounded-lg p-6">
              <h2 className="text-2xl font-bold mb-4">Dashboard</h2>

              <div className="space-y-4">
                <div className="border-l-4 border-blue-500 pl-4">
                  <h3 className="font-semibold text-gray-900">User Information</h3>
                  <dl className="mt-2 space-y-2">
                    <div>
                      <dt className="text-sm text-gray-500">ID</dt>
                      <dd className="text-sm font-medium text-gray-900">{user?.id}</dd>
                    </div>
                    <div>
                      <dt className="text-sm text-gray-500">Name</dt>
                      <dd className="text-sm font-medium text-gray-900">{user?.name || 'N/A'}</dd>
                    </div>
                    <div>
                      <dt className="text-sm text-gray-500">Email</dt>
                      <dd className="text-sm font-medium text-gray-900">{user?.email || 'N/A'}</dd>
                    </div>
                  </dl>
                </div>

                <div className="border-l-4 border-green-500 pl-4">
                  <h3 className="font-semibold text-gray-900">Status</h3>
                  <p className="text-sm text-gray-600 mt-2">
                    You are successfully authenticated and can access protected resources.
                  </p>
                </div>
              </div>
            </div>
          </main>
        </div>
      )
    }
    ```
  </Step>

  <Step title="Create Callback and Sign-In Pages">
    Add the required authentication pages:

    <CodeGroup>
      ```tsx pages/Callback.tsx theme={null}
      import { CallbackPage } from '@ouim/logto-authkit'

      export default function Callback() {
        return (
          <CallbackPage
            onSuccess={() => {
              console.log('Authentication successful!')
            }}
            onError={(error) => {
              console.error('Authentication error:', error)
            }}
          />
        )
      }
      ```

      ```tsx pages/SignIn.tsx theme={null}
      import { SignInPage } from '@ouim/logto-authkit'

      export default function SignIn() {
        return <SignInPage />
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## Features Demonstrated

This example showcases:

* **Authentication Provider**: Global auth state management
* **Popup Sign-In**: Optional popup-based authentication flow
* **User Center Component**: Pre-built user menu with avatar and sign-out
* **Protected Routes**: Automatic redirection for unauthenticated users
* **Loading States**: Proper handling of authentication loading states
* **User Profile Display**: Accessing and displaying user information

## Running the Example

```bash theme={null}
npm run dev
```

Visit `http://localhost:3000` to see the app in action.

## Next Steps

<CardGroup>
  <Card title="Protected Routes" icon="lock" href="/logto-authkit/examples/protected-routes">
    Learn advanced patterns for protecting routes
  </Card>

  <Card title="Next.js Example" icon="react" href="/logto-authkit/examples/nextjs-app">
    See how to use logto-authkit with Next.js
  </Card>
</CardGroup>


# AuthProvider
Source: https://docs.ouim.me/logto-authkit/frontend/auth-provider

The main authentication provider component that wraps your application

## Overview

The `AuthProvider` component is the core wrapper for logto-authkit authentication. It manages authentication state, handles sign-in/sign-out operations, and provides auth context to your entire application.

## Installation

The `AuthProvider` is included in the logto-authkit package:

```bash theme={null}
npm install @ouim/logto-authkit
```

## Basic Usage

Wrap your application with `AuthProvider` at the root level:

```tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'

function App() {
  return (
    <AuthProvider
      config={{
        endpoint: process.env.NEXT_PUBLIC_LOGTO_ENDPOINT!,
        appId: process.env.NEXT_PUBLIC_LOGTO_APP_ID!,
        resources: [process.env.NEXT_PUBLIC_LOGTO_RESOURCE!],
      }}
      callbackUrl="/callback"
    >
      {/* Your app components */}
    </AuthProvider>
  )
}
```

## Props

<ParamField type="LogtoConfig">
  Logto configuration object containing authentication settings.

  <Expandable title="LogtoConfig properties">
    <ParamField type="string">
      Your Logto instance endpoint URL
    </ParamField>

    <ParamField type="string">
      Your Logto application ID
    </ParamField>

    <ParamField type="string[]">
      Array of API resource identifiers
    </ParamField>
  </Expandable>
</ParamField>

<ParamField type="string">
  The URL to redirect to after authentication. Defaults to current page.

  ```tsx theme={null}
  <AuthProvider callbackUrl="/callback" config={config}>
  ```
</ParamField>

<ParamField type="boolean">
  Enable popup-based sign-in instead of full page redirects.

  ```tsx theme={null}
  <AuthProvider enablePopupSignIn={true} config={config}>
  ```
</ParamField>

<ParamField type="(url: string, options?: NavigationOptions) => void">
  Custom navigation function for framework-specific routing (e.g., Next.js router).

  <Expandable title="NavigationOptions">
    <ParamField type="boolean">
      Use replaceState instead of pushState
    </ParamField>

    <ParamField type="boolean">
      Force navigation even if already on the same page
    </ParamField>
  </Expandable>

  ```tsx theme={null}
  import { useRouter } from 'next/router'

  function App() {
    const router = useRouter()
    
    return (
      <AuthProvider
        config={config}
        customNavigate={(url, options) => {
          if (options?.replace) {
            router.replace(url)
          } else {
            router.push(url)
          }
        }}
      >
    )
  }
  ```
</ParamField>

<ParamField type="React.ReactNode">
  Your application components that need access to authentication context.
</ParamField>

## Features

### Automatic State Management

The `AuthProvider` automatically:

* Fetches and updates user information when authentication state changes
* Handles JWT token storage in cookies
* Syncs authentication across browser tabs and windows
* Refreshes auth state on window focus
* Manages loading states during authentication operations

### Popup Sign-In Support

When `enablePopupSignIn` is enabled, sign-in operations open in a popup window instead of redirecting the entire page:

```tsx theme={null}
<AuthProvider config={config} enablePopupSignIn={true} callbackUrl="/callback">
  {children}
</AuthProvider>
```

<Info>Popup sign-in provides a better user experience as it doesn't interrupt the user's current page state.</Info>

### Cross-Tab Synchronization

Authentication state is automatically synchronized across browser tabs:

* Sign in on one tab → all tabs update
* Sign out on one tab → all tabs update
* Uses localStorage events and custom event dispatching

### Error Handling

The provider includes robust error handling:

* Automatic logout on invalid/expired tokens
* Rate limiting to prevent excessive API calls
* Graceful fallback for popup authentication failures

## Advanced Usage

### Next.js App Router

```tsx app/layout.tsx theme={null}
import { AuthProvider } from '@ouim/logto-authkit'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider
          config={{
            endpoint: process.env.NEXT_PUBLIC_LOGTO_ENDPOINT!,
            appId: process.env.NEXT_PUBLIC_LOGTO_APP_ID!,
            resources: [process.env.NEXT_PUBLIC_LOGTO_RESOURCE!],
          }}
          callbackUrl="/callback"
          enablePopupSignIn={true}
        >
          {children}
        </AuthProvider>
      </body>
    </html>
  )
}
```

### With Custom Navigation (Next.js)

```tsx theme={null}
'use client'

import { AuthProvider } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'

export function AuthProviderWrapper({ children }: { children: React.ReactNode }) {
  const router = useRouter()

  return (
    <AuthProvider
      config={{
        endpoint: process.env.NEXT_PUBLIC_LOGTO_ENDPOINT!,
        appId: process.env.NEXT_PUBLIC_LOGTO_APP_ID!,
      }}
      customNavigate={(url, options) => {
        if (options?.replace) {
          router.replace(url)
        } else {
          router.push(url)
        }
      }}
    >
      {children}
    </AuthProvider>
  )
}
```

## Context Value

The `AuthProvider` exposes the following context value (accessible via `useAuth` hook):

```typescript theme={null}
interface AuthContextType {
  user: LogtoUser | null
  isLoadingUser: boolean
  signIn: (callbackUrl?: string, usePopup?: boolean) => Promise<void>
  signOut: (options?: { callbackUrl?: string; global?: boolean }) => Promise<void>
  refreshAuth: () => Promise<void>
  enablePopupSignIn?: boolean
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Place at the root of your application">
    Always wrap your entire application with `AuthProvider` to ensure all components have access to authentication context.
  </Accordion>

  <Accordion title="Use environment variables for config">
    Store sensitive configuration like `endpoint` and `appId` in environment variables, not hardcoded in your source.
  </Accordion>

  <Accordion title="Enable popup sign-in for better UX">
    For better user experience, enable `enablePopupSignIn` to avoid full page redirects during authentication.
  </Accordion>

  <Accordion title="Handle SSR properly">
    The provider includes built-in SSR handling with `ClientOnly` wrapper. No additional configuration needed for Next.js.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<Warning>
  If you see "useAuthContext must be used within an AuthProvider" error, ensure the `AuthProvider` wraps your component tree.
</Warning>

<Check>The provider automatically handles token refresh and manages authentication state across page navigations.</Check>

## Related

<CardGroup>
  <Card title="useAuth Hook" icon="hook" href="/logto-authkit/frontend/use-auth">
    Access authentication state and methods
  </Card>

  <Card title="CallbackPage" icon="arrow-right-to-bracket" href="/logto-authkit/frontend/callback-page">
    Handle authentication callbacks
  </Card>

  <Card title="UserCenter" icon="user" href="/logto-authkit/frontend/user-center">
    Pre-built user menu component
  </Card>

  <Card title="Route Protection" icon="lock" href="/logto-authkit/frontend/route-protection">
    Protect routes and pages
  </Card>
</CardGroup>


# CallbackPage
Source: https://docs.ouim.me/logto-authkit/frontend/callback-page

Component for handling authentication callbacks after Logto redirect

## Overview

The `CallbackPage` component handles the authentication callback after users are redirected back from Logto. It processes the authentication code, exchanges it for tokens, and manages the post-authentication flow including popup and redirect scenarios.

## Installation

```bash theme={null}
npm install @ouim/logto-authkit
```

## Basic Usage

Create a callback route in your application:

```tsx app/callback/page.tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

export default function Callback() {
  return <CallbackPage />
}
```

## Props

<ParamField type="string">
  Additional CSS classes to apply to the container element.

  ```tsx theme={null}
  <CallbackPage className="bg-gray-50" />
  ```
</ParamField>

<ParamField type="React.ReactNode">
  Custom component to display while processing authentication.

  ```tsx theme={null}
  <CallbackPage
    loadingComponent={
      <div className="flex items-center gap-2">
        <Spinner />
        <p>Please wait...</p>
      </div>
    }
  />
  ```
</ParamField>

<ParamField type="React.ReactNode">
  Custom component to display after successful authentication.

  ```tsx theme={null}
  <CallbackPage
    successComponent={
      <div className="text-center">
        <CheckCircle className="text-green-500" />
        <p>Success! Taking you to your dashboard...</p>
      </div>
    }
  />
  ```
</ParamField>

<ParamField type="() => void">
  Callback function executed after successful authentication, before redirect/close.

  ```tsx theme={null}
  <CallbackPage
    onSuccess={() => {
      console.log('Authentication successful!')
      // Track analytics, etc.
    }}
  />
  ```
</ParamField>

<ParamField type="(error: Error) => void">
  Callback function executed if authentication fails.

  ```tsx theme={null}
  <CallbackPage
    onError={error => {
      console.error('Auth failed:', error)
      // Show error message, redirect to error page, etc.
    }}
  />
  ```
</ParamField>

## How It Works

The `CallbackPage` component:

1. **Receives the auth code** from Logto redirect URL
2. **Exchanges code for tokens** using `useHandleSignInCallback()` from `@logto/react`
3. **Detects the flow type** (popup vs. redirect)
4. **Handles completion**:
   * **Popup flow**: Sends message to parent window and closes
   * **Redirect flow**: Redirects to home page (`/`)

## Flow Detection

The component automatically detects whether it's handling a popup or redirect flow:

```typescript theme={null}
const isPopup = (window.opener && window.opener !== window) || sessionStorage.getItem('simple_logto_popup_flow') === 'true'
```

* Checks if the window has an `opener` (parent window)
* Falls back to `sessionStorage` flag for cross-origin scenarios

## Popup Flow

For popup-based authentication:

1. Component detects it's in a popup
2. Processes authentication
3. Sends `SIGNIN_SUCCESS` message to parent window
4. Closes the popup

```typescript theme={null}
// Sends message to parent
window.opener.postMessage({ type: 'SIGNIN_SUCCESS' }, window.location.origin)

// Closes popup after small delay
setTimeout(() => {
  window.close()
}, 100)
```

### Fallback Mechanism

If `window.opener` is unavailable (some browsers clear it), falls back to localStorage:

```typescript theme={null}
localStorage.setItem('simple_logto_signin_complete', Date.now().toString())
```

<Info>The parent window listens for both `postMessage` and `localStorage` events to handle popup completion.</Info>

## Redirect Flow

For full-page redirect authentication:

1. Component detects it's NOT in a popup
2. Processes authentication
3. Redirects to home page (`/`)

```typescript theme={null}
if (!isPopup) {
  window.location.href = '/'
}
```

## Examples

### Basic Setup (Next.js App Router)

```tsx app/callback/page.tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

export default function Callback() {
  return <CallbackPage />
}
```

### With Custom Loading State

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'
import { Loader2 } from 'lucide-react'

export default function Callback() {
  return (
    <CallbackPage
      loadingComponent={
        <div className="flex flex-col items-center gap-4">
          <Loader2 className="h-8 w-8 animate-spin text-blue-500" />
          <p className="text-lg font-medium">Signing you in...</p>
          <p className="text-sm text-gray-500">Please wait a moment</p>
        </div>
      }
    />
  )
}
```

### With Success Tracking

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'

export default function Callback() {
  const router = useRouter()

  return (
    <CallbackPage
      onSuccess={() => {
        // Track successful authentication
        if (typeof window !== 'undefined' && window.analytics) {
          window.analytics.track('User Signed In', {
            method: 'logto',
            timestamp: new Date().toISOString(),
          })
        }
      }}
      onError={error => {
        console.error('Authentication error:', error)
        // Redirect to error page
        router.push('/auth/error')
      }}
    />
  )
}
```

### Custom Styling

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

export default function Callback() {
  return (
    <div className="min-h-screen bg-gradient-to-br from-blue-500 to-purple-600">
      <CallbackPage
        className="flex items-center justify-center min-h-screen"
        loadingComponent={
          <div className="bg-white rounded-lg shadow-xl p-8">
            <div className="flex items-center gap-3">
              <div className="animate-spin rounded-full h-6 w-6 border-b-2 border-blue-500" />
              <p className="text-gray-700">Authenticating...</p>
            </div>
          </div>
        }
      />
    </div>
  )
}
```

### With Custom Redirect

```tsx theme={null}
import { CallbackPage } from '@ouim/logto-authkit'

export default function Callback() {
  return (
    <CallbackPage
      onSuccess={() => {
        // Check if this is popup flow
        const isPopup = (window.opener && window.opener !== window) || sessionStorage.getItem('simple_logto_popup_flow') === 'true'

        if (!isPopup) {
          // Custom redirect for non-popup flow
          window.location.href = '/dashboard'
        }
      }}
    />
  )
}
```

## Default UI

If no custom components are provided, the callback page displays:

### Loading State

```tsx theme={null}
<div className="flex items-center gap-2">
  <Spinner /> {/* Animated spinner */}
  <div className="text-lg text-slate-500">Signing you in...</div>
</div>
```

### Success State

```tsx theme={null}
<div className="flex items-center gap-2">
  <Spinner />
  <div className="text-lg text-slate-500">Authentication complete! Redirecting...</div>
</div>
```

## Session Storage Flag

For popup flows, your sign-in page should set a flag:

```tsx app/signin/page.tsx theme={null}
'use client'

import { useEffect } from 'react'
import { useAuth } from '@ouim/logto-authkit'
import { useSearchParams } from 'next/navigation'

export default function SignIn() {
  const { signIn } = useAuth()
  const searchParams = useSearchParams()
  const isPopup = searchParams.get('popup') === 'true'

  useEffect(() => {
    if (isPopup) {
      sessionStorage.setItem('simple_logto_popup_flow', 'true')
    }
    signIn('/callback')
  }, [signIn, isPopup])

  return <div>Redirecting to sign in...</div>
}
```

## Error Handling

The component handles errors during authentication:

```typescript theme={null}
try {
  // Process authentication
} catch (error) {
  console.error('Authentication callback error:', error)
  if (onError) {
    onError(error as Error)
  }
}
```

Common errors:

* Invalid authorization code
* Token exchange failure
* Network errors
* CORS issues

## Best Practices

<AccordionGroup>
  <Accordion title="Create a dedicated route">
    Always use a dedicated route like `/callback` or `/auth/callback` for handling authentication callbacks.
  </Accordion>

  <Accordion title="Configure Logto redirect URI">
    Make sure your Logto application's redirect URI matches your callback route exactly.
  </Accordion>

  <Accordion title="Handle both flows">
    The component automatically handles both popup and redirect flows - no additional configuration needed.
  </Accordion>

  <Accordion title="Add error tracking">Use the `onError` callback to track authentication failures in your monitoring system.</Accordion>

  <Accordion title="Customize user experience">
    Provide custom loading and success components that match your application's design.
  </Accordion>
</AccordionGroup>

## Configuration in Logto

In your Logto application settings, add your callback URL:

```
https://yourdomain.com/callback
```

For local development:

```
http://localhost:3000/callback
```

## Troubleshooting

<Warning>
  **Popup doesn't close**: Ensure your sign-in page sets the `simple_logto_popup_flow` sessionStorage flag when `?popup=true` is in the URL.
</Warning>

<Warning>**Infinite redirect loop**: Check that your Logto redirect URI exactly matches your callback route.</Warning>

<Warning>**CORS errors**: Ensure your Logto application's allowed origins include your application's domain.</Warning>

<Check>The component automatically cleans up the `simple_logto_popup_flow` flag after successful authentication.</Check>

## Related

<CardGroup>
  <Card title="AuthProvider" icon="shield-check" href="/logto-authkit/frontend/auth-provider">
    Configure authentication provider
  </Card>

  <Card title="useAuth Hook" icon="hook" href="/logto-authkit/frontend/use-auth">
    Access sign-in functionality
  </Card>

  <Card title="UserCenter" icon="user" href="/logto-authkit/frontend/user-center">
    User menu with sign-in button
  </Card>

  <Card title="Route Protection" icon="lock" href="/logto-authkit/frontend/route-protection">
    Protect authenticated routes
  </Card>
</CardGroup>


# Route Protection
Source: https://docs.ouim.me/logto-authkit/frontend/route-protection

Patterns and best practices for protecting routes and pages

## Overview

Route protection ensures that certain pages are only accessible to authenticated users, while others are restricted to guests. logto-authkit provides multiple patterns for implementing route protection.

## Protection Methods

There are three main approaches to route protection:

1. **Middleware option in `useAuth` hook** (recommended)
2. **Manual checks with conditional rendering**
3. **Higher-order components (HOC)**

## Method 1: Middleware Option (Recommended)

The simplest and most declarative approach using the `useAuth` hook's built-in middleware.

### Protected Route (Auth Required)

```tsx app/dashboard/page.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

export default function DashboardPage() {
  const { user } = useAuth({
    middleware: 'auth',
    redirectTo: '/login'
  })
  
  // This will only render if user is authenticated
  // Otherwise, automatically redirects to '/login'
  return (
    <div>
      <h1>Dashboard</h1>
      <p>Welcome, {user?.name}!</p>
    </div>
  )
}
```

### Guest-Only Route

```tsx app/login/page.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

export default function LoginPage() {
  const { signIn } = useAuth({
    middleware: 'guest',
    redirectIfAuthenticated: '/dashboard'
  })
  
  // This will only render if user is NOT authenticated
  // Otherwise, automatically redirects to '/dashboard'
  return (
    <div>
      <h1>Sign In</h1>
      <button onClick={() => signIn()}>Sign In</button>
    </div>
  )
}
```

## Method 2: Manual Checks

For more control over the protection logic and UI.

### With Loading and Redirect

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'
import { useEffect } from 'react'

export default function ProtectedPage() {
  const { user, isLoadingUser } = useAuth()
  const router = useRouter()
  
  useEffect(() => {
    if (!isLoadingUser && !user) {
      router.push('/login')
    }
  }, [user, isLoadingUser, router])
  
  if (isLoadingUser) {
    return <div>Loading...</div>
  }
  
  if (!user) {
    return null // or return <div>Redirecting...</div>
  }
  
  return (
    <div>
      <h1>Protected Content</h1>
      <p>Only authenticated users see this</p>
    </div>
  )
}
```

### With Error Message

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

export default function ProtectedPage() {
  const { user, isLoadingUser, signIn } = useAuth()
  
  if (isLoadingUser) {
    return (
      <div className="flex items-center justify-center min-h-screen">
        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-500" />
      </div>
    )
  }
  
  if (!user) {
    return (
      <div className="flex flex-col items-center justify-center min-h-screen gap-4">
        <h1 className="text-2xl font-bold">Authentication Required</h1>
        <p className="text-gray-600">Please sign in to access this page</p>
        <button
          onClick={() => signIn()}
          className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
        >
          Sign In
        </button>
      </div>
    )
  }
  
  return (
    <div>
      <h1>Protected Content</h1>
    </div>
  )
}
```

## Method 3: Higher-Order Component

Create reusable protection wrappers.

### Protected Page HOC

```tsx lib/withAuth.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'
import { useEffect, ComponentType } from 'react'

export function withAuth<P extends object>(
  Component: ComponentType<P>,
  redirectTo: string = '/login'
) {
  return function ProtectedComponent(props: P) {
    const { user, isLoadingUser } = useAuth()
    const router = useRouter()
    
    useEffect(() => {
      if (!isLoadingUser && !user) {
        router.push(redirectTo)
      }
    }, [user, isLoadingUser, router])
    
    if (isLoadingUser) {
      return (
        <div className="flex items-center justify-center min-h-screen">
          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-500" />
        </div>
      )
    }
    
    if (!user) {
      return null
    }
    
    return <Component {...props} />
  }
}

// Usage
import { withAuth } from '@/lib/withAuth'

function DashboardPage() {
  return <div>Dashboard Content</div>
}

export default withAuth(DashboardPage)
```

### Guest-Only HOC

```tsx lib/withGuest.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'
import { useEffect, ComponentType } from 'react'

export function withGuest<P extends object>(
  Component: ComponentType<P>,
  redirectTo: string = '/dashboard'
) {
  return function GuestComponent(props: P) {
    const { user, isLoadingUser } = useAuth()
    const router = useRouter()
    
    useEffect(() => {
      if (!isLoadingUser && user) {
        router.push(redirectTo)
      }
    }, [user, isLoadingUser, router])
    
    if (isLoadingUser) {
      return (
        <div className="flex items-center justify-center min-h-screen">
          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-500" />
        </div>
      )
    }
    
    if (user) {
      return null
    }
    
    return <Component {...props} />
  }
}

// Usage
import { withGuest } from '@/lib/withGuest'

function LoginPage() {
  return <div>Login Content</div>
}

export default withGuest(LoginPage)
```

## Advanced Patterns

### Role-Based Protection

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'
import { useRouter } from 'next/navigation'
import { useEffect } from 'react'

export default function AdminPage() {
  const { user, isLoadingUser } = useAuth({
    middleware: 'auth',
    redirectTo: '/login'
  })
  const router = useRouter()
  
  useEffect(() => {
    if (!isLoadingUser && user && user.role !== 'admin') {
      router.push('/unauthorized')
    }
  }, [user, isLoadingUser, router])
  
  if (isLoadingUser) {
    return <div>Loading...</div>
  }
  
  if (!user || user.role !== 'admin') {
    return null
  }
  
  return (
    <div>
      <h1>Admin Dashboard</h1>
      <p>Admin-only content</p>
    </div>
  )
}
```

### Permission-Based Protection

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function hasPermission(user: any, permission: string): boolean {
  return user?.permissions?.includes(permission) ?? false
}

export default function SettingsPage() {
  const { user, isLoadingUser } = useAuth({
    middleware: 'auth',
    redirectTo: '/login'
  })
  
  if (isLoadingUser) {
    return <div>Loading...</div>
  }
  
  const canEditSettings = hasPermission(user, 'settings:write')
  const canViewSettings = hasPermission(user, 'settings:read')
  
  if (!canViewSettings) {
    return (
      <div>
        <h1>Access Denied</h1>
        <p>You don't have permission to view settings</p>
      </div>
    )
  }
  
  return (
    <div>
      <h1>Settings</h1>
      {canEditSettings ? (
        <button>Edit Settings</button>
      ) : (
        <p>Read-only view</p>
      )}
    </div>
  )
}
```

### Conditional Component Rendering

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function ProtectedSection({ children }: { children: React.ReactNode }) {
  const { user, isLoadingUser } = useAuth()
  
  if (isLoadingUser) {
    return <div>Loading...</div>
  }
  
  if (!user) {
    return null // Don't render anything
  }
  
  return <>{children}</>
}

// Usage
export default function Page() {
  return (
    <div>
      <h1>Public Content</h1>
      <p>Everyone can see this</p>
      
      <ProtectedSection>
        <h2>Members Only</h2>
        <p>Only authenticated users see this section</p>
      </ProtectedSection>
    </div>
  )
}
```

### Layout-Level Protection

```tsx app/dashboard/layout.tsx theme={null}
'use client'

import { useAuth } from '@ouim/logto-authkit'

export default function DashboardLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const { user, isLoadingUser } = useAuth({
    middleware: 'auth',
    redirectTo: '/login'
  })
  
  if (isLoadingUser) {
    return (
      <div className="flex items-center justify-center min-h-screen">
        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-500" />
      </div>
    )
  }
  
  return (
    <div className="flex">
      <aside className="w-64 bg-gray-100">
        <nav>
          <a href="/dashboard">Dashboard</a>
          <a href="/dashboard/profile">Profile</a>
          <a href="/dashboard/settings">Settings</a>
        </nav>
      </aside>
      <main className="flex-1">
        {children}
      </main>
    </div>
  )
}
```

## Navigation Options

Control how redirects behave:

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

export default function Page() {
  const { user } = useAuth({
    middleware: 'auth',
    redirectTo: '/login',
    navigationOptions: {
      replace: true, // Replace history instead of push
      force: true    // Force navigation even if on same page
    }
  })
  
  return <div>Protected content</div>
}
```

## Server-Side Protection (Next.js)

For server components and API routes:

```tsx app/api/protected/route.ts theme={null}
import { cookies } from 'next/headers'
import { NextResponse } from 'next/server'

export async function GET() {
  const cookieStore = cookies()
  const token = cookieStore.get('logto_access_token')
  
  if (!token) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    )
  }
  
  // Verify token and proceed
  return NextResponse.json({ data: 'Protected data' })
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use middleware option for simple cases">
    The `middleware` option in `useAuth` is the simplest and most declarative way to protect routes.
  </Accordion>

  <Accordion title="Always handle loading state">
    Show a loading indicator while `isLoadingUser` is `true` to prevent UI flashing.
  </Accordion>

  <Accordion title="Protect at the layout level when possible">
    For sections with multiple protected pages, protect the layout instead of each page individually.
  </Accordion>

  <Accordion title="Provide clear feedback">
    When access is denied, show a clear message and provide a way to authenticate.
  </Accordion>

  <Accordion title="Use HOCs for consistent behavior">
    Create reusable HOCs to ensure consistent protection logic across your app.
  </Accordion>

  <Accordion title="Combine client and server protection">
    For sensitive data, protect both the UI (client) and API routes (server).
  </Accordion>
</AccordionGroup>

## Common Patterns Summary

| Pattern               | Use Case               | Complexity |
| --------------------- | ---------------------- | ---------- |
| `middleware: 'auth'`  | Require authentication | Low        |
| `middleware: 'guest'` | Guest-only pages       | Low        |
| Manual checks         | Custom logic needed    | Medium     |
| HOC                   | Reusable protection    | Medium     |
| Role-based            | Multiple user types    | High       |
| Permission-based      | Fine-grained access    | High       |

## Troubleshooting

<Warning>
  **Infinite redirect loop**: Ensure `redirectTo` and `redirectIfAuthenticated` point to pages with different middleware settings.
</Warning>

<Warning>
  **Flash of unauthenticated content**: Always check `isLoadingUser` before rendering protected content.
</Warning>

<Check>
  The `useAuth` hook waits for loading to complete before performing middleware redirects, preventing race conditions.
</Check>

## Related

<CardGroup>
  <Card title="useAuth Hook" icon="code" href="/logto-authkit/frontend/use-auth">
    Complete hook documentation
  </Card>

  <Card title="AuthProvider" icon="shield-check" href="/logto-authkit/frontend/auth-provider">
    Configure authentication provider
  </Card>

  <Card title="UserCenter" icon="user" href="/logto-authkit/frontend/user-center">
    Pre-built user menu component
  </Card>

  <Card title="CallbackPage" icon="arrow-right-to-bracket" href="/logto-authkit/frontend/callback-page">
    Handle authentication callbacks
  </Card>
</CardGroup>


# useAuth
Source: https://docs.ouim.me/logto-authkit/frontend/use-auth

React hook for accessing authentication state and methods

## Overview

The `useAuth` hook provides access to the current user's authentication state and authentication methods. It also supports middleware for route protection and automatic redirects.

## Installation

```bash theme={null}
npm install @ouim/logto-authkit
```

## Basic Usage

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function MyComponent() {
  const { user, isLoadingUser, signIn, signOut } = useAuth()

  if (isLoadingUser) {
    return <div>Loading...</div>
  }

  if (user) {
    return (
      <div>
        <p>Welcome, {user.name}!</p>
        <button onClick={() => signOut()}>Sign Out</button>
      </div>
    )
  }

  return <button onClick={() => signIn()}>Sign In</button>
}
```

## Parameters

The hook accepts an optional `options` object:

<ParamField type="AuthOptions">
  Configuration object for authentication behavior and route protection.

  <Expandable title="AuthOptions properties">
    <ParamField type="'auth' | 'guest' | undefined">
      Route protection middleware type:

      * `'auth'`: Requires authentication (redirects unauthenticated users)
      * `'guest'`: Guest-only route (redirects authenticated users)
      * `undefined`: No protection

      ```tsx theme={null}
      const { user } = useAuth({ middleware: 'auth' })
      ```
    </ParamField>

    <ParamField type="string">
      URL to redirect to when `middleware: 'auth'` and user is not authenticated.

      ```tsx theme={null}
      const { user } = useAuth({
        middleware: 'auth',
        redirectTo: '/login'
      })
      ```
    </ParamField>

    <ParamField type="string">
      URL to redirect to when `middleware: 'guest'` and user is authenticated.

      ```tsx theme={null}
      const { user } = useAuth({
        middleware: 'guest',
        redirectIfAuthenticated: '/dashboard'
      })
      ```
    </ParamField>

    <ParamField type="NavigationOptions">
      Options for navigation behavior.

      <Expandable title="NavigationOptions properties">
        <ParamField type="boolean">
          Use replaceState instead of pushState
        </ParamField>

        <ParamField type="boolean">
          Force navigation even if already on the same page
        </ParamField>
      </Expandable>

      ```tsx theme={null}
      const { user } = useAuth({
        middleware: 'auth',
        redirectTo: '/login',
        navigationOptions: { replace: true }
      })
      ```
    </ParamField>
  </Expandable>
</ParamField>

## Return Value

The hook returns an `AuthContextType` object:

```typescript theme={null}
interface AuthContextType {
  user: LogtoUser | null
  isLoadingUser: boolean
  signIn: (callbackUrl?: string, usePopup?: boolean) => Promise<void>
  signOut: (options?: { callbackUrl?: string; global?: boolean }) => Promise<void>
  refreshAuth: () => Promise<void>
  enablePopupSignIn?: boolean
}
```

<ParamField type="LogtoUser | null">
  Current authenticated user object, or `null` if not authenticated.

  ```typescript theme={null}
  type LogtoUser = {
    id: string
    name?: string
    email?: string
    avatar?: string
    [key: string]: any
  }
  ```
</ParamField>

<ParamField type="boolean">
  Loading state indicator. `true` while fetching user data, `false` when complete.
</ParamField>

<ParamField type="(callbackUrl?: string, usePopup?: boolean) => Promise<void>">
  Function to initiate sign-in flow. - `callbackUrl`: Optional URL to redirect to after authentication - `usePopup`: Override the
  `enablePopupSignIn` setting from `AuthProvider` `tsx // Default sign-in await signIn() // With custom callback URL await
      signIn('/dashboard') // Force popup mode await signIn('/callback', true) // Force redirect mode await signIn('/callback', false) `
</ParamField>

<ParamField type="(options?: { callbackUrl?: string; global?: boolean }) => Promise<void>">
  Function to sign out the current user.

  * `callbackUrl`: Optional URL to redirect to after sign-out
  * `global`: Whether to perform global sign-out (default: `true`)

  ```tsx theme={null}
  // Default global sign-out
  await signOut()

  // With custom redirect
  await signOut({ callbackUrl: '/goodbye' })

  // Local sign-out only
  await signOut({ global: false })

  // Local sign-out with redirect
  await signOut({ callbackUrl: '/login', global: false })
  ```
</ParamField>

<ParamField type="() => Promise<void>">
  Function to manually refresh the authentication state. `tsx // Refresh user data await refreshAuth() `
</ParamField>

<ParamField type="boolean | undefined">
  Whether popup sign-in is enabled (from `AuthProvider` configuration).
</ParamField>

## Examples

### Display User Information

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function UserProfile() {
  const { user, isLoadingUser } = useAuth()

  if (isLoadingUser) {
    return <div>Loading user...</div>
  }

  if (!user) {
    return <div>Please sign in</div>
  }

  return (
    <div>
      <img src={user.avatar} alt={user.name} />
      <h2>{user.name}</h2>
      <p>{user.email}</p>
      <p>User ID: {user.id}</p>
    </div>
  )
}
```

### Protected Page

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

export default function DashboardPage() {
  const { user } = useAuth({
    middleware: 'auth',
    redirectTo: '/login',
  })

  // No need to check if user exists - middleware handles it
  return (
    <div>
      <h1>Dashboard</h1>
      <p>Welcome, {user?.name}!</p>
    </div>
  )
}
```

### Guest-Only Page

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

export default function LoginPage() {
  const { signIn } = useAuth({
    middleware: 'guest',
    redirectIfAuthenticated: '/dashboard',
  })

  return (
    <div>
      <h1>Sign In</h1>
      <button onClick={() => signIn()}>Sign in with Logto</button>
    </div>
  )
}
```

### Custom Sign-In Button

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function SignInButton() {
  const { signIn, isLoadingUser } = useAuth()

  return (
    <button
      onClick={() => signIn('/dashboard', true)} // Use popup
      disabled={isLoadingUser}
    >
      {isLoadingUser ? 'Loading...' : 'Sign In'}
    </button>
  )
}
```

### Sign-Out with Confirmation

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function SignOutButton() {
  const { signOut } = useAuth()

  const handleSignOut = async () => {
    if (confirm('Are you sure you want to sign out?')) {
      await signOut({ callbackUrl: '/' })
    }
  }

  return <button onClick={handleSignOut}>Sign Out</button>
}
```

### Conditional Rendering

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function Navigation() {
  const { user, signIn, signOut } = useAuth()

  return (
    <nav>
      <a href="/">Home</a>
      {user ? (
        <>
          <a href="/dashboard">Dashboard</a>
          <a href="/profile">Profile</a>
          <button onClick={() => signOut()}>Sign Out</button>
        </>
      ) : (
        <button onClick={() => signIn()}>Sign In</button>
      )}
    </nav>
  )
}
```

### Manual Auth Refresh

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function ProfilePage() {
  const { user, refreshAuth } = useAuth({ middleware: 'auth' })

  const handleProfileUpdate = async () => {
    // Update profile via API
    await updateProfile({ name: 'New Name' })

    // Refresh auth state to get updated user data
    await refreshAuth()
  }

  return (
    <div>
      <h1>{user?.name}</h1>
      <button onClick={handleProfileUpdate}>Update Profile</button>
    </div>
  )
}
```

### With Loading State

```tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function App() {
  const { user, isLoadingUser, signIn, signOut } = useAuth()

  return (
    <div>
      {isLoadingUser ? (
        <div className="flex items-center justify-center min-h-screen">
          <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-500" />
        </div>
      ) : user ? (
        <Dashboard user={user} onSignOut={signOut} />
      ) : (
        <LandingPage onSignIn={signIn} />
      )}
    </div>
  )
}
```

## Middleware Behavior

### `middleware: 'auth'`

Protects routes that require authentication:

```tsx theme={null}
const { user } = useAuth({
  middleware: 'auth',
  redirectTo: '/login',
})

// If user is NOT authenticated → redirects to '/login'
// If user IS authenticated → renders normally
```

### `middleware: 'guest'`

Protects routes that should only be accessible to unauthenticated users:

```tsx theme={null}
const { user } = useAuth({
  middleware: 'guest',
  redirectIfAuthenticated: '/dashboard',
})

// If user IS authenticated → redirects to '/dashboard'
// If user is NOT authenticated → renders normally
```

### No Middleware

```tsx theme={null}
const { user } = useAuth()

// No automatic redirects
// Manually check user state and handle accordingly
```

## SSR Considerations

<Info>
  The hook waits for client-side mounting and `isLoadingUser` to be `false` before performing middleware redirects, preventing hydration
  mismatches.
</Info>

```tsx theme={null}
useEffect(() => {
  if (isLoadingUser) return // Wait for loading to complete

  // Perform middleware checks and redirects
}, [user, isLoadingUser, memoizedOptions])
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use middleware for route protection">
    Instead of manually checking `user` and redirecting, use the built-in `middleware` option for cleaner code.
  </Accordion>

  <Accordion title="Always check loading state">
    Always handle the `isLoadingUser` state to prevent UI flashing and provide better UX.
  </Accordion>

  <Accordion title="Memoize options object">
    The hook internally memoizes options, but you can also wrap your options in `useMemo` if they depend on other state.
  </Accordion>

  <Accordion title="Handle sign-out errors">Wrap `signOut` calls in try-catch blocks to handle potential errors gracefully.</Accordion>
</AccordionGroup>

## TypeScript Support

The hook is fully typed:

```typescript theme={null}
import { useAuth, type AuthOptions, type AuthContextType } from '@ouim/logto-authkit'

const options: AuthOptions = {
  middleware: 'auth',
  redirectTo: '/login',
}

const auth: AuthContextType = useAuth(options)
```

## Troubleshooting

<Warning>**"useAuthContext must be used within an AuthProvider"**: Ensure your component is wrapped with `AuthProvider`.</Warning>

<Warning>
  **Infinite redirect loop**: Check that `redirectTo` and `redirectIfAuthenticated` point to different routes and don't conflict.
</Warning>

<Check>
  The hook automatically refreshes auth state when: - Window regains focus - Storage events occur (cross-tab sync) - Custom
  `auth-state-changed` events are dispatched
</Check>

## Related

<CardGroup>
  <Card title="AuthProvider" icon="shield-check" href="/logto-authkit/frontend/auth-provider">
    Configure authentication provider
  </Card>

  <Card title="Route Protection" icon="lock" href="/logto-authkit/frontend/route-protection">
    Advanced route protection patterns
  </Card>

  <Card title="UserCenter" icon="user" href="/logto-authkit/frontend/user-center">
    Pre-built user menu component
  </Card>

  <Card title="CallbackPage" icon="arrow-right-to-bracket" href="/logto-authkit/frontend/callback-page">
    Handle authentication callbacks
  </Card>
</CardGroup>


# UserCenter
Source: https://docs.ouim.me/logto-authkit/frontend/user-center

Pre-built dropdown user menu component with sign-in/sign-out functionality

## Overview

The `UserCenter` component is a ready-to-use dropdown menu that displays user information and provides authentication controls. It automatically adapts based on authentication state, showing either a sign-in button or user profile menu.

## Installation

```bash theme={null}
npm install @ouim/logto-authkit
```

## Basic Usage

```tsx theme={null}
import { UserCenter } from '@ouim/logto-authkit'

function Header() {
  return (
    <header>
      <nav>
        {/* Your navigation items */}
        <UserCenter />
      </nav>
    </header>
  )
}
```

## Props

<ParamField type="string">
  Additional CSS classes to apply to the avatar element. \`\`\`tsx

  <UserCenter />

  ````
  </ParamField>

  <ParamField path="globalSignOut" type="boolean" default="true">
  Whether to perform a global sign-out (logs out from entire Logto ecosystem) or local-only sign-out. ```tsx
  <UserCenter globalSignOut={false} />
  ````
</ParamField>

<ParamField type="string">
  URL to redirect to after sign-out. Defaults to current page. \`\`\`tsx

  <UserCenter />

  ````
  </ParamField>

  <ParamField path="themeClassnames" type="string" default="dark:bg-[#171717] dark:text-slate-200 bg-white text-slate-900">
  Custom theme classes for the dropdown menu styling. ```tsx
  <UserCenter themeClassnames="bg-gray-800 text-white" />
  ````
</ParamField>

<ParamField type="AdditionalPage[]">
  Additional menu items to show in the dropdown before the sign-out button.

  <Expandable title="AdditionalPage type">
    ```typescript theme={null}
    interface AdditionalPage {
      link: string      // URL to navigate to
      text: string      // Display text for the menu item
      icon?: React.ReactNode  // Optional icon component
    }
    ```
  </Expandable>

  ```tsx theme={null}
  import { Settings, CreditCard } from 'lucide-react'

  <UserCenter
    additionalPages={[
      {
        link: '/settings',
        text: 'Settings',
        icon: <Settings />
      },
      {
        link: '/billing',
        text: 'Billing',
        icon: <CreditCard />
      }
    ]}
  />
  ```
</ParamField>

## States

### Loading State

While authentication state is loading, displays a pulsing skeleton:

```tsx theme={null}
<div className="h-8 w-8 rounded-full bg-slate-100 animate-pulse" />
```

### Authenticated State

When a user is signed in, shows:

* User avatar (if available) or initials
* Dropdown menu with:
  * User name and email
  * Additional custom pages (if configured)
  * Sign out button

### Unauthenticated State

When no user is signed in, shows:

* Generic user icon
* Dropdown menu with sign-in button

## Examples

### Basic Implementation

```tsx theme={null}
import { UserCenter } from '@ouim/logto-authkit'

export default function Header() {
  return (
    <header className="flex items-center justify-between p-4">
      <h1>My App</h1>
      <UserCenter />
    </header>
  )
}
```

### With Custom Pages

```tsx theme={null}
import { UserCenter } from '@ouim/logto-authkit'
import { Settings, User, CreditCard } from 'lucide-react'

export default function Navigation() {
  return (
    <nav className="flex items-center gap-4">
      <UserCenter
        additionalPages={[
          {
            link: '/profile',
            text: 'Profile',
            icon: <User className="h-4 w-4" />,
          },
          {
            link: '/settings',
            text: 'Settings',
            icon: <Settings className="h-4 w-4" />,
          },
          {
            link: '/billing',
            text: 'Billing',
            icon: <CreditCard className="h-4 w-4" />,
          },
        ]}
      />
    </nav>
  )
}
```

### Custom Styling

```tsx theme={null}
import { UserCenter } from '@ouim/logto-authkit'

export default function ThemedHeader() {
  return (
    <header className="bg-slate-900">
      <UserCenter className="ring-2 ring-blue-500" themeClassnames="bg-slate-800 text-white border-slate-700" />
    </header>
  )
}
```

### Local Sign-Out Only

```tsx theme={null}
import { UserCenter } from '@ouim/logto-authkit'

export default function Header() {
  return (
    <header>
      <UserCenter globalSignOut={false} signoutCallbackUrl="/login" />
    </header>
  )
}
```

## User Data Display

The component automatically displays:

* **User Avatar**: If `user.avatar` exists, shows the avatar image
* **User Initials**: If no avatar, generates initials from `user.name`
* **User Name**: Displays as the main label in the dropdown
* **User Email**: Shows below the name in a smaller, muted text

```typescript theme={null}
// User object structure
interface LogtoUser {
  id: string
  name?: string
  email?: string
  avatar?: string
  [key: string]: any
}
```

## Behavior

### Sign-In Flow

1. User clicks on the guest avatar
2. Dropdown shows "Sign in to your account"
3. Click "Sign in" button
4. Triggers `signIn()` from `useAuth` hook
5. Redirects to Logto authentication

### Sign-Out Flow

1. User clicks "Sign out" button
2. Calls `signOut({ callbackUrl, global })` from `useAuth` hook
3. If `globalSignOut={true}`: Logs out from entire Logto ecosystem
4. If `globalSignOut={false}`: Only clears local session
5. Redirects to `signoutCallbackUrl` or current page

## Customization

### Custom Icons

You can use any icon library with `additionalPages`:

```tsx theme={null}
import { UserCenter } from '@ouim/logto-authkit'
import { IoSettingsOutline, IoCreditCardOutline } from 'react-icons/io5'

;<UserCenter
  additionalPages={[
    {
      link: '/settings',
      text: 'Settings',
      icon: <IoSettingsOutline />,
    },
    {
      link: '/billing',
      text: 'Billing',
      icon: <IoCreditCardOutline />,
    },
  ]}
/>
```

### Dark Mode Support

The default theme classes support dark mode:

```tsx theme={null}
// Default theme
themeClassnames = 'dark:bg-[#171717] dark:text-slate-200 bg-white text-slate-900'
```

Customize for your design system:

```tsx theme={null}
<UserCenter
  themeClassnames="
    dark:bg-gray-900 dark:text-gray-100 dark:border-gray-700
    bg-white text-gray-900 border-gray-200
  "
/>
```

## SSR Considerations

<Info>
  The component includes built-in SSR handling to prevent hydration mismatches. It waits for client-side mounting before rendering
  user-specific content.
</Info>

```tsx theme={null}
// Internal handling
const [hasMounted, setHasMounted] = useState(false)

useEffect(() => {
  setHasMounted(true)
}, [])

if (!hasMounted || isLoadingUser) {
  return <LoadingSkeleton />
}
```

## Dependencies

The component requires these shadcn/ui components:

* `Avatar`, `AvatarFallback`, `AvatarImage`
* `DropdownMenu` family
* `Button`

Icons from `lucide-react`:

* `User`
* `LogOut`
* `UserCircle`

## Best Practices

<AccordionGroup>
  <Accordion title="Always wrap with AuthProvider">
    Ensure `UserCenter` is used within an `AuthProvider` to access authentication context.
  </Accordion>

  <Accordion title="Configure sign-out redirect">Set `signoutCallbackUrl` to control where users land after signing out.</Accordion>

  <Accordion title="Use global sign-out for security">
    Keep `globalSignOut={true}` (default) for better security, clearing all sessions across devices.
  </Accordion>

  <Accordion title="Add relevant pages">
    Use `additionalPages` to provide quick access to user-related pages like settings, profile, and billing.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<Warning>
  If the component doesn't show user information after sign-in, ensure the `AuthProvider` is properly configured and wrapping your app.
</Warning>

<Warning>For popup sign-in, make sure your `/signin` page properly handles the `?popup=true` query parameter.</Warning>

## Related

<CardGroup>
  <Card title="AuthProvider" icon="shield-check" href="/logto-authkit/frontend/auth-provider">
    Main authentication provider
  </Card>

  <Card title="useAuth Hook" icon="hook" href="/logto-authkit/frontend/use-auth">
    Access authentication in any component
  </Card>

  <Card title="CallbackPage" icon="arrow-right-to-bracket" href="/logto-authkit/frontend/callback-page">
    Handle authentication callbacks
  </Card>

  <Card title="Route Protection" icon="lock" href="/logto-authkit/frontend/route-protection">
    Protect routes from unauthorized access
  </Card>
</CardGroup>


# Installation
Source: https://docs.ouim.me/logto-authkit/installation

Install logto-authkit using your preferred package manager

# Installation

logto-authkit is available as a single npm package that includes both frontend and server features.

## Install the package

<CodeGroup>
  ```bash npm theme={null}
  npm install @ouim/logto-authkit
  ```

  ```bash yarn theme={null}
  yarn add @ouim/logto-authkit
  ```

  ```bash pnpm theme={null}
  pnpm add @ouim/logto-authkit
  ```
</CodeGroup>

## Peer dependencies

logto-authkit requires the following peer dependencies for frontend features:

* `@logto/react` - ^3.0.0 || ^4.0.0
* `react` - ^17.0.0 || ^19.0.0
* `react-dom` - ^17.0.0 || ^19.0.0

These should be installed automatically by your package manager, but if not, install them manually:

<CodeGroup>
  ```bash npm theme={null}
  npm install @logto/react react react-dom
  ```

  ```bash yarn theme={null}
  yarn add @logto/react react react-dom
  ```

  ```bash pnpm theme={null}
  pnpm add @logto/react react react-dom
  ```
</CodeGroup>

<Note>
  Server features work independently and don't require React dependencies.
</Note>

## Package exports

logto-authkit provides three main exports:

### Main entry (frontend)

```typescript theme={null}
import { AuthProvider, useAuth, UserCenter, CallbackPage } from '@ouim/logto-authkit'
```

Includes all frontend components and hooks for React applications.

### Server entry

```typescript theme={null}
import { verifyAuth, createExpressAuthMiddleware, verifyNextAuth } from '@ouim/logto-authkit/server'
```

Includes JWT verification, Express middleware, and Next.js helpers.

### Bundler config entry

```typescript theme={null}
import { viteConfig, webpackConfig, nextjsConfig } from '@ouim/logto-authkit/bundler-config'
```

Pre-configured bundler settings for Vite, Webpack, and Next.js.

<Tip>
  When editing build-time scripts, import from `@ouim/logto-authkit/bundler-config` to avoid executing the main library bundle.
</Tip>

## TypeScript support

logto-authkit is written in TypeScript and provides comprehensive type definitions out of the box.

```typescript theme={null}
import type {
  LogtoUser,
  AuthOptions,
  AuthMiddleware,
  CallbackPageProps,
  NavigationOptions,
  AdditionalPage
} from '@ouim/logto-authkit'

// Server types
import type {
  AuthContext,
  AuthPayload,
  VerifyAuthOptions
} from '@ouim/logto-authkit/server'
```

## Next steps

<Card title="Quick start" icon="rocket" href="/logto-authkit/quickstart">
  Get up and running with authentication in minutes
</Card>


# Introduction
Source: https://docs.ouim.me/logto-authkit/introduction

A simpler way to use @logto/react with prebuilt UI components and hooks for fast authentication setup in React apps

# Welcome to logto-authkit

A plug-and-play authentication solution that simplifies [@logto/react](https://github.com/logto-io/logto) with prebuilt UI components and hooks for fast authentication setup in React applications.

logto-authkit is designed to save you the hassle of setting up authentication from scratch and connecting frontend and server authentication flows. Start quickly with minimal configuration, and migrate to the official Logto SDK later if you need more advanced features.

## Key features

<CardGroup>
  <Card title="Frontend components" icon="react" href="#frontend-features">
    Prebuilt AuthProvider, UserCenter, CallbackPage, and useAuth hook for seamless React integration
  </Card>

  <Card title="Server authentication" icon="server" href="#server-features">
    JWT verification with JWKS caching, Express middleware, and Next.js support
  </Card>

  <Card title="Guest mode" icon="user" href="#guest-mode">
    Built-in guest user support with fingerprinting for anonymous access
  </Card>

  <Card title="Bundler configuration" icon="gear" href="#bundler-support">
    Pre-configured settings for Vite, Webpack, and Next.js
  </Card>
</CardGroup>

## Frontend features

* **AuthProvider** - Easy context provider for Logto authentication with custom navigation support
* **UserCenter** - Prebuilt user dropdown/avatar component for your navbar
* **CallbackPage** - Handles OAuth callback and popup flows automatically
* **useAuth** - React hook for accessing user data and auth actions with middleware support
* **Custom navigation** - Integrates with React Router, Next.js, and other routing libraries
* **Guest mode** - Built-in guest user support with fingerprinting

## Server features

* **JWT verification** - Manual JWT verification with JWKS caching
* **Express.js middleware** - Ready-to-use Express middleware with built-in cookie parsing
* **Next.js support** - API routes and middleware helpers for Next.js applications
* **TypeScript support** - Full TypeScript definitions included

## Guest mode

Allow users to browse your app without authentication using the built-in guest mode with fingerprinting:

```tsx src/components/Dashboard.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function Dashboard() {
  const { user } = useAuth({
    middleware: 'guest', // Allow guest users
  })

  return (
    <div>
      {user ? (
        <p>Welcome back, {user.name}!</p>
      ) : (
        <p>You're browsing as a guest</p>
      )}
    </div>
  )
}
```

## Bundler support

Pre-configured bundler settings resolve common issues with the `jose` library and other dependencies:

* **Vite** - Pre-configured Vite settings via `viteConfig`
* **Webpack** - Webpack configuration helpers via `webpackConfig`
* **Next.js** - Next.js bundler configuration via `nextjsConfig`

## Get started

<CardGroup>
  <Card title="Installation" icon="download" href="/logto-authkit/installation">
    Install logto-authkit using npm, yarn, or pnpm
  </Card>

  <Card title="Quick start" icon="rocket" href="/logto-authkit/quickstart">
    Get up and running with authentication in minutes
  </Card>
</CardGroup>


# Quick start
Source: https://docs.ouim.me/logto-authkit/quickstart

Get up and running with logto-authkit authentication in minutes

# Quick start

This guide will help you set up logto-authkit authentication in your React application in just a few steps.

## Prerequisites

Before you begin, make sure you have:

* A Logto account and application configured
* Your Logto endpoint URL and app ID
* logto-authkit installed in your project

<Note>
  Don't have a Logto account? [Sign up for free](https://logto.io) and create your first application.
</Note>

## Setup steps

<Steps>
  <Step title="Wrap your app with AuthProvider">
    Wrap your application with the `AuthProvider` component and pass your Logto configuration:

    ```tsx src/App.tsx theme={null}
    import { AuthProvider } from '@ouim/logto-authkit'

    const config = {
      endpoint: 'https://your-logto-endpoint.com',
      appId: 'your-app-id',
    }

    function App() {
      return (
        <AuthProvider
          config={config}
          callbackUrl="http://localhost:3000/callback"
        >
          <YourApp />
        </AuthProvider>
      )
    }
    ```

    <Tip>
      For single-page applications, pass a `customNavigate` function to integrate with your router:

      ```tsx theme={null}
      <AuthProvider
        config={config}
        callbackUrl="http://localhost:3000/callback"
        customNavigate={(url, options) => {
          // Your navigation logic here
        }}
      >
      ```
    </Tip>
  </Step>

  <Step title="Add the UserCenter component">
    Drop the `UserCenter` component into your navbar for a ready-to-use user menu:

    ```tsx src/components/Navbar.tsx theme={null}
    import { UserCenter } from '@ouim/logto-authkit'

    function Navbar() {
      return (
        <nav className="flex items-center justify-between h-16 px-4 border-b">
          <div className="font-bold">MyApp</div>
          <UserCenter />
        </nav>
      )
    }
    ```

    The `UserCenter` component automatically shows:

    * Avatar, name, and sign out button when authenticated
    * Sign in button when not authenticated

    <Note>
      Customize the `UserCenter` with additional pages:

      ```tsx theme={null}
      <UserCenter
        additionalPages={[
          { link: '/settings', text: 'Settings' },
          { link: '/profile', text: 'Profile' }
        ]}
      />
      ```
    </Note>
  </Step>

  <Step title="Create a callback route">
    Create a route at `/callback` and render the `CallbackPage` component to handle OAuth redirects:

    ```tsx src/pages/Callback.tsx theme={null}
    import { CallbackPage } from '@ouim/logto-authkit'

    export default function Callback() {
      return <CallbackPage />
    }
    ```

    The `CallbackPage` handles:

    * OAuth callback flow
    * Popup authentication flow
    * Redirects after successful authentication

    <Tip>
      Customize the callback experience with optional props:

      ```tsx theme={null}
      <CallbackPage
        onSuccess={() => console.log('Auth success!')}
        onError={(error) => console.error('Auth error:', error)}
        loadingComponent={<CustomLoader />}
      />
      ```
    </Tip>
  </Step>

  <Step title="Use the useAuth hook">
    Access user data and authentication actions anywhere in your app with the `useAuth` hook:

    ```tsx src/components/Dashboard.tsx theme={null}
    import { useAuth } from '@ouim/logto-authkit'

    function Dashboard() {
      const { user, isLoadingUser, signIn, signOut } = useAuth()

      if (isLoadingUser) return <div>Loading...</div>
      if (!user) return <button onClick={() => signIn()}>Sign in</button>

      return (
        <div>
          <p>Welcome, {user.name}!</p>
          <button onClick={() => signOut()}>Sign out</button>
        </div>
      )
    }
    ```
  </Step>
</Steps>

## Route protection

Protect routes by requiring authentication with the `middleware` option:

```tsx src/pages/ProtectedPage.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function ProtectedPage() {
  const { user } = useAuth({
    middleware: 'auth',
    redirectTo: '/login', // Redirect if not authenticated
  })

  if (!user) return null // or loading indicator
  
  return <div>Protected content</div>
}
```

## Guest mode

Allow anonymous users to access your app with guest mode:

```tsx src/pages/PublicPage.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function PublicPage() {
  const { user } = useAuth({
    middleware: 'guest', // Allow guest users
  })

  return (
    <div>
      {user ? (
        <p>Welcome back, {user.name}!</p>
      ) : (
        <p>You're browsing as a guest</p>
      )}
    </div>
  )
}
```

## Refresh authentication

Manually refresh the authentication state when needed:

```tsx src/components/RefreshButton.tsx theme={null}
import { useAuth } from '@ouim/logto-authkit'

function RefreshButton() {
  const { refreshAuth } = useAuth()

  return (
    <button onClick={refreshAuth}>
      Refresh Auth
    </button>
  )
}
```

## Popup sign-in (optional)

Enable popup-based sign-in for a better user experience:

```tsx src/App.tsx theme={null}
<AuthProvider
  config={config}
  callbackUrl="http://localhost:3000/callback"
  enablePopupSignIn={true}
>
  <YourApp />
</AuthProvider>
```

With popup sign-in enabled:

* Authentication happens in a popup window
* Main page doesn't reload
* Users stay on the same page after signing in

<Warning>
  Popup sign-in requires a `/signin` route. Make sure to create one if using this feature.
</Warning>

## Next steps

<CardGroup>
  <Card title="Server authentication" icon="server" href="/logto-authkit/server/overview">
    Secure your API endpoints with JWT verification
  </Card>

  <Card title="Bundler configuration" icon="gear" href="/logto-authkit/configuration/bundler-setup">
    Configure Vite, Webpack, or Next.js bundlers
  </Card>
</CardGroup>


# Express Middleware
Source: https://docs.ouim.me/logto-authkit/server/express-middleware

Protect Express.js routes with Logto authentication

## Quick Start

The `createExpressAuthMiddleware` function creates an Express middleware that automatically verifies Logto tokens and attaches user information to the request object.

```javascript theme={null}
import express from 'express';
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server';

const app = express();

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: 'https://your-tenant.logto.app',
  audience: 'https://api.yourapp.com',
});

// Protected route
app.get('/api/user/profile', authMiddleware, (req, res) => {
  // Access authenticated user info
  const { userId, payload } = req.auth;
  
  res.json({
    userId,
    email: payload.email,
    name: payload.name,
  });
});

app.listen(3000);
```

## Configuration

The middleware accepts a `VerifyAuthOptions` object:

<ParamField type="string">
  Your Logto server URL

  ```typescript theme={null}
  logtoUrl: 'https://your-tenant.logto.app'
  ```
</ParamField>

<ParamField type="string">
  The API resource identifier you registered in Logto

  ```typescript theme={null}
  audience: 'https://api.yourapp.com'
  ```
</ParamField>

<ParamField type="string">
  Custom cookie name if you changed it in the frontend

  ```typescript theme={null}
  cookieName: 'my_custom_token'
  ```
</ParamField>

<ParamField type="string">
  Require a specific scope to be present in the token

  ```typescript theme={null}
  requiredScope: 'read:admin'
  ```
</ParamField>

<ParamField type="boolean">
  Allow unauthenticated users with guest context

  ```typescript theme={null}
  allowGuest: true
  ```
</ParamField>

## Request Object

The middleware adds an `auth` property to the Express request:

```typescript theme={null}
interface ExpressRequest {
  auth?: AuthContext;
  // ... other Express request properties
}

interface AuthContext {
  userId: string | null;          // Logto user ID
  isAuthenticated: boolean;       // true if authenticated
  payload: AuthPayload | null;    // Full JWT claims
  isGuest?: boolean;             // true in guest mode
  guestId?: string;              // UUID for guest users
}
```

## Usage Examples

### Basic Protected Route

```javascript theme={null}
import { createExpressAuthMiddleware } from '@ouim/logto-authkit/server';

const auth = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_API_RESOURCE,
});

app.get('/api/protected', auth, (req, res) => {
  res.json({ 
    message: 'This is protected!',
    userId: req.auth.userId 
  });
});
```

### Route with Required Scope

```javascript theme={null}
const adminAuth = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_API_RESOURCE,
  requiredScope: 'admin:write',
});

app.delete('/api/admin/users/:id', adminAuth, (req, res) => {
  // Only users with 'admin:write' scope can access
  res.json({ success: true });
});
```

### Multiple Middleware

Use different authentication requirements for different routes:

```javascript theme={null}
const basicAuth = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_API_RESOURCE,
});

const adminAuth = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_API_RESOURCE,
  requiredScope: 'admin',
});

// Regular authenticated routes
app.use('/api/user', basicAuth);
app.get('/api/user/profile', (req, res) => { /* ... */ });
app.put('/api/user/settings', (req, res) => { /* ... */ });

// Admin-only routes
app.use('/api/admin', adminAuth);
app.get('/api/admin/users', (req, res) => { /* ... */ });
app.post('/api/admin/settings', (req, res) => { /* ... */ });
```

### Guest Mode

Allow both authenticated and guest users:

```javascript theme={null}
const flexibleAuth = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL,
  audience: process.env.LOGTO_API_RESOURCE,
  allowGuest: true,
});

app.get('/api/cart', flexibleAuth, (req, res) => {
  if (req.auth.isAuthenticated) {
    // Load user's saved cart from database
    const cart = await getCartByUserId(req.auth.userId);
    res.json(cart);
  } else {
    // Load guest cart from session
    const cart = await getCartByGuestId(req.auth.guestId);
    res.json(cart);
  }
});
```

### TypeScript Usage

```typescript theme={null}
import express, { Request, Response } from 'express';
import { createExpressAuthMiddleware, AuthContext } from '@ouim/logto-authkit/server';

// Extend Express Request type
declare global {
  namespace Express {
    interface Request {
      auth?: AuthContext;
    }
  }
}

const app = express();

const authMiddleware = createExpressAuthMiddleware({
  logtoUrl: process.env.LOGTO_URL!,
  audience: process.env.LOGTO_API_RESOURCE!,
});

app.get('/api/profile', authMiddleware, (req: Request, res: Response) => {
  // TypeScript knows about req.auth
  const userId = req.auth!.userId;
  res.json({ userId });
});
```

## Error Responses

The middleware returns `401 Unauthorized` for authentication failures:

### Missing Token

```json theme={null}
{
  "error": "Authentication required",
  "message": "No token found in cookies or Authorization header"
}
```

### Invalid Token

```json theme={null}
{
  "error": "Authentication failed",
  "message": "Token verification failed: Token has expired"
}
```

### Missing Scope

```json theme={null}
{
  "error": "Authentication failed",
  "message": "Token verification failed: Missing required scope: admin:write"
}
```

<Note>
  When `allowGuest: true`, the middleware never returns 401 errors. Instead, it sets `req.auth` with guest context.
</Note>

## How It Works

The middleware performs these steps on each request:

<Steps>
  <Step title="Parse Cookies">
    Automatically parses cookies using `cookie-parser` if not already available
  </Step>

  <Step title="Extract Token">
    Checks for token in cookies (`logto_authtoken`) then Authorization header
  </Step>

  <Step title="Verify Token">
    * Fetches JWKS from Logto server (cached for 5 minutes)
    * Verifies JWT signature using the appropriate public key
    * Validates issuer, audience, expiration, and scopes
  </Step>

  <Step title="Set Auth Context">
    Attaches `AuthContext` to `req.auth` and calls `next()`
  </Step>

  <Step title="Handle Errors">
    Returns 401 JSON response or guest context (if `allowGuest` enabled)
  </Step>
</Steps>

## Best Practices

<AccordionGroup>
  <Accordion title="Environment Variables">
    Store configuration in environment variables:

    ```javascript theme={null}
    const auth = createExpressAuthMiddleware({
      logtoUrl: process.env.LOGTO_URL,
      audience: process.env.LOGTO_API_RESOURCE,
    });
    ```
  </Accordion>

  <Accordion title="Route-Level Authorization">
    Use different middleware instances for different authorization levels:

    ```javascript theme={null}
    const userAuth = createExpressAuthMiddleware({ ... });
    const adminAuth = createExpressAuthMiddleware({ 
      ..., 
      requiredScope: 'admin' 
    });
    ```
  </Accordion>

  <Accordion title="Check Authentication Status">
    Always check `isAuthenticated` when using `allowGuest`:

    ```javascript theme={null}
    app.post('/api/checkout', flexibleAuth, (req, res) => {
      if (!req.auth.isAuthenticated) {
        return res.status(401).json({ 
          error: 'Please login to checkout' 
        });
      }
      // Process checkout
    });
    ```
  </Accordion>

  <Accordion title="Access JWT Payload">
    The full JWT payload is available in `req.auth.payload`:

    ```javascript theme={null}
    app.get('/api/user', auth, (req, res) => {
      const { email, name, picture } = req.auth.payload;
      res.json({ email, name, picture });
    });
    ```
  </Accordion>
</AccordionGroup>

## Cookie Parsing

The middleware automatically handles cookie parsing:

* If `req.cookies` exists (already parsed), uses it directly
* If not, applies `cookie-parser` middleware internally
* No need to add `cookie-parser` to your app separately

```javascript theme={null}
// This works even without app.use(cookieParser())
app.get('/api/protected', authMiddleware, (req, res) => {
  res.json({ userId: req.auth.userId });
});
```

<Tip>
  While the middleware handles cookie parsing internally, you can still use `cookie-parser` globally if needed for other routes.
</Tip>

## Related

<CardGroup>
  <Card title="Next.js Integration" icon="react" href="/logto-authkit/server/nextjs-integration">
    Server-side auth for Next.js
  </Card>

  <Card title="Generic Usage" icon="code" href="/logto-authkit/server/generic-usage">
    Use in any Node.js environment
  </Card>
</CardGroup>


# Generic Usage
Source: https://docs.ouim.me/logto-authkit/server/generic-usage

Use verifyAuth in any Node.js environment

## Overview

The `verifyAuth` function is a flexible authentication utility that works in any Node.js environment. It accepts either a raw JWT token string or a request object with cookies/headers.

## Function Signature

```typescript theme={null}
function verifyAuth(
  tokenOrRequest: string | { cookies?: any; headers?: any },
  options: VerifyAuthOptions
): Promise<AuthContext>
```

### Parameters

<ParamField type="string | object">
  Either a JWT token string or a request object containing cookies and/or headers

  <Expandable title="Request object structure">
    ```typescript theme={null}
    {
      cookies?: { [key: string]: string },  // Cookie object
      headers?: { [key: string]: string }   // Headers object
    }
    ```
  </Expandable>
</ParamField>

<ParamField type="VerifyAuthOptions">
  Authentication configuration options

  <Expandable title="VerifyAuthOptions properties">
    <ParamField type="string">
      Your Logto server URL (e.g., `https://your-tenant.logto.app`)
    </ParamField>

    <ParamField type="string">
      API resource identifier registered in Logto
    </ParamField>

    <ParamField type="string">
      Custom cookie name if changed in frontend
    </ParamField>

    <ParamField type="string">
      Required scope that must be present in the token
    </ParamField>

    <ParamField type="boolean">
      Enable guest mode for unauthenticated users
    </ParamField>
  </Expandable>
</ParamField>

### Return Value

<ResponseField name="AuthContext" type="object">
  User authentication context

  <Expandable title="AuthContext properties">
    <ResponseField name="userId" type="string | null">
      Logto user ID from the `sub` claim (null for guests)
    </ResponseField>

    <ResponseField name="isAuthenticated" type="boolean">
      Whether the user is authenticated
    </ResponseField>

    <ResponseField name="payload" type="AuthPayload | null">
      Full JWT payload with all claims (null for guests)
    </ResponseField>

    <ResponseField name="isGuest" type="boolean">
      Whether user is in guest mode
    </ResponseField>

    <ResponseField name="guestId" type="string">
      Generated UUID for guest users
    </ResponseField>
  </Expandable>
</ResponseField>

### Errors

Throws an error when:

* No token found in request and `allowGuest` is false
* Invalid JWT format
* Token signature verification fails
* Token has expired
* Invalid issuer or audience
* Missing required scope

## Usage Examples

### With Raw Token String

Verify a JWT token directly:

```typescript theme={null}
import { verifyAuth } from '@ouim/logto-authkit/server';

const token = 'eyJhbGciOiJSUzI1NiIs...';

try {
  const auth = await verifyAuth(token, {
    logtoUrl: 'https://your-tenant.logto.app',
    audience: 'https://api.yourapp.com',
  });

  console.log('User ID:', auth.userId);
  console.log('Email:', auth.payload.email);
} catch (error) {
  console.error('Authentication failed:', error.message);
}
```

### With Request Object

Extract token automatically from cookies or headers:

```typescript theme={null}
import { verifyAuth } from '@ouim/logto-authkit/server';

// Example request object
const request = {
  cookies: { logto_authtoken: 'eyJhbGciOiJSUzI1NiIs...' },
  headers: { authorization: 'Bearer eyJhbGciOiJSUzI1NiIs...' },
};

try {
  const auth = await verifyAuth(request, {
    logtoUrl: process.env.LOGTO_URL,
    audience: process.env.LOGTO_API_RESOURCE,
  });

  console.log('Authenticated:', auth.isAuthenticated);
  console.log('User ID:', auth.userId);
} catch (error) {
  console.error('Authentication failed:', error.message);
}
```

### AWS Lambda Function

```typescript theme={null}
import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
import { verifyAuth } from '@ouim/logto-authkit/server';

export const handler = async (
  event: APIGatewayProxyEvent
): Promise<APIGatewayProxyResult> => {
  try {
    // Extract token from Lambda event
    const token = event.headers.Authorization?.replace('Bearer ', '');
    
    if (!token) {
      return {
        statusCode: 401,
        body: JSON.stringify({ error: 'No token provided' }),
      };
    }

    const auth = await verifyAuth(token, {
      logtoUrl: process.env.LOGTO_URL!,
      audience: process.env.LOGTO_API_RESOURCE!,
    });

    // Your Lambda logic
    return {
      statusCode: 200,
      body: JSON.stringify({ 
        message: 'Success',
        userId: auth.userId 
      }),
    };
  } catch (error) {
    return {
      statusCode: 401,
      body: JSON.stringify({ 
        error: 'Authentication failed',
        message: error.message 
      }),
    };
  }
};
```

### Cloudflare Workers

```typescript theme={null}
import { verifyAuth } from '@ouim/logto-authkit/server';

export default {
  async fetch(request: Request): Promise<Response> {
    try {
      // Extract token from Authorization header
      const authHeader = request.headers.get('Authorization');
      const token = authHeader?.replace('Bearer ', '');

      if (!token) {
        return new Response(
          JSON.stringify({ error: 'No token provided' }),
          { status: 401, headers: { 'Content-Type': 'application/json' } }
        );
      }

      const auth = await verifyAuth(token, {
        logtoUrl: 'https://your-tenant.logto.app',
        audience: 'https://api.yourapp.com',
      });

      // Your worker logic
      return new Response(
        JSON.stringify({ userId: auth.userId }),
        { status: 200, headers: { 'Content-Type': 'application/json' } }
      );
    } catch (error) {
      return new Response(
        JSON.stringify({ error: error.message }),
        { status: 401, headers: { 'Content-Type': 'application/json' } }
      );
    }
  },
};
```

### GraphQL Resolver Context

```typescript theme={null}
import { ApolloServer } from '@apollo/server';
import { verifyAuth } from '@ouim/logto-authkit/server';

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: async ({ req }) => {
    try {
      const auth = await verifyAuth(
        {
          cookies: req.cookies,
          headers: req.headers,
        },
        {
          logtoUrl: process.env.LOGTO_URL!,
          audience: process.env.LOGTO_API_RESOURCE!,
          allowGuest: true, // Allow unauthenticated GraphQL queries
        }
      );

      return { auth };
    } catch (error) {
      return { auth: null };
    }
  },
});

// In resolvers
const resolvers = {
  Query: {
    me: async (_parent, _args, context) => {
      if (!context.auth?.isAuthenticated) {
        throw new Error('Not authenticated');
      }
      
      return getUserById(context.auth.userId);
    },
  },
};
```

### tRPC Middleware

```typescript theme={null}
import { initTRPC } from '@trpc/server';
import { verifyAuth } from '@ouim/logto-authkit/server';

const t = initTRPC.context().create();

const isAuthed = t.middleware(async ({ ctx, next }) => {
  const auth = await verifyAuth(
    {
      cookies: ctx.req.cookies,
      headers: ctx.req.headers,
    },
    {
      logtoUrl: process.env.LOGTO_URL!,
      audience: process.env.LOGTO_API_RESOURCE!,
    }
  );

  if (!auth.isAuthenticated) {
    throw new Error('Not authenticated');
  }

  return next({
    ctx: {
      auth,
    },
  });
});

export const protectedProcedure = t.procedure.use(isAuthed);

// Usage
export const appRouter = t.router({
  getProfile: protectedProcedure.query(({ ctx }) => {
    return getUserById(ctx.auth.userId);
  }),
});
```

### Fastify Plugin

```typescript theme={null}
import Fastify from 'fastify';
import { verifyAuth } from '@ouim/logto-authkit/server';

const fastify = Fastify();

// Register auth decorator
fastify.decorateRequest('auth', null);

// Auth hook
fastify.addHook('preHandler', async (request, reply) => {
  if (request.routeOptions.config?.auth === false) {
    return; // Skip auth for public routes
  }

  try {
    const auth = await verifyAuth(
      {
        cookies: request.cookies,
        headers: request.headers,
      },
      {
        logtoUrl: process.env.LOGTO_URL!,
        audience: process.env.LOGTO_API_RESOURCE!,
      }
    );

    request.auth = auth;
  } catch (error) {
    reply.code(401).send({ error: 'Unauthorized' });
  }
});

// Protected route
fastify.get('/api/profile', async (request) => {
  return { userId: request.auth.userId };
});

// Public route
fastify.get('/api/health', { config: { auth: false } }, async () => {
  return { status: 'ok' };
});
```

### Hono Middleware

```typescript theme={null}
import { Hono } from 'hono';
import { verifyAuth } from '@ouim/logto-authkit/server';

const app = new Hono();

// Auth middleware
const authMiddleware = async (c, next) => {
  try {
    const auth = await verifyAuth(
      {
        cookies: c.req.cookies,
        headers: c.req.headers,
      },
      {
        logtoUrl: process.env.LOGTO_URL!,
        audience: process.env.LOGTO_API_RESOURCE!,
      }
    );

    c.set('auth', auth);
    await next();
  } catch (error) {
    return c.json({ error: 'Unauthorized' }, 401);
  }
};

// Use middleware
app.use('/api/*', authMiddleware);

app.get('/api/profile', (c) => {
  const auth = c.get('auth');
  return c.json({ userId: auth.userId });
});
```

### Next.js Server Actions

```typescript theme={null}
'use server'

import { cookies } from 'next/headers';
import { verifyAuth } from '@ouim/logto-authkit/server';

export async function createPost(formData: FormData) {
  const cookieStore = cookies();
  const token = cookieStore.get('logto_authtoken')?.value;

  if (!token) {
    throw new Error('Unauthorized');
  }

  const auth = await verifyAuth(token, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_API_RESOURCE!,
  });

  // Create post with authenticated user
  const post = await db.post.create({
    data: {
      title: formData.get('title') as string,
      content: formData.get('content') as string,
      authorId: auth.userId,
    },
  });

  return post;
}
```

## Guest Mode

When `allowGuest: true`, the function returns guest context instead of throwing errors:

```typescript theme={null}
const auth = await verifyAuth(request, {
  logtoUrl: process.env.LOGTO_URL!,
  audience: process.env.LOGTO_API_RESOURCE!,
  allowGuest: true,
});

if (auth.isAuthenticated) {
  // Authenticated user
  console.log('User ID:', auth.userId);
  console.log('Email:', auth.payload.email);
} else if (auth.isGuest) {
  // Guest user
  console.log('Guest ID:', auth.guestId);
}
```

## Error Handling

### Without Guest Mode

```typescript theme={null}
try {
  const auth = await verifyAuth(token, { ... });
  // Use auth.userId, auth.payload, etc.
} catch (error) {
  if (error.message.includes('expired')) {
    // Handle expired token
  } else if (error.message.includes('Invalid audience')) {
    // Handle wrong audience
  } else {
    // Handle other errors
  }
}
```

### With Guest Mode

```typescript theme={null}
const auth = await verifyAuth(request, {
  allowGuest: true,
  // ... other options
});

// Never throws - always returns auth context
if (auth.isAuthenticated) {
  // Proceed with authenticated user
} else {
  // Proceed with guest user
}
```

## Token Extraction Priority

When passing a request object, tokens are checked in this order:

1. **Cookie**: `cookies[cookieName]` (default: `logto_authtoken`)
2. **Authorization Header**: `headers.authorization` (Bearer token)

```typescript theme={null}
const request = {
  cookies: { logto_authtoken: 'token-from-cookie' },
  headers: { authorization: 'Bearer token-from-header' },
};

// Will use 'token-from-cookie' (cookies take precedence)
const auth = await verifyAuth(request, { ... });
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Environment Variables">
    Store Logto configuration in environment variables:

    ```typescript theme={null}
    const auth = await verifyAuth(token, {
      logtoUrl: process.env.LOGTO_URL!,
      audience: process.env.LOGTO_API_RESOURCE!,
    });
    ```
  </Accordion>

  <Accordion title="Handle Errors Gracefully">
    Always wrap calls in try-catch unless using `allowGuest`:

    ```typescript theme={null}
    try {
      const auth = await verifyAuth(token, { ... });
    } catch (error) {
      // Return appropriate error response
    }
    ```
  </Accordion>

  <Accordion title="Validate isAuthenticated">
    When using guest mode, always check authentication status:

    ```typescript theme={null}
    if (!auth.isAuthenticated) {
      throw new Error('Authentication required');
    }
    ```
  </Accordion>

  <Accordion title="Cache Configuration">
    Create a reusable configuration object:

    ```typescript theme={null}
    const authOptions = {
      logtoUrl: process.env.LOGTO_URL!,
      audience: process.env.LOGTO_API_RESOURCE!,
    };

    const auth = await verifyAuth(token, authOptions);
    ```
  </Accordion>
</AccordionGroup>

## Type Definitions

```typescript theme={null}
import type {
  AuthContext,
  AuthPayload,
  VerifyAuthOptions,
} from '@ouim/logto-authkit/server';

// AuthPayload - JWT token claims
interface AuthPayload {
  sub: string;              // User ID
  scope: string;            // Space-separated scopes
  [key: string]: any;       // Additional custom claims
}

// AuthContext - Authentication result
interface AuthContext {
  userId: string | null;
  isAuthenticated: boolean;
  payload: AuthPayload | null;
  isGuest?: boolean;
  guestId?: string;
}

// VerifyAuthOptions - Configuration
interface VerifyAuthOptions {
  logtoUrl: string;
  audience: string;
  cookieName?: string;
  requiredScope?: string;
  allowGuest?: boolean;
}
```

## Related

<CardGroup>
  <Card title="Express Middleware" icon="node-js" href="/logto-authkit/server/express-middleware">
    Ready-to-use Express middleware
  </Card>

  <Card title="Next.js Integration" icon="react" href="/logto-authkit/server/nextjs-integration">
    Next.js-specific authentication
  </Card>
</CardGroup>


# Next.js Integration
Source: https://docs.ouim.me/logto-authkit/server/nextjs-integration

Authenticate Next.js API routes and middleware

## Quick Start

Use `verifyNextAuth` to authenticate Next.js App Router API routes and middleware. It handles both cookies and Authorization headers.

```typescript theme={null}
import { NextRequest, NextResponse } from 'next/server';
import { verifyNextAuth } from '@ouim/logto-authkit/server';

export async function GET(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_API_RESOURCE!,
  });

  if (!result.success) {
    return NextResponse.json(
      { error: result.error },
      { status: 401 }
    );
  }

  const { userId, payload } = result.auth;
  
  return NextResponse.json({
    userId,
    email: payload.email,
  });
}
```

## Function Signature

```typescript theme={null}
function verifyNextAuth(
  request: NextRequest,
  options: VerifyAuthOptions
): Promise<
  | { success: true; auth: AuthContext }
  | { success: false; error: string; auth?: AuthContext }
>
```

### Parameters

<ParamField type="NextRequest">
  The Next.js request object from your API route or middleware
</ParamField>

<ParamField type="VerifyAuthOptions">
  Configuration options for authentication

  <Expandable title="VerifyAuthOptions properties">
    <ParamField type="string">
      Your Logto server URL (e.g., `https://your-tenant.logto.app`)
    </ParamField>

    <ParamField type="string">
      API resource identifier registered in Logto
    </ParamField>

    <ParamField type="string">
      Custom cookie name if changed in frontend
    </ParamField>

    <ParamField type="string">
      Required scope that must be present in the token
    </ParamField>

    <ParamField type="boolean">
      Enable guest mode for unauthenticated users
    </ParamField>
  </Expandable>
</ParamField>

### Return Value

<ResponseField name="success" type="boolean">
  Whether authentication was successful
</ResponseField>

<ResponseField name="auth" type="AuthContext">
  User authentication context (always present when `success: true`, optional with guest mode)

  <Expandable title="AuthContext properties">
    <ResponseField name="userId" type="string | null">
      Logto user ID from the `sub` claim
    </ResponseField>

    <ResponseField name="isAuthenticated" type="boolean">
      Whether the user is authenticated
    </ResponseField>

    <ResponseField name="payload" type="AuthPayload | null">
      Full JWT payload with all claims
    </ResponseField>

    <ResponseField name="isGuest" type="boolean">
      Whether user is in guest mode (when `allowGuest: true`)
    </ResponseField>

    <ResponseField name="guestId" type="string">
      Generated UUID for guest users
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="string">
  Error message when `success: false`
</ResponseField>

## Usage Examples

### API Route (App Router)

```typescript theme={null}
// app/api/user/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { verifyNextAuth } from '@ouim/logto-authkit/server';

export async function GET(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_API_RESOURCE!,
  });

  if (!result.success) {
    return NextResponse.json(
      { error: result.error },
      { status: 401 }
    );
  }

  // Fetch user data from database
  const user = await db.user.findUnique({
    where: { id: result.auth.userId },
  });

  return NextResponse.json({ user });
}
```

### POST Route with Data

```typescript theme={null}
// app/api/posts/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { verifyNextAuth } from '@ouim/logto-authkit/server';

export async function POST(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_API_RESOURCE!,
  });

  if (!result.success) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }

  const body = await request.json();
  
  const post = await db.post.create({
    data: {
      ...body,
      authorId: result.auth.userId,
    },
  });

  return NextResponse.json({ post });
}
```

### Route with Required Scope

```typescript theme={null}
// app/api/admin/users/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { verifyNextAuth } from '@ouim/logto-authkit/server';

export async function DELETE(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_API_RESOURCE!,
    requiredScope: 'admin:users:delete',
  });

  if (!result.success) {
    return NextResponse.json(
      { error: 'Insufficient permissions' },
      { status: 403 }
    );
  }

  // Delete user logic
  return NextResponse.json({ success: true });
}
```

### Next.js Middleware

Protect multiple routes with Next.js middleware:

```typescript theme={null}
// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';
import { verifyNextAuth } from '@ouim/logto-authkit/server';

export async function middleware(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_API_RESOURCE!,
  });

  if (!result.success) {
    return NextResponse.json(
      { error: 'Unauthorized' },
      { status: 401 }
    );
  }

  // Add user ID to response headers for downstream use
  const response = NextResponse.next();
  response.headers.set('x-user-id', result.auth.userId!);
  
  return response;
}

export const config = {
  matcher: '/api/protected/:path*',
};
```

### Guest Mode

Allow both authenticated and guest users:

```typescript theme={null}
// app/api/cart/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { verifyNextAuth } from '@ouim/logto-authkit/server';

export async function GET(request: NextRequest) {
  const result = await verifyNextAuth(request, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_API_RESOURCE!,
    allowGuest: true,
  });

  // result.auth is always present with allowGuest
  const cart = result.auth!.isAuthenticated
    ? await getCartByUserId(result.auth.userId!)
    : await getCartByGuestId(result.auth.guestId!);

  return NextResponse.json({ cart });
}
```

### Reusable Auth Helper

Create a helper function for consistent authentication:

```typescript theme={null}
// lib/auth.ts
import { NextRequest, NextResponse } from 'next/server';
import { verifyNextAuth, AuthContext } from '@ouim/logto-authkit/server';

type AuthHandler = (
  request: NextRequest,
  auth: AuthContext
) => Promise<NextResponse> | NextResponse;

export function withAuth(handler: AuthHandler) {
  return async (request: NextRequest) => {
    const result = await verifyNextAuth(request, {
      logtoUrl: process.env.LOGTO_URL!,
      audience: process.env.LOGTO_API_RESOURCE!,
    });

    if (!result.success) {
      return NextResponse.json(
        { error: result.error },
        { status: 401 }
      );
    }

    return handler(request, result.auth);
  };
}

// Usage in routes
// app/api/profile/route.ts
import { withAuth } from '@/lib/auth';

export const GET = withAuth(async (request, auth) => {
  const user = await db.user.findUnique({
    where: { id: auth.userId },
  });
  
  return NextResponse.json({ user });
});
```

## Server Actions (Experimental)

For Next.js Server Actions, extract the token from cookies:

```typescript theme={null}
'use server'

import { cookies } from 'next/headers';
import { verifyAuth } from '@ouim/logto-authkit/server';

export async function updateProfile(formData: FormData) {
  const cookieStore = cookies();
  const token = cookieStore.get('logto_authtoken')?.value;

  if (!token) {
    throw new Error('Unauthorized');
  }

  const auth = await verifyAuth(token, {
    logtoUrl: process.env.LOGTO_URL!,
    audience: process.env.LOGTO_API_RESOURCE!,
  });

  // Update user profile
  await db.user.update({
    where: { id: auth.userId },
    data: {
      name: formData.get('name'),
    },
  });
}
```

<Note>
  For Server Actions, use the generic `verifyAuth` function instead of `verifyNextAuth`. See [Generic Usage](/logto-authkit/server/generic-usage) for details.
</Note>

## Error Handling

### With allowGuest: false (default)

```typescript theme={null}
const result = await verifyNextAuth(request, { ... });

if (!result.success) {
  // result.error contains the error message
  // result.auth is undefined
  return NextResponse.json(
    { error: result.error },
    { status: 401 }
  );
}

// result.auth is guaranteed to exist and be authenticated
const userId = result.auth.userId;
```

### With allowGuest: true

```typescript theme={null}
const result = await verifyNextAuth(request, {
  allowGuest: true,
  // ... other options
});

if (result.success) {
  // Authenticated user
  const userId = result.auth.userId;
} else {
  // Guest user (result.auth contains guest context)
  if (result.auth?.isGuest) {
    const guestId = result.auth.guestId;
  }
}
```

## Common Error Messages

<AccordionGroup>
  <Accordion title="No token found in cookies or Authorization header">
    No authentication token was provided in the request.

    **Solution**: Ensure the frontend is setting cookies or sending Authorization header.
  </Accordion>

  <Accordion title="Token verification failed: Token has expired">
    The JWT token's expiration time has passed.

    **Solution**: Refresh the token on the frontend or prompt user to re-authenticate.
  </Accordion>

  <Accordion title="Invalid issuer">
    Token wasn't issued by your Logto server.

    **Solution**: Verify `logtoUrl` matches your Logto tenant URL.
  </Accordion>

  <Accordion title="Invalid audience">
    Token's audience claim doesn't match your API resource.

    **Solution**: Verify `audience` matches the API resource registered in Logto.
  </Accordion>

  <Accordion title="Missing required scope">
    Token doesn't include the required scope.

    **Solution**: Ensure the scope is requested during frontend authentication.
  </Accordion>
</AccordionGroup>

## Best Practices

<Steps>
  <Step title="Use Environment Variables">
    Store Logto configuration in environment variables:

    ```typescript theme={null}
    const result = await verifyNextAuth(request, {
      logtoUrl: process.env.LOGTO_URL!,
      audience: process.env.LOGTO_API_RESOURCE!,
    });
    ```
  </Step>

  <Step title="Create Helper Functions">
    Wrap `verifyNextAuth` in helper functions for consistent error handling:

    ```typescript theme={null}
    export const withAuth = (handler: AuthHandler) => { ... };
    ```
  </Step>

  <Step title="Return Appropriate Status Codes">
    * `401 Unauthorized`: Authentication failed or missing
    * `403 Forbidden`: Authenticated but insufficient permissions
  </Step>

  <Step title="Validate Auth Context">
    Always check `isAuthenticated` when using guest mode:

    ```typescript theme={null}
    if (!result.auth?.isAuthenticated) {
      return NextResponse.json({ error: 'Login required' }, { status: 401 });
    }
    ```
  </Step>
</Steps>

## Related

<CardGroup>
  <Card title="Express Middleware" icon="node-js" href="/logto-authkit/server/express-middleware">
    Middleware for Express.js applications
  </Card>

  <Card title="Generic Usage" icon="code" href="/logto-authkit/server/generic-usage">
    Flexible verifyAuth for any environment
  </Card>
</CardGroup>


# Server Authentication
Source: https://docs.ouim.me/logto-authkit/server/overview

Secure your server routes with Logto authentication

## Overview

logto-authkit provides flexible server authentication utilities that work with Express.js, Next.js, and any Node.js environment. All authentication functions verify JWT tokens issued by your Logto server and provide a consistent `AuthContext` object.

## Key Features

<CardGroup>
  <Card title="Express Middleware" icon="node-js" href="/logto-authkit/server/express-middleware">
    Ready-to-use middleware for Express.js applications
  </Card>

  <Card title="Next.js Integration" icon="react" href="/logto-authkit/server/nextjs-integration">
    Server-side authentication for Next.js API routes and middleware
  </Card>

  <Card title="Generic Usage" icon="code" href="/logto-authkit/server/generic-usage">
    Flexible verifyAuth function for any Node.js environment
  </Card>

  <Card title="Guest Mode" icon="user">
    Optional guest mode for unauthenticated users
  </Card>
</CardGroup>

## Authentication Flow

All server authentication functions follow this flow:

1. **Token Extraction**: Checks for JWT token in cookies (default: `logto_authtoken`) or `Authorization` header
2. **JWKS Fetching**: Retrieves public keys from your Logto server (with 5-minute caching)
3. **Signature Verification**: Verifies JWT signature using the appropriate public key
4. **Claims Validation**: Validates issuer, audience, expiration, and required scopes
5. **Context Creation**: Returns an `AuthContext` object with user information

## AuthContext Object

All authentication functions return or set an `AuthContext` object:

```typescript theme={null}
interface AuthContext {
  userId: string | null          // Logto user ID (sub claim)
  isAuthenticated: boolean       // Whether user is authenticated
  payload: AuthPayload | null    // Full JWT payload
  isGuest?: boolean             // Whether user is in guest mode
  guestId?: string              // Generated UUID for guest users
}
```

## Configuration Options

All authentication functions accept a `VerifyAuthOptions` object:

<ParamField type="string">
  Your Logto server URL (e.g., `https://your-tenant.logto.app`)
</ParamField>

<ParamField type="string">
  The API resource identifier registered in Logto
</ParamField>

<ParamField type="string">
  Name of the cookie containing the JWT token
</ParamField>

<ParamField type="string">
  Optional scope that must be present in the token
</ParamField>

<ParamField type="boolean">
  Enable guest mode for unauthenticated users. When enabled, failed authentication returns a guest context instead of throwing an error.
</ParamField>

## Guest Mode

When `allowGuest` is enabled, the authentication functions handle unauthenticated users gracefully:

* No token found: Returns guest context with generated `guestId`
* Invalid token: Falls back to guest context
* Guest ID stored in cookie: `guest_logto_authtoken` (auto-generated UUID)

```typescript theme={null}
// Example guest context
{
  userId: null,
  isAuthenticated: false,
  payload: null,
  isGuest: true,
  guestId: "550e8400-e29b-41d4-a716-446655440000"
}
```

<Tip>
  Guest mode is useful for applications that support both authenticated and anonymous users, such as e-commerce sites or content platforms.
</Tip>

## Token Sources

Authentication tokens can be provided in two ways (checked in order):

### 1. Cookie (Recommended)

Set by the frontend authentication SDK:

```http theme={null}
Cookie: logto_authtoken=eyJhbGciOiJSUzI1NiIs...
```

### 2. Authorization Header

Useful for API clients and mobile apps:

```http theme={null}
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
```

## Error Handling

Authentication functions throw errors in these scenarios:

* **No token found**: When `allowGuest` is disabled and no token is present
* **Invalid JWT format**: Malformed token structure
* **Signature verification failed**: Token signature doesn't match public key
* **Token expired**: Token's `exp` claim is in the past
* **Invalid issuer**: Token wasn't issued by your Logto server
* **Invalid audience**: Token's `aud` claim doesn't match your API resource
* **Missing scope**: Required scope not present in token

<Warning>
  Always handle authentication errors appropriately in production. Return 401 status codes for authentication failures.
</Warning>

## Security Features

<AccordionGroup>
  <Accordion title="JWKS Caching">
    Public keys are cached for 5 minutes to reduce load on your Logto server while maintaining security. The cache is automatically refreshed when expired.
  </Accordion>

  <Accordion title="Automatic Cookie Parsing">
    Express middleware automatically parses cookies using `cookie-parser` if not already available, ensuring seamless integration.
  </Accordion>

  <Accordion title="Comprehensive Validation">
    All JWT claims are validated including issuer, audience, expiration (`exp`), not-before (`nbf`), and custom scopes.
  </Accordion>

  <Accordion title="Multiple Token Sources">
    Supports both cookie-based (for web apps) and header-based (for APIs) authentication in the same endpoint.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Express Setup" icon="node-js" href="/logto-authkit/server/express-middleware">
    Add middleware to Express routes
  </Card>

  <Card title="Next.js Setup" icon="react" href="/logto-authkit/server/nextjs-integration">
    Protect Next.js API routes
  </Card>

  <Card title="Generic Usage" icon="code" href="/logto-authkit/server/generic-usage">
    Use in any Node.js environment
  </Card>
</CardGroup>


# Domain allowlist
Source: https://docs.ouim.me/reacher/configuration/domain-allowlist

How PROXY_ALLOWED_DOMAINS and FETCH_EXTERNAL_TOKEN_MAP control which APIs fetch_external can reach and how auth tokens are injected automatically.

The `fetch_external` tool is Reacher's HTTP proxy for calling external APIs. Two environment variables control its behavior: `PROXY_ALLOWED_DOMAINS` defines which domains Claude is permitted to reach, and `FETCH_EXTERNAL_TOKEN_MAP` tells the server which credential to inject for each domain.

Together they give Claude authenticated access to any REST API without you ever pasting a token into a prompt.

***

## Why domain whitelisting matters

Without a domain restriction, a compromised prompt or an unintended instruction could cause Reacher to proxy requests to arbitrary hosts on the internet — potentially leaking data or triggering unintended side effects on external services.

`PROXY_ALLOWED_DOMAINS` is a strict allowlist. The server parses the hostname from the requested URL and checks it against the list before making any outbound connection. If the domain is not listed, the request is rejected immediately and Claude receives an error — no HTTP call is made.

```
Domain "api.attacker.com" is not in PROXY_ALLOWED_DOMAINS → rejected
Domain "api.github.com" is in PROXY_ALLOWED_DOMAINS → proceeds
```

This means the set of APIs Claude can reach is always explicit and operator-controlled.

***

## How token injection works

`FETCH_EXTERNAL_TOKEN_MAP` is a JSON object that maps domain hostnames to the names of environment variables holding credentials:

```bash theme={null}
FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","api.linear.app":"LINEAR_API_TOKEN"}
```

When `fetch_external` receives a request for `api.github.com`, it:

1. Confirms the domain is in `PROXY_ALLOWED_DOMAINS`
2. Looks up `"api.github.com"` in `FETCH_EXTERNAL_TOKEN_MAP` → finds `"GITHUB_TOKEN"`
3. Reads the value of the `GITHUB_TOKEN` environment variable from the server process
4. Injects `Authorization: Bearer <token>` into the outbound request headers
5. Forwards the request and returns the response to Claude

Claude never sees the token value. It only sees the API response.

<Note>
  If a domain is in `PROXY_ALLOWED_DOMAINS` but not in `FETCH_EXTERNAL_TOKEN_MAP`, the request proceeds without injecting any authorization header. This is correct for public APIs that do not require authentication.
</Note>

***

## JSON format

`FETCH_EXTERNAL_TOKEN_MAP` must be valid JSON. The keys are exact hostnames (not URLs or patterns), and the values are the names of other environment variables — not the token values themselves.

```json theme={null}
{
  "api.github.com": "GITHUB_TOKEN",
  "api.linear.app": "LINEAR_API_TOKEN",
  "api.notion.com": "NOTION_TOKEN",
  "your-instance.atlassian.net": "JIRA_API_TOKEN"
}
```

In `.env`, the entire JSON object must be on a single line:

```bash theme={null}
FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","api.linear.app":"LINEAR_API_TOKEN"}
```

<Warning>
  If the JSON is malformed, `fetch_external` will fail to parse the token map and no tokens will be injected. Check the server logs on startup if you suspect a parsing issue.
</Warning>

***

## Adding a new API integration

Adding support for a new API is a two-line change to your `.env`:

<Steps>
  <Step title="Add the domain to PROXY_ALLOWED_DOMAINS">
    ```bash theme={null}
    PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app,api.notion.com
    ```

    Append the new hostname to the existing comma-separated list.
  </Step>

  <Step title="Add the token mapping to FETCH_EXTERNAL_TOKEN_MAP">
    ```bash theme={null}
    FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","api.linear.app":"LINEAR_API_TOKEN","api.notion.com":"NOTION_TOKEN"}
    ```

    Add the hostname-to-variable mapping. If the API is public and needs no auth, skip this step.
  </Step>

  <Step title="Add the token value as its own environment variable">
    ```bash theme={null}
    NOTION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxx
    ```

    The name here must match the value you used in `FETCH_EXTERNAL_TOKEN_MAP`.
  </Step>

  <Step title="Restart the server">
    ```bash theme={null}
    docker compose restart reacher
    # or: pm2 restart reacher
    ```

    Environment variable changes require a server restart to take effect.
  </Step>
</Steps>

***

## Real examples

### GitHub

```bash theme={null}
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
PROXY_ALLOWED_DOMAINS=api.github.com
FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN"}
```

Once configured, Claude can call any GitHub API endpoint:

```text Example Claude prompt theme={null}
List my open pull requests across all repos.
```

Claude will call `fetch_external` with something like:

```json theme={null}
{
  "url": "https://api.github.com/search/issues?q=is:pr+is:open+author:@me",
  "method": "GET"
}
```

Reacher injects the `Authorization: Bearer ghp_xxx` header automatically and returns the GitHub API response to Claude.

### Linear

```bash theme={null}
LINEAR_API_TOKEN=lin_api_xxxxxxxxxxxxxxxxxxxx
PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app
FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","api.linear.app":"LINEAR_API_TOKEN"}
```

Linear's API is GraphQL. Claude can POST to `https://api.linear.app/graphql` with the appropriate query body.

### Notion

```bash theme={null}
NOTION_TOKEN=secret_xxxxxxxxxxxxxxxxxxxx
PROXY_ALLOWED_DOMAINS=api.github.com,api.notion.com
FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","api.notion.com":"NOTION_TOKEN"}
```

Notion's REST API uses `Bearer` auth — Reacher's injection pattern matches exactly.

### Jira (Atlassian Cloud)

Jira Cloud hostnames are instance-specific (e.g., `your-org.atlassian.net`). Use your exact subdomain:

```bash theme={null}
JIRA_API_TOKEN=your_atlassian_api_token
PROXY_ALLOWED_DOMAINS=your-org.atlassian.net
FETCH_EXTERNAL_TOKEN_MAP={"your-org.atlassian.net":"JIRA_API_TOKEN"}
```

<Note>
  Jira Cloud uses HTTP Basic auth, not Bearer tokens. The standard token injection adds a `Bearer` header. For Jira, you may need to pass credentials differently — check the [Atlassian REST API authentication docs](https://developer.atlassian.com/cloud/jira/platform/basic-auth-for-rest-apis/) and construct the auth header manually if needed.
</Note>

***

## How the domain check works

The allowlist check in `fetch_external` parses the full URL to extract the hostname, then checks exact membership in the allowed list:

```javascript theme={null}
const allowedList = (allowedDomains || '')
  .split(',')
  .map(d => d.trim())
  .filter(d => d)

if (!allowedList.includes(hostname)) {
  return { success: false, error: 'Domain not allowed', hostname }
}
```

This is exact hostname matching — `api.github.com` does not match `github.com` or `gist.github.com`. If you need access to multiple subdomains of the same service, add each one explicitly.

### What happens when a domain is blocked

When Claude calls `fetch_external` for a domain not in the allowlist, the tool returns an error object immediately:

```json theme={null}
{
  "success": false,
  "error": "Domain not allowed",
  "hostname": "api.example.com"
}
```

No outbound HTTP request is made. Claude sees this error and can tell you that the domain is not configured — it will not retry or find a workaround.

<Tip>
  If Claude reports a "Domain not allowed" error for a call you expected to work, double-check that the hostname in `PROXY_ALLOWED_DOMAINS` exactly matches the hostname in the URL (no trailing slashes, no protocol prefix, no path).
</Tip>


# Environment variables
Source: https://docs.ouim.me/reacher/configuration/environment-variables

Complete reference for all environment variables that configure Reacher's authentication, tools, safety, and server behavior.

Reacher is configured primarily through environment variables in a `.env` file at the project root. Copy `.env.example` to `.env` and fill in your values before starting the server.

```bash theme={null}
cp .env.example .env
```

<Note>
  `MCP_SECRET`, `TAILSCALE_API_KEY`, and `GITHUB_TOKEN` are validated at startup. The server will exit immediately if any of these are missing.
</Note>

***

## Authentication

<ParamField type="string">
  Shared secret that Claude.ai sends with every request as a URL query parameter (`?token=...`). All requests without the correct token are rejected with `401 Unauthorized`.

  Generate a secure value with:

  ```bash theme={null}
  openssl rand -hex 32
  ```

  Never reuse a token across environments. Treat this like a password.
</ParamField>

***

## Tailscale

<ParamField type="string">
  API key for the Tailscale control plane. Used by `tailscale_status` to query device list, IP addresses, and online/offline status.

  **Required scope:** Devices (read)

  Create one at [login.tailscale.com/admin/settings/keys](https://login.tailscale.com/admin/settings/keys).
</ParamField>

***

## GitHub

<ParamField type="string">
  Personal access token for GitHub API calls. Used by:

  * `gist_kb` — read and write private Gists
  * `github_search` — search pull requests and commits
  * `fetch_external` — inject auth on requests to `api.github.com` (when configured in `FETCH_EXTERNAL_TOKEN_MAP`)

  **Required scope:** `gist` (read + write). Add `repo` if you need to search private repositories.

  Create one at [github.com/settings/tokens](https://github.com/settings/tokens).
</ParamField>

***

## HTTP proxy

<ParamField type="string">
  Comma-separated list of hostnames that `fetch_external` is permitted to call. Requests to any domain not in this list are rejected before the HTTP call is made.

  ```bash theme={null}
  PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app,api.notion.com
  ```

  Matching is done against the exact hostname parsed from the request URL. See [Domain allowlist](/reacher/configuration/domain-allowlist) for a full explanation.
</ParamField>

<ParamField type="string">
  JSON object that maps hostnames to environment variable names. When `fetch_external` makes a request to a matching domain, it reads the named environment variable and injects it as an `Authorization: Bearer <token>` header.

  ```bash theme={null}
  FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","api.linear.app":"LINEAR_API_TOKEN"}
  ```

  The token value never leaves the server — Claude only sees the result of the API call. See [Domain allowlist](/reacher/configuration/domain-allowlist) for examples.
</ParamField>

***

## SSH safety

<ParamField type="string">
  Comma-separated list of command substrings to block from `ssh_exec`. Matching is case-insensitive substring matching — if any blocked string appears anywhere in the command, the command is rejected.

  ```bash theme={null}
  SSH_BLOCKED_COMMANDS=rm -rf /,shutdown,reboot,mkfs,dd,format
  ```

  This variable overrides `ssh.blocked_commands` in `reacher.config.yaml`. The same setting can also be managed in the YAML file as a list, which supports comments and easier editing.
</ParamField>

<ParamField type="string">
  Comma-separated list of directory prefixes. When set, `ssh_exec` will only allow commands that operate on paths starting with one of the listed directories.

  ```bash theme={null}
  SSH_ALLOWED_DIRS=/home/deploy,/tmp,/var/log
  ```

  When empty (the default), there are no directory restrictions. This variable overrides `ssh.allowed_dirs` in `reacher.config.yaml`.
</ParamField>

***

## Audit logging

<ParamField type="string">
  Set to `false` to disable audit logging entirely. Any other value (or the absence of this variable) leaves auditing enabled.

  ```bash theme={null}
  AUDIT_ENABLED=false
  ```

  When enabled, every tool call is written as a JSON line to `AUDIT_LOG_PATH`. Sensitive keys (anything containing `token`, `password`, `secret`, or `key`) are stripped from the log entry automatically.

  This variable overrides `audit.enabled` in `reacher.config.yaml`.
</ParamField>

<ParamField type="string">
  Path to the audit log file. Accepts both relative paths (resolved from the project root) and absolute paths.

  ```bash theme={null}
  AUDIT_LOG_PATH=/var/log/reacher/audit.log
  ```

  The file is created automatically if it does not exist. Entries are appended, so the file grows continuously — rotate it with a tool like `logrotate` in production.

  This variable overrides `audit.log_path` in `reacher.config.yaml`.
</ParamField>

***

## Server

<ParamField type="number">
  TCP port that the Express HTTP server listens on.

  ```bash theme={null}
  PORT=8080
  ```

  When deploying behind a reverse proxy (Caddy, Nginx, Traefik), this is the internal port the proxy forwards to. Claude.ai connects to the public HTTPS URL, not this port directly.
</ParamField>

<ParamField type="string">
  Set to `true` to put `ssh_exec` into dry-run mode. In this mode, `ssh_exec` logs the command it would have run but does not actually execute it.

  ```bash theme={null}
  DRY_RUN=true
  ```

  Useful for testing prompts and validating what Claude would do before granting live SSH access. The `/health` endpoint reports the current dry-run state.

  This variable overrides `dry_run` in `reacher.config.yaml`.
</ParamField>

***

## Browser

<ParamField type="string">
  Hostname or IP address of the Chrome DevTools Protocol (CDP) compatible browser that the `browser` tool connects to.

  ```bash theme={null}
  BROWSER_CDP_HOST=127.0.0.1
  ```

  Requires a running CDP-compatible browser (such as Lightpanda or Chrome with `--remote-debugging-port`) and the `agent-browser` CLI installed globally.
</ParamField>

<ParamField type="number">
  Port of the CDP-compatible browser.

  ```bash theme={null}
  BROWSER_CDP_PORT=9222
  ```
</ParamField>

***

## Precedence rules

When the same setting exists in both `.env` and `reacher.config.yaml`, the environment variable always wins. This makes it safe to commit a base `reacher.config.yaml` to version control and override specific values per deployment via environment variables.

See [reacher.config.yaml reference](/reacher/configuration/reacher-config) for full details on the YAML config file.


# reacher.config.yaml
Source: https://docs.ouim.me/reacher/configuration/reacher-config

Reference for the optional YAML configuration file that manages safety and behavior settings.

`reacher.config.yaml` is an optional configuration file for managing Reacher's safety and behavior settings. It is designed for settings you want to keep in version control and review as code — particularly the SSH blocklist and audit configuration.

## Setup

```bash theme={null}
cp reacher.config.example.yaml reacher.config.yaml
```

Edit the file, then restart the server. There is no hot-reload — changes take effect on the next startup.

<Note>
  Environment variables always take precedence over YAML values. If `DRY_RUN=true` is set in your environment, the `dry_run: false` in the YAML file has no effect.
</Note>

***

## Full annotated example

```yaml reacher.config.yaml theme={null}
# Reacher Configuration File
# This file is optional. All settings can be overridden via environment variables.
# Environment variables always take precedence over YAML config.
#
# To use this file:
# 1. Copy to reacher.config.yaml in the project root
# 2. Edit the values as needed
# 3. Restart the server for changes to take effect

# SSH Configuration
ssh:
  # List of commands to block from execution.
  # Supports substring matching (case-insensitive).
  # If "rm -rf" is in the list, any command containing "rm -rf" is rejected.
  blocked_commands:
    - "rm -rf"
    - "dd"
    - ":(){ :|:& };:" # fork bomb

  # List of directories where SSH commands are allowed to operate.
  # If empty (or omitted), all directories are allowed — no restriction.
  # Uses prefix matching: "/home/user" allows "/home/user/file.txt".
  allowed_dirs:
    # - "/home/deploy"
    # - "/tmp"
    # - "/var/log"

# Audit Configuration
audit:
  # Enable or disable audit logging.
  # All tool calls are written as JSON lines to audit.log_path.
  # Sensitive keys (token, password, secret, key) are stripped automatically.
  enabled: true

  # Path to audit log file.
  # Accepts relative paths (resolved from project root) or absolute paths.
  log_path: "./reacher-audit.log"

# Dry-run Mode
# When true, ssh_exec logs commands but does not execute them.
# Useful for testing prompts before granting live SSH access.
dry_run: false
```

***

## Settings reference

### `ssh.blocked_commands`

|                  |                                          |
| ---------------- | ---------------------------------------- |
| **Type**         | `string[]`                               |
| **Default**      | `[]` (no commands blocked)               |
| **Env override** | `SSH_BLOCKED_COMMANDS` (comma-separated) |

A list of command substrings to block from `ssh_exec`. Matching is case-insensitive and substring-based: if any string in this list appears anywhere in the submitted command, the command is rejected before it is sent over SSH.

```yaml theme={null}
ssh:
  blocked_commands:
    - "rm -rf"
    - "shutdown"
    - "reboot"
    - "mkfs"
    - "dd"
    - ":(){ :|:& };:" # fork bomb
```

<Tip>
  Start with a conservative blocklist and expand it based on what your use case requires. Blocking `dd`, `mkfs`, and fork bombs covers the most destructive one-liners.
</Tip>

### `ssh.allowed_dirs`

|                  |                                      |
| ---------------- | ------------------------------------ |
| **Type**         | `string[]`                           |
| **Default**      | `[]` (no directory restriction)      |
| **Env override** | `SSH_ALLOWED_DIRS` (comma-separated) |

Optional list of directory prefixes. When set, `ssh_exec` only permits commands whose working path starts with one of the listed directories. An empty list (the default) applies no restriction.

Prefix matching means `/home/deploy` permits `/home/deploy/app/` and `/home/deploy/logs/`, but not `/home/other/`.

```yaml theme={null}
ssh:
  allowed_dirs:
    - "/home/deploy"
    - "/tmp"
    - "/var/log"
```

### `audit.enabled`

|                  |                                               |
| ---------------- | --------------------------------------------- |
| **Type**         | `boolean`                                     |
| **Default**      | `true`                                        |
| **Env override** | `AUDIT_ENABLED` (set to `"false"` to disable) |

Controls whether tool calls are written to the audit log. When `true`, every call to any Reacher tool produces a JSON log entry containing the timestamp, tool name, sanitized input, and success status.

### `audit.log_path`

|                  |                         |
| ---------------- | ----------------------- |
| **Type**         | `string`                |
| **Default**      | `"./reacher-audit.log"` |
| **Env override** | `AUDIT_LOG_PATH`        |

File path for the audit log. The file is created if it does not exist and entries are appended on each tool call. In production, use an absolute path and configure log rotation.

```yaml theme={null}
audit:
  log_path: "/var/log/reacher/audit.log"
```

### `dry_run`

|                  |                                       |
| ---------------- | ------------------------------------- |
| **Type**         | `boolean`                             |
| **Default**      | `false`                               |
| **Env override** | `DRY_RUN` (set to `"true"` to enable) |

When `true`, `ssh_exec` returns a simulated response describing the command it would have run, without making any SSH connection. All other tools continue to operate normally.

The current dry-run state is visible in the `/health` endpoint response:

```json theme={null}
{ "status": "ok", "timestamp": "...", "dry_run": true }
```

***

## How the config system works

On startup, Reacher reads `reacher.config.yaml` from the project root (if it exists) using `js-yaml`. The parsed YAML values are merged with environment variables according to the following precedence rules:

1. **Environment variable is set** → use the environment variable value, ignore YAML
2. **Environment variable is not set, YAML value exists** → use the YAML value
3. **Neither is set** → use the built-in default

The merge logic in `src/lib/config.js` handles type coercion for boolean-like variables. For `AUDIT_ENABLED`, only the exact string `"false"` disables auditing. For `DRY_RUN`, only the exact string `"true"` enables it.

<Warning>
  The YAML file is only read once at startup. Editing `reacher.config.yaml` while the server is running has no effect until you restart the process.
</Warning>

***

## Reloading configuration

<Steps>
  <Step title="Edit reacher.config.yaml">
    Make your changes and save the file.
  </Step>

  <Step title="Restart the server">
    <CodeGroup>
      ```bash Docker theme={null}
      docker compose restart reacher
      ```

      ```bash Bare Node theme={null}
      # If running with PM2:
      pm2 restart reacher

      # If running directly:
      # Send SIGINT (Ctrl+C) and restart:
      node index.js
      ```
    </CodeGroup>
  </Step>

  <Step title="Verify the change took effect">
    Check the startup log output, or query the health endpoint to confirm dry-run state:

    ```bash theme={null}
    curl "http://localhost:3000/health?token=YOUR_MCP_SECRET"
    ```
  </Step>
</Steps>


# Connecting to Claude
Source: https://docs.ouim.me/reacher/connecting-to-claude

Link your running Reacher server to Claude.ai as a custom MCP connector.

## Prerequisites

* Reacher must be running and publicly reachable over HTTPS. If you haven't done that yet, complete the [Quickstart](/reacher/quickstart) first.
* Your server URL must use HTTPS — Claude.ai will not connect to plain HTTP endpoints.
* You'll need your `MCP_SECRET` value from your `.env` file.

***

## Add the connector

<Steps>
  <Step title="Open Claude.ai settings">
    Go to [Claude.ai](https://claude.ai) and click your profile avatar, then select **Settings**.
  </Step>

  <Step title="Navigate to Integrations">
    In the Settings sidebar, select **Integrations**.
  </Step>

  <Step title="Add a custom connector">
    Click **Add custom connector**.
  </Step>

  <Step title="Enter your server URL">
    Paste your Reacher URL in the following format:

    ```
    https://yourdomain.com/mcp?token=YOUR_MCP_SECRET
    ```

    Replace `yourdomain.com` with your actual domain and `YOUR_MCP_SECRET` with the value from your `.env` file.

    <Warning>
      The `token` query parameter must exactly match the `MCP_SECRET` in your `.env`. If they don't match, every request returns a 401 Unauthorized error and Claude will show a connection failure.
    </Warning>
  </Step>

  <Step title="Save and verify">
    Save the connector. Claude.ai will attempt to contact your server and retrieve the tools list.

    If the connection succeeds, you'll see Reacher listed as an active integration. Open a new conversation and you should see the Reacher tools available.
  </Step>
</Steps>

***

## Verify Claude can call tools

Start a new conversation and try a prompt that exercises a tool:

> "What devices are on my Tailscale network?"

Claude should call `tailscale_status` and return a list of your devices with their hostnames, IP addresses, OS, and online/offline status.

If Claude responds without calling any tools, the connector may not be active in that conversation. Look for a tools icon or connector indicator in the Claude.ai UI and confirm Reacher is enabled.

***

## Bootstrap Claude with AGENT.MD

The repository includes an `AGENT.MD` file that tells Claude how to use Reacher's tools effectively: how to discover your devices, when to use each tool, how to handle Windows vs. Linux targets, and what to save to the knowledge base.

<Tip>
  Drop the contents of `AGENT.MD` into the start of a new conversation. Claude will run the first-time setup checklist automatically: discover your Tailscale devices, probe SSH access on each one, check the `gist_kb` knowledge base for any saved context, and write a device map so future sessions don't start from scratch.
</Tip>

The first-time checklist Claude follows from `AGENT.MD`:

1. Call `tailscale_status` to discover all devices, their hostnames, OS, and online status
2. Run a test command via `ssh_exec` on each online device to confirm SSH access
3. Call `gist_kb` with `action: list` to check for saved notes from previous sessions
4. Write a device map to a gist (`RC: device-map`) so future sessions resume with full context

After this runs once, every new session can pick up where the last one left off.

***

## Troubleshooting

**Claude.ai shows "connection failed" when adding the connector**

* Confirm the server is publicly reachable: `curl "https://yourdomain.com/health?token=YOUR_MCP_SECRET"`
* Check that your reverse proxy is forwarding to port 3000 (or whatever `PORT` you set)
* Verify your SSL certificate is valid and not expired
* Make sure port 443 is open in your VPS firewall

**Tools are listed but Claude gets errors when calling them**

* Check the server logs: `docker compose logs -f reacher`
* Confirm `MCP_SECRET` in the URL matches the one in `.env` exactly (it's case-sensitive)
* Look at `reacher-audit.log` for logged tool calls and their results

**`fetch_external` returns "Domain not allowed"**

The domain isn't in your `PROXY_ALLOWED_DOMAINS` list. Add it to `.env` and restart the server:

```bash theme={null}
PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app,api.notion.com
```

**`ssh_exec` fails to connect to a device**

* Run `tailscale_status` to confirm the device shows online (note: status can lag — try SSH anyway)
* Verify Tailscale SSH is enabled on the target device: `sudo tailscale up --ssh`
* Test the connection manually from your Reacher server: `ssh user@device-hostname`

**`gist_kb` or `github_search` returns an authentication error**

Your `GITHUB_TOKEN` is missing or doesn't have the required scopes. The token needs `gist` scope for `gist_kb` and any additional API scopes needed for `fetch_external` targets. Create or update the token at [github.com/settings/tokens](https://github.com/settings/tokens).


# Bare Node.js
Source: https://docs.ouim.me/reacher/deployment/bare-node

Run Reacher directly with Node.js on any machine without Docker.

Running Reacher directly with Node.js is the lightest-weight option and works well on any VPS where you already manage the process lifecycle.

## Prerequisites

* Node.js 18 or later (`node --version` to check)
* npm (bundled with Node.js)
* Git

## Setup

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone --branch v0.1.0 https://github.com/thezem/reacher.git
    cd reacher
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Configure environment and config files">
    ```bash theme={null}
    cp .env.example .env
    cp reacher.config.example.yaml reacher.config.yaml
    ```

    Open `.env` and fill in your credentials. The required variables are:

    ```bash theme={null}
    MCP_SECRET=<random-string>        # openssl rand -hex 32
    TAILSCALE_API_KEY=<your-key>
    GITHUB_TOKEN=<your-token>
    PROXY_ALLOWED_DOMAINS=api.github.com
    ```

    See [`.env.example`](https://github.com/thezem/reacher/blob/main/.env.example) for the full list of options.
  </Step>

  <Step title="Start the server">
    ```bash theme={null}
    node index.js
    ```

    The server starts on port 3000 by default (or `PORT` from your `.env`).

    ```
    ✅ MCP Server started on http://localhost:3000
       POST http://localhost:3000/mcp
       GET  http://localhost:3000/health
    ```
  </Step>

  <Step title="Verify it is running">
    ```bash theme={null}
    curl "http://localhost:3000/health?token=YOUR_MCP_SECRET"
    ```

    Expected response: `{"status":"ok",...}`
  </Step>
</Steps>

## Start options

<CodeGroup>
  ```bash npm start theme={null}
  npm start
  ```

  ```bash node directly theme={null}
  node index.js
  ```
</CodeGroup>

Both are equivalent — `npm start` is defined as `node index.js` in `package.json`.

## Development mode with auto-reload

During development, use `--watch` mode so the server restarts automatically when you edit files:

```bash theme={null}
npm run dev
```

This runs `node --watch index.js` (built into Node.js 18+, no extra tools needed).

## Production with PM2

For a long-running production deployment, PM2 manages the process, restarts it on crash, and survives reboots.

<Steps>
  <Step title="Install PM2 globally">
    ```bash theme={null}
    npm install -g pm2
    ```
  </Step>

  <Step title="Start Reacher with PM2">
    <CodeGroup>
      ```bash Start theme={null}
      pm2 start index.js --name reacher
      ```

      ```bash Start with log file theme={null}
      pm2 start index.js --name reacher --log ./reacher.log
      ```
    </CodeGroup>
  </Step>

  <Step title="Save the process list and enable startup">
    ```bash theme={null}
    pm2 save
    pm2 startup
    ```

    Run the command that `pm2 startup` prints — this registers PM2 to launch on system boot.
  </Step>
</Steps>

### Useful PM2 commands

```bash theme={null}
pm2 status                  # show all managed processes
pm2 logs reacher            # stream live logs
pm2 logs reacher --lines 50 # last 50 log lines
pm2 restart reacher         # restart the process
pm2 stop reacher            # stop without removing
pm2 delete reacher          # stop and remove from PM2
```

## Health check

```bash theme={null}
curl "http://localhost:3000/health?token=YOUR_MCP_SECRET"
```

```json theme={null}
{
  "status": "ok",
  "timestamp": "2026-03-18T12:00:00.000Z",
  "dry_run": false
}
```

## Updating

<Steps>
  <Step title="Pull the latest code">
    ```bash theme={null}
    git pull
    ```
  </Step>

  <Step title="Install any new dependencies">
    ```bash theme={null}
    npm install
    ```
  </Step>

  <Step title="Restart the server">
    <CodeGroup>
      ```bash PM2 theme={null}
      pm2 restart reacher
      ```

      ```bash Manual theme={null}
      # Stop the running process (Ctrl+C or kill), then:
      node index.js
      ```
    </CodeGroup>
  </Step>
</Steps>

## Exposing Reacher publicly

The server listens on `http://localhost:3000` by default. Claude.ai requires a public HTTPS URL to connect.

The standard approach on a VPS is a reverse proxy. Caddy handles HTTPS certificate provisioning automatically:

```
mcp.yourdomain.com {
  reverse_proxy localhost:3000
}
```

With Nginx, add a server block that proxies to port 3000 and configure Certbot for TLS.

<Info>
  Cloud platforms like EasyPanel, Railway, and Render handle HTTPS automatically if you prefer not to manage a reverse proxy yourself. See the other deployment guides for those options.
</Info>


# Docker
Source: https://docs.ouim.me/reacher/deployment/docker

Deploy Reacher using Docker or Docker Compose on any VPS or local machine.

Docker is the recommended way to run Reacher in production. It handles dependencies, provides automatic restarts, and isolates the process cleanly.

## Prerequisites

* Docker installed on your host machine
* `.env` file configured with your credentials (copy from `.env.example`)
* `reacher.config.yaml` configured (copy from `reacher.config.example.yaml`)

<Tip>
  Generate a strong `MCP_SECRET` before you start: `openssl rand -hex 32`
</Tip>

## Docker Compose (recommended)

Docker Compose is the simplest path for most deployments. It builds the image, maps ports, loads your `.env`, and restarts automatically on crash or reboot.

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone --branch v0.1.0 https://github.com/thezem/reacher.git
    cd reacher
    ```
  </Step>

  <Step title="Configure environment and config files">
    ```bash theme={null}
    cp .env.example .env
    cp reacher.config.example.yaml reacher.config.yaml
    ```

    Edit both files with your credentials. At minimum, set:

    ```bash theme={null}
    MCP_SECRET=<random-string>
    TAILSCALE_API_KEY=<your-tailscale-api-key>
    GITHUB_TOKEN=<your-github-token>
    PROXY_ALLOWED_DOMAINS=api.github.com
    ```
  </Step>

  <Step title="Start the service">
    ```bash theme={null}
    docker compose up -d
    ```

    Docker Compose will build the image and start the container in the background.
  </Step>

  <Step title="Verify it is running">
    ```bash theme={null}
    docker logs mcp-server
    curl "http://localhost:3000/health?token=YOUR_MCP_SECRET"
    ```

    You should see `{"status":"ok",...}` from the health check endpoint.
  </Step>
</Steps>

### docker-compose.yml

This is the full Compose file included in the repository:

```yaml docker-compose.yml theme={null}
version: '3.8'

services:
  mcp-server:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: mcp-server
    ports:
      - "${PORT:-3000}:${PORT:-3000}"
    environment:
      PORT: ${PORT:-3000}
      TAILSCALE_API_KEY: ${TAILSCALE_API_KEY}
      # TELEGRAM_BOT_TOKEN and DEFAULT_CHAT_ID are unused leftover vars in the compose file
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
      DEFAULT_CHAT_ID: ${DEFAULT_CHAT_ID}
    env_file:
      - .env
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "node", "-e", "require('http').get('http://localhost:' + (process.env.PORT || 3000), (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s
    volumes:
      - ./src:/app/src
      - ./index.js:/app/index.js
    # Uncomment for local development with auto-reload
    # command: npm run dev
```

## Manual docker run

If you prefer to manage the container directly without Compose:

<Steps>
  <Step title="Build the image">
    ```bash theme={null}
    docker build -t reacher .
    ```
  </Step>

  <Step title="Run the container">
    ```bash theme={null}
    docker run -d \
      -p 3000:3000 \
      --env-file .env \
      --restart unless-stopped \
      --name reacher \
      reacher
    ```

    The flags do the following:

    * `-d` — run in the background (detached)
    * `-p 3000:3000` — map host port 3000 to container port 3000
    * `--env-file .env` — inject all variables from your `.env` file
    * `--restart unless-stopped` — restart automatically on crash or host reboot
    * `--name reacher` — give the container a stable name for log and management commands
  </Step>
</Steps>

## Checking logs

```bash theme={null}
docker logs reacher
docker logs reacher --follow   # stream live output
```

For Docker Compose deployments, use the service name:

```bash theme={null}
docker compose logs -f mcp-server
```

## Health check

The `/health` endpoint returns the current server status. It requires the same token as the `/mcp` endpoint:

```bash theme={null}
curl "http://localhost:3000/health?token=YOUR_MCP_SECRET"
```

```json theme={null}
{
  "status": "ok",
  "timestamp": "2026-03-18T12:00:00.000Z",
  "dry_run": false
}
```

Docker runs its own built-in health check every 30 seconds against this endpoint. You can inspect it with:

```bash theme={null}
docker inspect --format='{{.State.Health.Status}}' reacher
```

## Updating to a new version

<Steps>
  <Step title="Pull the latest code">
    ```bash theme={null}
    git pull
    ```
  </Step>

  <Step title="Rebuild and restart">
    <CodeGroup>
      ```bash Docker Compose theme={null}
      docker compose up -d --build
      ```

      ```bash Manual docker run theme={null}
      docker build -t reacher .
      docker stop reacher && docker rm reacher
      docker run -d \
        -p 3000:3000 \
        --env-file .env \
        --restart unless-stopped \
        --name reacher \
        reacher
      ```
    </CodeGroup>
  </Step>
</Steps>

## Dockerfile reference

The included Dockerfile produces a minimal production image:

```dockerfile Dockerfile theme={null}
FROM node:22-alpine

# Install openssh-client for ssh_exec tool
RUN apk add --no-cache openssh-client

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies with production flag
RUN npm install --omit=dev

# Copy application code
COPY . .

# Expose port (default 3000, can be overridden)
EXPOSE ${PORT:-3000}

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:' + (process.env.PORT || 3000), (r) => {if (r.statusCode !== 200) throw new Error(r.statusCode)})"

# Start the server
CMD ["node", "index.js"]
```

Key details:

* **Base image**: `node:22-alpine` — small Alpine-based Node 22 image
* **`openssh-client`**: required for the `ssh_exec` tool to reach Tailscale devices
* **`npm install --omit=dev`**: installs only production dependencies to keep the image lean
* **Built-in health check**: polls the server's HTTP port every 30 seconds


# EasyPanel
Source: https://docs.ouim.me/reacher/deployment/easypanel

Deploy Reacher on EasyPanel with automatic builds from GitHub and a managed HTTPS URL.

EasyPanel is a server management panel that connects directly to your GitHub repository and handles image builds, deployments, and HTTPS termination automatically. It runs on your own VPS, so you retain full control of the infrastructure.

## Prerequisites

* An EasyPanel instance running on a VPS ([easypanel.io](https://easypanel.io))
* Your Reacher fork or clone pushed to a GitHub repository
* Your credentials ready (see [`.env.example`](https://github.com/thezem/reacher/blob/main/.env.example))

## Deployment

<Steps>
  <Step title="Create a new project">
    In the EasyPanel dashboard, click **Create Project** and give it a name (e.g. `reacher`).
  </Step>

  <Step title="Add a new service">
    Inside the project, click **Create Service** and choose **App**.
  </Step>

  <Step title="Connect your GitHub repository">
    Select **GitHub** as the source. Authorize EasyPanel to access your account if prompted, then choose your Reacher repository and the branch you want to deploy (e.g. `main` or `v0.1.0`).

    EasyPanel will detect the `Dockerfile` automatically and use it to build the image.
  </Step>

  <Step title="Set the port">
    In the service settings, set the **App Port** to `3000`. This tells EasyPanel which container port to route traffic to.
  </Step>

  <Step title="Configure environment variables">
    Navigate to the **Environment** tab of your service and add each variable:

    | Variable                | Required | Value                                       |
    | ----------------------- | -------- | ------------------------------------------- |
    | `MCP_SECRET`            | Yes      | A random secret (`openssl rand -hex 32`)    |
    | `TAILSCALE_API_KEY`     | Yes      | Your Tailscale API key                      |
    | `GITHUB_TOKEN`          | Yes      | Your GitHub personal access token           |
    | `PROXY_ALLOWED_DOMAINS` | Yes      | Comma-separated list, e.g. `api.github.com` |
    | `PORT`                  | No       | Defaults to `3000`                          |

    Add any additional variables from `.env.example` that you need.
  </Step>

  <Step title="Set the health check path">
    In the service settings, you can set a **Health Check Path**. Because the `/health` endpoint requires the `MCP_SECRET` token as a query parameter, the easiest approach is to skip the HTTP health check and rely on EasyPanel's container restart policy instead.
  </Step>

  <Step title="Deploy">
    Click **Deploy**. EasyPanel builds the Docker image from your repository and starts the container.

    You can monitor build and runtime logs from the **Logs** tab of the service.
  </Step>

  <Step title="Connect to Claude.ai">
    Once the service is running, EasyPanel assigns it a public HTTPS URL (e.g. `https://reacher.your-easypanel-domain.com`).

    Use this URL to connect Claude.ai:

    ```
    https://reacher.your-easypanel-domain.com/mcp?token=YOUR_MCP_SECRET
    ```

    Go to **Claude.ai** > **Settings** > **Integrations** > **Add custom connector** and paste the URL above.
  </Step>
</Steps>

## Automatic deploys on push

EasyPanel can rebuild and redeploy your service automatically whenever you push to GitHub. Enable this in the service's **Source** settings by turning on **Auto Deploy**.

<Tip>
  If you are iterating on the server configuration without changing code, you can trigger a manual redeploy from the EasyPanel dashboard without a git push.
</Tip>

## Viewing logs

Logs are available in real time from the **Logs** tab of your service in the EasyPanel dashboard. There is no separate CLI step required.


# Railway & Render
Source: https://docs.ouim.me/reacher/deployment/railway-render

Deploy Reacher on Railway or Render with automatic HTTPS and GitHub-based deployments.

Railway and Render are managed platforms that deploy directly from a GitHub repository. Both handle HTTPS, DNS, and container orchestration automatically — no VPS configuration needed.

<Warning>
  Both platforms offer free tiers that **spin down idle services** after a period of inactivity. A sleeping server cannot receive requests from Claude.ai. For reliable operation, use a paid plan or deploy to an always-on host (a VPS with Docker or bare Node.js).
</Warning>

<Tabs>
  <Tab title="Railway">
    ## Deploy on Railway

    <Steps>
      <Step title="Create a new project">
        Go to [railway.app](https://railway.app) and click **New Project**.
      </Step>

      <Step title="Connect your GitHub repository">
        Choose **Deploy from GitHub repo** and select your Reacher repository.

        Railway detects the `Dockerfile` automatically and uses it to build the image.
      </Step>

      <Step title="Configure the start command">
        In the service settings under **Deploy**, confirm the start command is:

        ```bash theme={null}
        node index.js
        ```

        If Railway does not detect it automatically, set it explicitly.
      </Step>

      <Step title="Set environment variables">
        Navigate to the **Variables** tab of your service and add the following:

        | Variable                | Required | Value                                                   |
        | ----------------------- | -------- | ------------------------------------------------------- |
        | `MCP_SECRET`            | Yes      | A random secret (`openssl rand -hex 32`)                |
        | `TAILSCALE_API_KEY`     | Yes      | Your Tailscale API key                                  |
        | `GITHUB_TOKEN`          | Yes      | Your GitHub personal access token                       |
        | `PROXY_ALLOWED_DOMAINS` | Yes      | Comma-separated list, e.g. `api.github.com`             |
        | `PORT`                  | No       | Railway injects `PORT` automatically; you can omit this |

        Add any additional variables from `.env.example` that apply to your setup.
      </Step>

      <Step title="Deploy">
        Railway builds and deploys automatically after you save the variables. Watch the build logs from the **Deployments** tab.
      </Step>

      <Step title="Get your public URL">
        Once deployed, go to **Settings** > **Networking** and click **Generate Domain**. Railway assigns a public HTTPS URL.

        Use this to connect Claude.ai:

        ```
        https://your-app.up.railway.app/mcp?token=YOUR_MCP_SECRET
        ```
      </Step>

      <Step title="Connect to Claude.ai">
        Go to **Claude.ai** > **Settings** > **Integrations** > **Add custom connector** and paste the URL from the previous step.
      </Step>
    </Steps>

    ### Auto-deploys

    Railway redeploys automatically on every push to your connected branch. No manual trigger needed.
  </Tab>

  <Tab title="Render">
    ## Deploy on Render

    <Steps>
      <Step title="Create a new Web Service">
        Go to [render.com](https://render.com), click **New**, and select **Web Service**.
      </Step>

      <Step title="Connect your GitHub repository">
        Authorize Render to access your GitHub account if prompted, then select your Reacher repository and branch.
      </Step>

      <Step title="Configure the service">
        Set the following in the service configuration:

        * **Runtime**: `Node`
        * **Root Directory**: leave blank (or `.` if your repo root contains `index.js`)
        * **Build Command**: `npm install`
        * **Start Command**: `node index.js`
      </Step>

      <Step title="Set environment variables">
        Scroll to the **Environment Variables** section and add:

        | Variable                | Required | Value                                       |
        | ----------------------- | -------- | ------------------------------------------- |
        | `MCP_SECRET`            | Yes      | A random secret (`openssl rand -hex 32`)    |
        | `TAILSCALE_API_KEY`     | Yes      | Your Tailscale API key                      |
        | `GITHUB_TOKEN`          | Yes      | Your GitHub personal access token           |
        | `PROXY_ALLOWED_DOMAINS` | Yes      | Comma-separated list, e.g. `api.github.com` |

        Add any additional variables from `.env.example` that apply to your setup.

        <Note>
          Render injects `PORT` automatically. Do not set it manually — Render assigns the port and expects your app to listen on `process.env.PORT`.
        </Note>
      </Step>

      <Step title="Deploy">
        Click **Create Web Service**. Render builds from your repository and starts the container. Monitor progress in the **Logs** tab.
      </Step>

      <Step title="Get your public URL">
        Render assigns a public HTTPS URL in the format `https://your-app.onrender.com`. It is shown at the top of the service dashboard.

        Use this to connect Claude.ai:

        ```
        https://your-app.onrender.com/mcp?token=YOUR_MCP_SECRET
        ```
      </Step>

      <Step title="Connect to Claude.ai">
        Go to **Claude.ai** > **Settings** > **Integrations** > **Add custom connector** and paste the URL from the previous step.
      </Step>
    </Steps>

    ### Auto-deploys

    Render redeploys automatically on every push to your connected branch. This can be disabled in the service settings if you prefer manual deploys.
  </Tab>
</Tabs>

## Health check path

For both platforms, set the health check path to `/health`. Note that this endpoint requires the `MCP_SECRET` token as a query parameter (`?token=YOUR_SECRET`) — configure your platform's health check accordingly, or use a platform-level TCP check on port 3000 instead.

## Environment variable reference

See [`.env.example`](https://github.com/thezem/reacher/blob/main/.env.example) for the full list of supported variables and descriptions.


# Adding tools
Source: https://docs.ouim.me/reacher/extending/adding-tools

Add custom tools to Reacher — each tool is a self-contained file with a name, description, schema, and handler.

Every tool in Reacher is a single file in `src/tools/`. There is no framework to configure, no plugin system to learn. You create a file, register it in one place, and it appears in Claude's tool list.

This guide walks through the complete pattern: the file structure, handler signatures, registration, audit logging, and how to test your new tool.

## The tool file pattern

Every tool exports four things:

| Export        | Type             | Purpose                                                              |
| ------------- | ---------------- | -------------------------------------------------------------------- |
| `name`        | `string`         | Tool identifier Claude uses when calling it                          |
| `description` | `string`         | Natural language description Claude uses to decide when to invoke it |
| `schema`      | Zod shape object | Parameter definitions — descriptions become Claude's parameter docs  |
| `handler`     | `async function` | The implementation                                                   |

Here's the minimal shape, taken directly from the codebase:

```javascript src/tools/gist_kb.js theme={null}
export const name = 'gist_kb'

export const description =
  'Manage a private personal knowledge base backed by GitHub Gists. ' +
  'All entries are namespaced with the cc-- filename prefix automatically. ' +
  'Supports list, get, create, update, and delete operations.'

export const schema = {
  action: z.enum(['list', 'get', 'create', 'update', 'delete']),
  id: z.string().optional().describe('Gist ID - required for get, update, delete'),
  title: z.string().optional().describe('Filename without prefix - tool adds cc-- automatically'),
  content: z.string().optional().describe('File content - required for create and update'),
  description: z.string().optional().describe('Gist description'),
}

export async function handler(args, env) {
  const token = env.GITHUB_TOKEN
  // ...
}
```

<Tip>
  Put `.describe()` on every Zod field. These strings are what Claude reads when it decides how to fill in parameters — they are your tool's inline documentation. A field without a description leaves Claude guessing.
</Tip>

## Handler signature options

Different tools receive different parameters depending on what they need. The server passes only what's required — this limits each tool's access to credentials it doesn't use.

| Signature                            | Used by                           | When to use                         |
| ------------------------------------ | --------------------------------- | ----------------------------------- |
| `handler(args)`                      | `ssh_exec`                        | No environment access needed        |
| `handler(args, apiKey)`              | `tailscale_status`                | Needs one specific API key          |
| `handler(args, allowedDomains, env)` | `fetch_external`, `github_search` | Needs domain allowlist + env tokens |
| `handler(args, env)`                 | `gist_kb`, `browser`              | Needs full environment object       |

Choose the most restrictive signature that covers your tool's actual needs.

## Step-by-step: creating a new tool

This example builds a `disk_usage` tool that checks free disk space on a remote host. It's new — not already in the codebase — and demonstrates the full pattern cleanly.

<Steps>
  <Step title="Create the tool file">
    Create `src/tools/disk_usage.js`:

    <CodeGroup>
      ```javascript src/tools/disk_usage.js theme={null}
      /**
       * Disk Usage tool
       * Returns disk space summary for one or more paths on a remote host via SSH
       */

      import { z } from 'zod'
      import { spawn } from 'child_process'
      import { auditLog } from '../lib/audit.js'

      export const name = 'disk_usage'

      export const description =
        'Check disk space usage on a remote Tailscale device. ' +
        'Returns human-readable output for one or more paths. ' +
        'Use this before running operations that write large files.'

      export const schema = {
        hostname: z
          .string()
          .describe('Tailscale hostname of the target device (e.g. "myserver")'),
        paths: z
          .array(z.string())
          .optional()
          .default(['/'])
          .describe('Filesystem paths to check — defaults to root partition'),
        user: z
          .string()
          .optional()
          .default('ubuntu')
          .describe('SSH user to connect as (default: ubuntu)'),
      }

      /**
       * @param {{ hostname: string, paths: string[], user: string }} args
       */
      export async function handler({ hostname, paths = ['/'], user = 'ubuntu' }) {
        const pathList = paths.join(' ')
        const command = `df -h ${pathList}`

        return new Promise((resolve) => {
          const sshArgs = [
            '-o', 'StrictHostKeyChecking=no',
            '-o', 'IdentitiesOnly=yes',
            '-i', '/root/.ssh/reacher-key',
            `${user}@${hostname}`,
            command,
          ]

          let stdout = ''
          let stderr = ''

          const proc = spawn('/usr/bin/ssh', sshArgs, { timeout: 15_000 })

          proc.stdout.on('data', (data) => { stdout += data.toString() })
          proc.stderr.on('data', (data) => { stderr += data.toString() })

          proc.on('close', (code) => {
            resolve({
              success: code === 0,
              hostname,
              user,
              paths,
              stdout: stdout.trim(),
              stderr: stderr.trim(),
              exitCode: code ?? 1,
            })
          })

          proc.on('error', (error) => {
            resolve({
              success: false,
              hostname,
              user,
              paths,
              error: error.message,
              exitCode: 1,
            })
          })
        })
      }
      ```
    </CodeGroup>

    The file is entirely self-contained. It imports only what it needs (`z` from Zod, `spawn` from Node's `child_process`), defines its own schema, and handles its own errors.
  </Step>

  <Step title="Register the tool in mcp-server.js">
    Open `src/mcp-server.js` and add two things: the import at the top, and a `server.tool(...)` call in the body.

    <CodeGroup>
      ```javascript src/mcp-server.js (import) theme={null}
      // Add this line with the other imports at the top of the file
      import * as diskUsage from './tools/disk_usage.js'
      ```

      ```javascript src/mcp-server.js (registration) theme={null}
      // Add this block inside createMCPServer(), following the same pattern
      // -------------------------------------------------------------------------
      // disk_usage - no env vars needed, uses SSH key from filesystem
      // -------------------------------------------------------------------------
      server.tool(diskUsage.name, diskUsage.description, diskUsage.schema, async args => {
        const result = await diskUsage.handler(args)
        await auditLog(diskUsage.name, args, result)
        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
      })
      ```
    </CodeGroup>

    The four arguments to `server.tool()` are always: `name`, `description`, `schema`, and an async wrapper that calls the handler and passes the result to `auditLog`.
  </Step>

  <Step title="Add audit logging">
    Every tool registration in `mcp-server.js` follows this wrapper pattern:

    ```javascript src/mcp-server.js theme={null}
    server.tool(myTool.name, myTool.description, myTool.schema, async args => {
      const result = await myTool.handler(args)
      await auditLog(myTool.name, args, result)
      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
    })
    ```

    `auditLog` writes to `reacher-audit.log` with the tool name, timestamp, arguments, and result. Sensitive keys (authorization headers, tokens) are stripped automatically before writing. You do not need to redact values yourself — just always call `auditLog` in the wrapper, never inside the tool handler.
  </Step>

  <Step title="Restart the server">
    <Tabs>
      <Tab title="Docker">
        ```bash theme={null}
        docker restart reacher
        ```
      </Tab>

      <Tab title="Docker Compose">
        ```bash theme={null}
        docker compose restart
        ```
      </Tab>

      <Tab title="Bare Node (dev)">
        ```bash theme={null}
        npm run dev
        ```

        If you're running with `--watch` (`npm run dev`), the server restarts automatically on file changes.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Verify with tools/list">
    Send a `tools/list` request to confirm your tool appears:

    ```bash theme={null}
    curl -s -X POST http://localhost:3000/mcp?token=YOUR_MCP_SECRET \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' \
      | jq '.result.tools[] | select(.name == "disk_usage")'
    ```

    You should see your tool's name, description, and the full parameter schema in the response.
  </Step>

  <Step title="Test in Claude">
    Start a new Claude conversation and ask something that naturally invokes your tool:

    > "How much disk space is left on homelab?"

    Claude will call `disk_usage` with `hostname: "homelab"` and return the result. If it doesn't pick up the tool, check that your `description` clearly states the tool's purpose and when to use it — Claude reads that string to decide whether to invoke it.
  </Step>
</Steps>

## Zod schema reference

The `schema` export is a plain object whose values are Zod validators. The MCP SDK converts it to a JSON Schema for Claude automatically.

```javascript theme={null}
export const schema = {
  // Required string
  hostname: z.string().describe('Tailscale hostname of the target device'),

  // Optional string with default
  user: z.string().optional().default('ubuntu').describe('SSH user (default: ubuntu)'),

  // Enum
  format: z.enum(['json', 'text']).optional().default('json')
    .describe('Output format — json returns parsed object, text returns raw string'),

  // Optional array
  paths: z.array(z.string()).optional().default(['/'])
    .describe('Paths to check — defaults to root partition'),

  // Optional object (for POST bodies, etc.)
  body: z.record(z.any()).optional().describe('Request body for POST requests'),
}
```

<Tip>
  Write descriptions from Claude's perspective. `"SSH user (default: ubuntu)"` tells Claude what the value is and what to assume when the user doesn't specify. `"string"` tells Claude nothing.
</Tip>

## Accessing environment variables

If your tool needs API keys or config values from `.env`, accept `env` as a second parameter and read from it:

```javascript theme={null}
export async function handler(args, env) {
  const apiKey = env.MY_SERVICE_API_KEY
  if (!apiKey) throw new Error('MY_SERVICE_API_KEY is not set')
  // ...
}
```

Then in `mcp-server.js`, pass `env` when calling the handler:

```javascript theme={null}
server.tool(myTool.name, myTool.description, myTool.schema, async args => {
  const result = await myTool.handler(args, env)
  await auditLog(myTool.name, args, result)
  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
})
```

The `env` object is `process.env` (or a subset of it) passed into `createMCPServer(env)` at startup.

<Note>
  Add any new environment variables to `.env.example` with a comment explaining what they're for. This keeps your setup reproducible.
</Note>


# Token injection
Source: https://docs.ouim.me/reacher/extending/token-injection

How fetch_external injects API credentials per domain — tokens stay server-side, Claude never sees them.

Token injection is the mechanism that makes `fetch_external` work as a general-purpose API proxy. Instead of pasting tokens into every prompt, or building a dedicated connector for each API, you map a domain to an environment variable. When Claude calls `fetch_external` with a URL, Reacher looks up that domain, reads the token from the server environment, and injects it into the request automatically.

Claude sends the URL. Reacher sends the credential. Claude never sees the token.

## The problem it solves

Without token injection, every API call would require one of:

* Pasting the token into the Claude conversation (exposed in chat history, prompt injections possible)
* Building a dedicated MCP tool per API (maintenance overhead, still needs token storage)
* Storing tokens client-side in Claude Desktop config (not available in Claude.ai)

Token injection moves credential management entirely to the server. You set a token once in `.env`. Every subsequent call to that domain gets it injected transparently.

## How FETCH\_EXTERNAL\_TOKEN\_MAP works

`FETCH_EXTERNAL_TOKEN_MAP` is a JSON string in your `.env` that maps domain names to environment variable names:

```bash .env theme={null}
FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","api.linear.app":"LINEAR_TOKEN"}
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
LINEAR_TOKEN=lin_api_xxxxxxxxxxxxxxxxxxxx
```

The key is the exact hostname (no scheme, no path). The value is the name of the environment variable that holds the token — not the token itself.

This indirection matters: you can rotate a token by updating a single env var, without touching the map. You can also share a token across multiple tools (`gist_kb` and `fetch_external` both use `GITHUB_TOKEN`) without duplicating it.

## The token injection flow

<Steps>
  <Step title="Claude calls fetch_external with a URL">
    Claude constructs a `fetch_external` call and sends it to the MCP server:

    ```json theme={null}
    {
      "tool": "fetch_external",
      "arguments": {
        "url": "https://api.github.com/repos/thezem/reacher/pulls?state=open",
        "method": "GET"
      }
    }
    ```

    No token, no credentials. Just a URL and a method.
  </Step>

  <Step title="Handler parses the hostname">
    The handler extracts the hostname from the URL using the built-in `URL` class:

    ```javascript src/tools/fetch_external.js theme={null}
    const parsedUrl = new URL(url)
    const hostname = parsedUrl.hostname
    // hostname = "api.github.com"
    ```
  </Step>

  <Step title="Domain is checked against the allowlist">
    Before any token lookup, the domain is verified against `PROXY_ALLOWED_DOMAINS`:

    ```javascript src/tools/fetch_external.js theme={null}
    const allowedList = (allowedDomains || '')
      .split(',')
      .map(d => d.trim())
      .filter(d => d)

    if (!allowedList.includes(hostname)) {
      return {
        success: false,
        error: 'Domain not allowed',
        url,
        hostname,
      }
    }
    ```

    If the domain is not in the allowlist, the request is rejected immediately — no network call, no token lookup.
  </Step>

  <Step title="Hostname is looked up in the token map">
    The token map is loaded once at module initialization from `FETCH_EXTERNAL_TOKEN_MAP`:

    ```javascript src/tools/fetch_external.js theme={null}
    const TOKEN_INJECTION_MAP = JSON.parse(process.env.FETCH_EXTERNAL_TOKEN_MAP || '{}')
    ```

    Then the hostname is looked up to find which env var holds its token:

    ```javascript src/tools/fetch_external.js theme={null}
    const tokenEnvVar = TOKEN_INJECTION_MAP[hostname]
    // tokenEnvVar = "GITHUB_TOKEN"
    ```
  </Step>

  <Step title="Token is read and injected as a header">
    If the lookup finds a variable name, the token is read from `env` and injected into the request headers:

    ```javascript src/tools/fetch_external.js theme={null}
    const finalHeaders = { ...headers }

    if (tokenEnvVar && env[tokenEnvVar]) {
      finalHeaders['Authorization'] = `Bearer ${env[tokenEnvVar]}`
    }
    ```

    `env` here is `process.env` — the token value is only ever read server-side. It is never returned to Claude in any response.
  </Step>

  <Step title="Request is made with the injected header">
    The assembled request goes out with the full headers:

    ```javascript src/tools/fetch_external.js theme={null}
    const fetchOptions = {
      method,
      headers: finalHeaders,
    }

    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
      fetchOptions.body = JSON.stringify(body)
      if (!finalHeaders['Content-Type']) {
        finalHeaders['Content-Type'] = 'application/json'
      }
    }

    const response = await fetch(url, fetchOptions)
    ```

    The upstream API receives `Authorization: Bearer ghp_xxx` as if a human had set it manually.
  </Step>

  <Step title="Response is returned to Claude — token stripped">
    The response body, status, and headers are returned to Claude. The `Authorization` header is never echoed back — Claude only sees the API's response data, not the credential used to obtain it.

    The audit log also strips token values before writing, so they do not appear in `reacher-audit.log`.
  </Step>
</Steps>

## Custom header formats

The default injection uses `Authorization: Bearer <token>`. Some APIs use different authentication schemes. You have two options:

### Pass the header manually from Claude

For one-off requests, Claude can set a custom `Authorization` header directly:

```json theme={null}
{
  "url": "https://api.example.com/resource",
  "headers": {
    "X-API-Key": "hardcoded-key-here"
  }
}
```

This works, but the value is visible in the conversation. Use it only for non-sensitive keys or during development.

### Add a custom header format in the tool

For APIs that use a scheme other than Bearer (Jira Basic auth, Linear `Authorization: <token>` without "Bearer", etc.), modify `fetch_external.js` to detect those domains and format the header accordingly.

Here is an example that adds support for Jira's Base64 Basic auth:

```javascript src/tools/fetch_external.js theme={null}
// After the existing Bearer injection block:
const tokenEnvVar = TOKEN_INJECTION_MAP[hostname]
if (tokenEnvVar && env[tokenEnvVar]) {
  // Jira uses Basic auth: base64("email:token")
  if (hostname.endsWith('atlassian.net')) {
    const email = env.JIRA_EMAIL
    const encoded = Buffer.from(`${email}:${env[tokenEnvVar]}`).toString('base64')
    finalHeaders['Authorization'] = `Basic ${encoded}`
  } else {
    finalHeaders['Authorization'] = `Bearer ${env[tokenEnvVar]}`
  }
}
```

Add the corresponding env vars to `.env`:

```bash .env theme={null}
PROXY_ALLOWED_DOMAINS=api.github.com,yourcompany.atlassian.net
FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","yourcompany.atlassian.net":"JIRA_TOKEN"}
GITHUB_TOKEN=ghp_xxx
JIRA_TOKEN=your_jira_api_token
JIRA_EMAIL=you@yourcompany.com
```

For `api-key` style headers (used by some services like Datadog or Algolia), the same pattern applies — change `Authorization: Bearer` to the appropriate header name and format:

```javascript theme={null}
finalHeaders['DD-API-KEY'] = env[tokenEnvVar]
```

## Adding a new token mapping

<Steps>
  <Step title="Add the domain to PROXY_ALLOWED_DOMAINS">
    ```bash .env theme={null}
    PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app
    ```

    `fetch_external` will refuse to call any domain not in this list, regardless of what's in the token map. Both values must be set.
  </Step>

  <Step title="Add the domain-to-variable mapping in FETCH_EXTERNAL_TOKEN_MAP">
    ```bash .env theme={null}
    FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","api.linear.app":"LINEAR_TOKEN"}
    ```

    The key is the exact hostname. The value is the name of the env var that holds the token — not the token itself.
  </Step>

  <Step title="Set the token value">
    ```bash .env theme={null}
    LINEAR_TOKEN=lin_api_xxxxxxxxxxxxxxxxxxxx
    ```
  </Step>

  <Step title="Restart the server">
    The token map is loaded at startup (`JSON.parse(process.env.FETCH_EXTERNAL_TOKEN_MAP || '{}')`). Changes to `.env` require a restart to take effect.

    ```bash theme={null}
    docker restart reacher
    # or
    docker compose restart
    ```
  </Step>

  <Step title="Verify the integration">
    Ask Claude to make a test call to the new API:

    > "Call the Linear API at [https://api.linear.app/graphql](https://api.linear.app/graphql) with a query for my assigned issues."

    If the token is injected correctly, you'll get a valid API response. If it fails with a 401, check that the hostname in the token map exactly matches the hostname in the URL — including subdomains.
  </Step>
</Steps>

## PROXY\_ALLOWED\_DOMAINS and FETCH\_EXTERNAL\_TOKEN\_MAP interaction

These two settings are independent but complementary:

| Scenario                 | PROXY\_ALLOWED\_DOMAINS | FETCH\_EXTERNAL\_TOKEN\_MAP         | Outcome                              |
| ------------------------ | ----------------------- | ----------------------------------- | ------------------------------------ |
| Domain in both           | `api.github.com`        | `{"api.github.com":"GITHUB_TOKEN"}` | Request made with injected token     |
| Domain in allowlist only | `api.github.com`        | `{}`                                | Request made with no auth header     |
| Domain in map only       | *(not listed)*          | `{"api.github.com":"GITHUB_TOKEN"}` | Request blocked — domain not allowed |
| Domain in neither        | *(not listed)*          | `{}`                                | Request blocked                      |

A domain only needs a token map entry if the API requires authentication. Public APIs (e.g. a public REST endpoint with no auth) can appear in `PROXY_ALLOWED_DOMAINS` without a corresponding entry in `FETCH_EXTERNAL_TOKEN_MAP`.

## Security properties

<Note>
  The token injection design provides these guarantees:
</Note>

**Tokens never leave the server.** The token value is read from `process.env` inside the handler and written to a request header. It is never included in any MCP response, never logged to `reacher-audit.log`, and never visible in the Claude conversation.

**Claude cannot exfiltrate tokens.** Claude can call `fetch_external` with any URL — but it cannot read what token was injected, because the handler does not return that information. The audit log confirms the call happened, not the credential value.

**The allowlist prevents open-proxy abuse.** Even with a token map configured, `fetch_external` will not proxy requests to arbitrary domains. The domain check happens before the token lookup, so a misused call fails before any credentials are touched.

**Token rotation requires no code changes.** Rotating a credential is a one-line `.env` update followed by a server restart. The token map does not change — only the value of the referenced env var does.

<Warning>
  If a user-supplied `Authorization` header is passed in the `headers` argument, the injected token overwrites it. Claude cannot override token injection by passing a conflicting header — the server-side token always wins for mapped domains.
</Warning>


# Introduction
Source: https://docs.ouim.me/reacher/introduction

Your own infrastructure layer for Claude. SSH, APIs, memory — all authenticated, all yours.

## What is Reacher?

Reacher is a self-hosted MCP (Model Context Protocol) server that turns Claude into a personal infrastructure agent. It gives Claude authenticated access to your machines, your APIs, and persistent memory — across every conversation.

You run it on a VPS you own. Claude reaches it over HTTPS. Everything in between — SSH keys, API tokens, Tailscale mesh access — stays on your server.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get Reacher running in under 10 minutes with Docker or bare Node.
  </Card>

  <Card title="Connect to Claude" icon="plug" href="/reacher/connecting-to-claude">
    Link your running server to Claude.ai as a custom connector.
  </Card>

  <Card title="Tools reference" icon="wrench" href="/reacher/tools/overview">
    Explore all six tools: ssh\_exec, fetch\_external, gist\_kb, and more.
  </Card>

  <Card title="Add your own tools" icon="code" href="/reacher/extending/adding-tools">
    Every tool is a single file. Add your own in minutes.
  </Card>
</CardGroup>

***

## The problem with official MCP connectors

Official connectors give you 40 tools when you need 3. They live in someone else's sandbox, they don't know your machines, and they reset when the conversation ends.

Reacher is the alternative. One server you own. One authenticated proxy. Every API you care about is just an allowed domain away — no new connector, no new tool, just a new line in your config.

***

## What Reacher actually is

A trust boundary with tools attached.

The VPS is neutral ground — not your laptop, not Anthropic's servers, yours. When Claude calls `ssh_exec` to reach one of your machines, it goes through a server you control, authenticated with a key you own, over your Tailscale mesh. The whole chain is yours.

### The fetch\_external insight

Adding GitHub support to Reacher is not "install the GitHub MCP connector." It's adding `api.github.com` to your allowed domains list. Same tool, same authenticated proxy, new target. Claude already knows REST APIs — it doesn't need a dedicated `github_list_prs` tool. It just needs a way to call the API with your token, without you pasting it into every prompt.

```bash theme={null}
PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app,api.notion.com
```

That's three integrations. *One tool.*

***

## Available tools

| Tool               | What it does                                               |
| ------------------ | ---------------------------------------------------------- |
| `ssh_exec`         | Run shell commands on any Tailscale device                 |
| `tailscale_status` | List all devices with online/offline status, IPs, OS       |
| `fetch_external`   | Proxy HTTP requests with injected auth per domain          |
| `github_search`    | Search GitHub for pull requests or commits                 |
| `gist_kb`          | Read/write a private knowledge base backed by GitHub Gists |
| `browser`          | Control a headless browser via CDP                         |

***

## Architecture overview

```
Claude.ai  ──HTTPS──►  Reacher (your VPS)  ──Tailscale SSH──►  your machines
                              │
                              ├──► fetch_external ──► api.github.com (with token)
                              ├──► gist_kb ──────────► GitHub Gists (with token)
                              └──► browser ──────────► headless browser (CDP)
```

Reacher is stateless — a new MCP transport handler is created per request. No session state is stored server-side. Your tokens never leave your server.

***

## Prerequisites

* A [Tailscale](https://tailscale.com) account with your devices enrolled
* Node.js 18+ or Docker
* A VPS or always-on machine reachable over HTTPS from Claude.ai
* A Tailscale API key and a GitHub personal access token


# Audit log
Source: https://docs.ouim.me/reacher/operations/audit-log

Every tool call Reacher executes is written to a structured log file with sensitive keys stripped automatically.

The audit log gives you a complete, tamper-evident record of what Claude asked Reacher to do and whether it succeeded. It is enabled by default.

***

## What is logged

Every tool call — regardless of which tool — produces one JSON line in the audit log:

```json theme={null}
{"timestamp":"2026-03-18T14:23:01.456Z","tool":"ssh_exec","input":{"hostname":"prod-server","command":"df -h /","user":"deploy"},"success":true}
{"timestamp":"2026-03-18T14:23:15.891Z","tool":"fetch_external","input":{"url":"https://api.github.com/repos/myorg/myrepo/issues","method":"GET"},"success":true}
{"timestamp":"2026-03-18T14:24:02.123Z","tool":"gist_kb","input":{"action":"list"},"success":true}
{"timestamp":"2026-03-18T14:25:44.310Z","tool":"ssh_exec","input":{"hostname":"prod-server","command":"rm -rf /tmp/cache","user":"deploy"},"success":false}
```

Each entry contains:

* `timestamp` — ISO 8601 timestamp of the call
* `tool` — name of the tool that was invoked
* `input` — sanitized arguments passed to the tool
* `success` — `true` if the tool returned successfully, `false` on error or block

## What is not logged

Sensitive keys are stripped from `input` before anything is written to disk. Any argument whose key name contains one of the following substrings (case-insensitive) is removed:

* `token`
* `password`
* `secret`
* `key`

This means `GITHUB_TOKEN`, `MCP_SECRET`, API keys, and similar values never appear in the log file — even if they were passed as tool arguments.

<Note>
  The result value from the tool is not logged — only the `success` boolean. Raw tool output (stdout, API responses, file contents) does not appear in the audit log.
</Note>

***

## Configuration

### Enable or disable

<CodeGroup>
  ```bash .env theme={null}
  # Enable (default)
  AUDIT_ENABLED=true

  # Disable
  AUDIT_ENABLED=false
  ```

  ```yaml reacher.config.yaml theme={null}
  audit:
    enabled: true
  ```
</CodeGroup>

Audit logging is enabled by default. Set `AUDIT_ENABLED=false` (the exact string `"false"`) to disable it.

<Warning>
  Disabling the audit log means you have no record of what commands Claude ran on your infrastructure. Only disable it if you have an alternative logging mechanism in place.
</Warning>

### Log file location

<CodeGroup>
  ```bash .env theme={null}
  AUDIT_LOG_PATH=./reacher-audit.log
  ```

  ```yaml reacher.config.yaml theme={null}
  audit:
    log_path: "./reacher-audit.log"
  ```
</CodeGroup>

The default path is `./reacher-audit.log` relative to the project root. The file is created automatically if it does not exist. Entries are appended — the file is never truncated by Reacher.

In production, use an absolute path and set up external log rotation:

```yaml reacher.config.yaml theme={null}
audit:
  log_path: "/var/log/reacher/audit.log"
```

***

## Reading the log

The log is newline-delimited JSON (NDJSON). Each line is a valid JSON object.

**Follow in real time:**

<CodeGroup>
  ```bash Bare Node theme={null}
  tail -f reacher-audit.log
  ```

  ```bash Docker theme={null}
  docker exec reacher tail -f reacher-audit.log
  ```
</CodeGroup>

**Pretty-print with `jq`:**

```bash theme={null}
tail -f reacher-audit.log | jq .
```

**Filter to a specific tool:**

```bash theme={null}
jq 'select(.tool == "ssh_exec")' reacher-audit.log
```

**Show only failures:**

```bash theme={null}
jq 'select(.success == false)' reacher-audit.log
```

**Count calls by tool:**

```bash theme={null}
jq -r '.tool' reacher-audit.log | sort | uniq -c | sort -rn
```

***

## How it works

The `auditLog` function in `src/lib/audit.js` is called after every tool execution in `src/mcp-server.js`. It:

1. Checks `config.audit.enabled` — if `false`, returns immediately
2. Copies the input arguments and deletes any key whose name contains a sensitive substring
3. Builds a log entry with `timestamp`, `tool`, `input`, and `success`
4. Appends the JSON-serialized entry plus a newline to the log file using `fs.appendFile`

If the write fails (disk full, permissions issue), the error is printed to stderr but does not crash the server or affect the tool response.


# Dry-run mode
Source: https://docs.ouim.me/reacher/operations/dry-run

Have ssh_exec report what it would execute without making any SSH connection.

Dry-run mode lets you verify your setup, test blocklist rules, and onboard new users — all without touching your infrastructure.

<Note>
  Dry-run mode only affects `ssh_exec`. All other tools (`fetch_external`, `gist_kb`, `browser`, etc.) continue to execute normally when dry-run is enabled.
</Note>

***

## How it works

When dry-run is enabled, `ssh_exec` still evaluates all safety checks — the blocklist and directory allowlist run as normal. If the command passes those checks, instead of opening an SSH connection, the tool returns a response describing what it would have run:

```json theme={null}
{
  "success": true,
  "dry_run": true,
  "would_execute": "df -h /",
  "hostname": "prod-server",
  "user": "deploy"
}
```

Blocked commands are still blocked in dry-run mode — they return the same `blocked: true` response regardless:

```json theme={null}
{
  "success": false,
  "blocked": true,
  "reason": "Command blocked by reacher config",
  "matched_rule": "rm -rf",
  "hostname": "prod-server",
  "user": "deploy",
  "command": "rm -rf /tmp/cache"
}
```

***

## Enabling dry-run

<CodeGroup>
  ```bash .env theme={null}
  DRY_RUN=true
  ```

  ```yaml reacher.config.yaml theme={null}
  dry_run: true
  ```
</CodeGroup>

Set `DRY_RUN=true` (the exact string `"true"`) in your `.env` file, or set `dry_run: true` in `reacher.config.yaml`. Restart the server for the change to take effect.

To disable, set `DRY_RUN=false` or remove the variable. The default is `false`.

<Note>
  Environment variables take precedence over YAML values. If `DRY_RUN=true` is set in your environment, `dry_run: false` in the YAML file has no effect.
</Note>

***

## Use cases

**Validating your setup**

Before granting Claude live SSH access, enable dry-run to confirm the server is running, Claude can reach it, and `ssh_exec` is receiving commands correctly. The `would_execute` response in Claude's output confirms the tool invocation path is working end to end.

**Testing blocklist rules**

When adding or changing entries in `ssh.blocked_commands`, dry-run lets you verify your rules without executing anything. Ask Claude to run the commands you want blocked — confirm the blocklist triggers — then disable dry-run.

```bash theme={null}
# In .env
DRY_RUN=true
SSH_BLOCKED_COMMANDS=rm -rf /,shutdown,reboot,mkfs
```

**Onboarding new users**

Share your Reacher instance with a new team member with dry-run enabled. They can explore and issue commands to learn the tool surface without any risk to live infrastructure. Disable dry-run when you're confident in the guardrails.

**Auditing planned actions**

If you want to review what Claude plans to do before committing, enable dry-run, run your workflow, check the audit log for the `would_execute` commands, then disable dry-run and re-run.

***

## Limitations

* Dry-run only intercepts `ssh_exec`. It does not affect `fetch_external`, `gist_kb`, `github_search`, or `browser`.
* There is no partial dry-run — it is all-or-nothing for the `ssh_exec` tool.
* The dry-run flag is read at startup. Changing it requires a server restart.


# Safety mechanisms
Source: https://docs.ouim.me/reacher/operations/safety

Configure SSH guardrails, directory restrictions, and domain whitelisting to define Reacher's access boundaries.

<Warning>
  Reacher gives Claude real access to your infrastructure — that's the point. The mechanisms described here let you define the boundaries. You own the risk tolerance.
</Warning>

Safety in Reacher is opt-in and additive. A default installation with no safety configuration is fully functional but fully open. Start with the defaults below and tighten them to match your environment.

***

## SSH command blocklist

The blocklist prevents `ssh_exec` from running commands that match any entry in the list. Matching happens **before** the SSH connection is made — a blocked command never leaves the server.

### How it works

Matching is **substring-based** and **case-insensitive**. If `rm -rf` is in the blocklist, all of the following are blocked:

```
rm -rf /tmp/cache
RM -RF /
sudo rm -rf /home/user
```

The tool returns immediately with `success: false` and `blocked: true`:

```json theme={null}
{
  "success": false,
  "blocked": true,
  "reason": "Command blocked by reacher config",
  "matched_rule": "rm -rf",
  "hostname": "myserver",
  "user": "deploy",
  "command": "rm -rf /tmp/old"
}
```

### Configuration

<CodeGroup>
  ```yaml reacher.config.yaml theme={null}
  ssh:
    blocked_commands:
      - "rm -rf"
      - "shutdown"
      - "reboot"
      - "mkfs"
      - "dd"
      - "format"
      - ":(){ :|:& };:" # fork bomb
  ```

  ```bash .env theme={null}
  SSH_BLOCKED_COMMANDS=rm -rf /,shutdown,reboot,mkfs,dd,format
  ```
</CodeGroup>

<Tip>
  The `.env.example` ships with `rm -rf /,shutdown,reboot,mkfs,dd,format` as sensible starting defaults. Extend this list based on the commands your environment should never run.
</Tip>

***

## Directory allowlist

The directory allowlist restricts `ssh_exec` to paths under specific prefixes. When the list is non-empty, `ssh_exec` parses path tokens from the command and rejects any that fall outside the allowed set.

### How it works

Matching is **prefix-based**. The tool extracts tokens from the command that start with `/`, `~`, or `./`, then checks each one:

```
Allowed: /home/deploy

✓  /home/deploy/scripts/release.sh
✓  /home/deploy/logs/app.log
✗  /home/other/file
✗  /etc/passwd
```

An empty `allowed_dirs` list (the default) applies no restriction — all paths are permitted.

### Configuration

<CodeGroup>
  ```yaml reacher.config.yaml theme={null}
  ssh:
    allowed_dirs:
      - "/home/deploy"
      - "/tmp"
      - "/var/log"
  ```

  ```bash .env theme={null}
  SSH_ALLOWED_DIRS=/home/deploy,/tmp,/var/log
  ```
</CodeGroup>

***

## Domain whitelisting for fetch\_external

`fetch_external` and `github_search` only proxy requests to domains listed in `PROXY_ALLOWED_DOMAINS`. Requests to any other hostname are rejected before any network call is made.

```bash .env theme={null}
PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app,api.notion.com
```

This prevents the server from being used as an open proxy. Add only the API domains your workflows actually need. See [Domain allowlist](/reacher/configuration/domain-allowlist) for the full configuration reference.

***

## Principle of least exposure

Different tools receive different subsets of the environment to minimize what each one can access:

| Tool                              | What it receives                                  |
| --------------------------------- | ------------------------------------------------- |
| `ssh_exec`                        | No env — operates on config only                  |
| `tailscale_status`                | Tailscale API key only                            |
| `fetch_external`, `github_search` | `allowedDomains` + full env (for token injection) |
| `gist_kb`, `browser`              | Full env object                                   |

This is enforced in handler signatures rather than runtime checks. A tool that doesn't receive `GITHUB_TOKEN` in its arguments cannot use it, regardless of what's in the process environment.

***

## Audit logging

Every tool call is logged to a file with timestamp, tool name, sanitized arguments, and result. Sensitive keys (`token`, `password`, `secret`, `key`) are stripped automatically before writing.

See [Audit log](/reacher/operations/audit-log) for the full reference.

***

## Dry-run mode

When `DRY_RUN=true`, `ssh_exec` evaluates safety rules and returns a `would_execute` response without making any SSH connection. Useful for validating your setup or testing a new blocklist configuration.

See [Dry-run mode](/reacher/operations/dry-run) for details.


# Troubleshooting
Source: https://docs.ouim.me/reacher/operations/troubleshooting

Diagnose and fix common issues with Reacher's connection, SSH, tools, and browser integration.

Find your symptom below. Each section covers the most common cause and how to resolve it.

***

## Connection issues

<AccordionGroup>
  <Accordion title="Claude can't connect to the server">
    Claude requires a public HTTPS URL to reach your Reacher server.

    1. Confirm the server is running and reachable:
       ```bash theme={null}
       curl "https://mcp.yourdomain.com/health?token=YOUR_MCP_SECRET"
       ```
       You should get `{"status":"ok",...}`. If this fails, the problem is network/DNS, not Reacher.

    2. Verify your reverse proxy is forwarding to the correct port (default `3000`).

    3. Make sure the full URL you gave Claude includes the token:
       ```
       https://mcp.yourdomain.com/mcp?token=YOUR_MCP_SECRET
       ```

    4. Check that port `3000` is not blocked by a firewall on your VPS.
  </Accordion>

  <Accordion title="401 Unauthorized">
    The `MCP_SECRET` in the URL does not match the one the server has loaded.

    1. Check what secret the server is using:
       ```bash theme={null}
       docker exec reacher printenv MCP_SECRET
       ```

    2. Compare it to the token in the URL you registered in Claude.ai. They must match exactly — including case and any trailing whitespace.

    3. If you changed `MCP_SECRET` in `.env`, restart the container:
       ```bash theme={null}
       docker compose restart reacher
       ```
  </Accordion>

  <Accordion title="Server not starting">
    Check the container logs for the actual error:

    ```bash theme={null}
    docker logs reacher
    ```

    Common causes:

    * **Missing required env vars** — `MCP_SECRET`, `TAILSCALE_API_KEY`, and `GITHUB_TOKEN` must all be set. A missing variable causes startup to fail with an explicit error message listing the missing keys.
    * **Port already in use** — another process is bound to port `3000`. Change `PORT` in `.env` or stop the other process.
    * **Malformed `.env`** — quotes around values can cause parsing issues. Values in `.env` do not need quotes.
  </Accordion>
</AccordionGroup>

***

## SSH issues

<AccordionGroup>
  <Accordion title="SSH not working — connection refused or timeout">
    <Steps>
      <Step title="Check that the device is online">
        Ask Claude to run `tailscale_status` and confirm the target device shows as `online: true`. An offline device cannot be reached over SSH.
      </Step>

      <Step title="Verify Tailscale SSH is enabled on the target">
        Tailscale SSH must be explicitly enabled on each target machine. SSH to the device manually and run:

        ```bash theme={null}
        sudo tailscale up --ssh
        ```
      </Step>

      <Step title="Test the connection manually">
        From the Reacher server itself, test that SSH works:

        ```bash theme={null}
        docker exec -it reacher ssh user@hostname
        ```

        If this fails, the issue is with SSH credentials or Tailscale connectivity, not Reacher's tool layer.
      </Step>

      <Step title="Check the SSH key">
        Reacher uses `/root/.ssh/reacher-key`. Verify it exists and is mounted correctly:

        ```bash theme={null}
        docker exec reacher ls -la /root/.ssh/reacher-key
        ```

        The key must have `600` permissions. Reacher sets this automatically, but verify if you mounted it manually.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Command blocked unexpectedly">
    The command matched an entry in `SSH_BLOCKED_COMMANDS`. The response includes `matched_rule` showing which rule triggered.

    To see your current blocklist:

    ```bash theme={null}
    docker exec reacher printenv SSH_BLOCKED_COMMANDS
    ```

    If the block is incorrect — for example, a legitimate command contains a blocked substring — you have two options:

    1. **Remove the specific entry** from `SSH_BLOCKED_COMMANDS` or `ssh.blocked_commands` in your YAML config, then restart.
    2. **Reword the command** to avoid the substring. Remember that matching is substring-based, so `dd if=...` matches the blocked entry `dd`.

    After changing the config, restart the server:

    ```bash theme={null}
    docker compose restart reacher
    ```
  </Accordion>

  <Accordion title="Permission denied on a directory path">
    `ssh_exec` returned `blocked: true` with `reason: "Path not in allowed directories"`.

    This means `SSH_ALLOWED_DIRS` (or `ssh.allowed_dirs`) is set and the command references a path outside the allowed prefixes.

    Options:

    1. **Add the path** to your `SSH_ALLOWED_DIRS` list:
       ```bash theme={null}
       # .env
       SSH_ALLOWED_DIRS=/home/deploy,/tmp,/var/log,/new/allowed/path
       ```

    2. **Clear the allowlist** if you no longer want directory restrictions:
       ```bash theme={null}
       SSH_ALLOWED_DIRS=
       ```

    Restart the server after any change.
  </Accordion>
</AccordionGroup>

***

## Tool errors

<AccordionGroup>
  <Accordion title="fetch_external: domain not allowed">
    The target domain is not in `PROXY_ALLOWED_DOMAINS`.

    Add it to your `.env`:

    ```bash theme={null}
    PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app,api.newdomain.com
    ```

    Restart the server. The full hostname must match — `api.github.com` and `github.com` are treated as separate entries.
  </Accordion>

  <Accordion title="GitHub authentication failed">
    The `GITHUB_TOKEN` in your `.env` is either missing, expired, or lacks the required scopes.

    1. Verify the token is set:
       ```bash theme={null}
       docker exec reacher printenv GITHUB_TOKEN
       ```

    2. Check that the token has not expired in [GitHub Settings → Tokens](https://github.com/settings/tokens).

    3. Confirm the token has the right scopes:
       * `repo` (or specific repo access) for `github_search` and API calls via `fetch_external`
       * `gist` for `gist_kb`

    4. Generate a new token and update `.env`, then restart the container.
  </Accordion>

  <Accordion title="gist_kb errors">
    `gist_kb` requires `GITHUB_TOKEN` with `gist` scope (read and write). A token with only `repo` scope will fail.

    1. Go to [GitHub Settings → Tokens](https://github.com/settings/tokens)
    2. Edit your token and enable the `gist` scope
    3. Save and update `GITHUB_TOKEN` in `.env`
    4. Restart the server

    If the token was recently regenerated and you updated `.env`, confirm the container picked up the new value:

    ```bash theme={null}
    docker compose restart reacher
    docker exec reacher printenv GITHUB_TOKEN
    ```
  </Accordion>
</AccordionGroup>

***

## Browser tool issues

<AccordionGroup>
  <Accordion title="agent-browser not found">
    The `browser` tool depends on the `agent-browser` CLI being installed globally on the server.

    ```bash theme={null}
    npm install -g agent-browser
    ```

    If you're running Reacher in Docker, this must be included in your Docker image or installed in the container. The default `Dockerfile` does not include it — add the install step if you need browser support:

    ```dockerfile theme={null}
    RUN npm install -g agent-browser
    ```

    Rebuild and restart the container after making this change.
  </Accordion>

  <Accordion title="CDP connection refused">
    The browser tool connects to a CDP-compatible browser at `ws://BROWSER_CDP_HOST:BROWSER_CDP_PORT`. Connection refused means no browser is listening on that address.

    1. Confirm the browser process is running.

    2. Check the default endpoint: `ws://127.0.0.1:9222`.

    3. If your browser is on a different host or port, update `.env`:
       ```bash theme={null}
       BROWSER_CDP_HOST=127.0.0.1
       BROWSER_CDP_PORT=9222
       ```

    4. Restart Reacher after changing the config.
  </Accordion>

  <Accordion title="Setting up Lightpanda">
    [Lightpanda](https://github.com/lightpanda-io/lightpanda) is a lightweight headless browser with CDP support. To use it with Reacher:

    1. Download and install Lightpanda on your server following the instructions in its repository.

    2. Start Lightpanda with CDP enabled on port `9222`:
       ```bash theme={null}
       lightpanda serve --host 127.0.0.1 --port 9222
       ```

    3. Leave `BROWSER_CDP_HOST` and `BROWSER_CDP_PORT` at their defaults, or set them to match your Lightpanda configuration.

    4. Verify the connection:
       ```bash theme={null}
       curl http://127.0.0.1:9222/json/version
       ```
  </Accordion>
</AccordionGroup>


# Quickstart
Source: https://docs.ouim.me/reacher/quickstart

Get Reacher running in under 10 minutes with Docker or bare Node.

## Prerequisites

Before you start, make sure you have:

* A [Tailscale](https://tailscale.com) account with your devices enrolled in a mesh network
* A VPS or always-on machine to host the server (must be reachable from Claude.ai)
* Node.js 18+ or Docker installed on that machine
* A Tailscale API key and a GitHub personal access token

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone --branch v0.1.0 https://github.com/thezem/reacher.git
    cd reacher
    ```
  </Step>

  <Step title="Copy and configure your environment files">
    Copy both config files from their examples:

    ```bash theme={null}
    cp .env.example .env
    cp reacher.config.example.yaml reacher.config.yaml
    ```

    Open `.env` and fill in your credentials. Every required variable is listed below.

    **Required environment variables**

    | Variable                   | Required | Description                                                                                                                                                                 |
    | -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `MCP_SECRET`               | Yes      | Shared secret that Claude.ai sends with every request. Generate with `openssl rand -hex 32`.                                                                                |
    | `TAILSCALE_API_KEY`        | Yes      | API key for querying your Tailscale network. Needs "Devices (read)" scope. Get one at [tailscale.com/admin/settings/keys](https://login.tailscale.com/admin/settings/keys). |
    | `GITHUB_TOKEN`             | Yes      | Personal access token for GitHub API calls and `gist_kb` read/write. Needs `gist` scope. Create at [github.com/settings/tokens](https://github.com/settings/tokens).        |
    | `PROXY_ALLOWED_DOMAINS`    | Yes      | Comma-separated list of domains `fetch_external` is allowed to call (e.g. `api.github.com,api.linear.app`).                                                                 |
    | `PORT`                     | No       | HTTP port to listen on. Defaults to `3000`.                                                                                                                                 |
    | `DRY_RUN`                  | No       | Set to `true` to have `ssh_exec` log commands without executing them. Defaults to `false`.                                                                                  |
    | `AUDIT_ENABLED`            | No       | Enable audit logging. Defaults to `true`.                                                                                                                                   |
    | `AUDIT_LOG_PATH`           | No       | Path to the audit log file. Defaults to `./reacher-audit.log`.                                                                                                              |
    | `SSH_BLOCKED_COMMANDS`     | No       | Comma-separated list of commands to block from `ssh_exec` (e.g. `rm -rf /,shutdown,reboot`).                                                                                |
    | `SSH_ALLOWED_DIRS`         | No       | Comma-separated list of directories SSH operations are restricted to. Empty means no restriction.                                                                           |
    | `FETCH_EXTERNAL_TOKEN_MAP` | No       | JSON mapping of domain → env var name for automatic token injection (e.g. `{"api.github.com":"GITHUB_TOKEN"}`).                                                             |
    | `BROWSER_CDP_HOST`         | No       | Host of the CDP-compatible browser. Defaults to `127.0.0.1`.                                                                                                                |
    | `BROWSER_CDP_PORT`         | No       | Port of the CDP-compatible browser. Defaults to `9222`.                                                                                                                     |

    <Note>
      `MCP_SECRET`, `TAILSCALE_API_KEY`, and `GITHUB_TOKEN` are validated at startup. The server will refuse to start if any of these are missing.
    </Note>

    **Optional: edit `reacher.config.yaml`**

    The YAML config controls safety settings. The defaults are reasonable, but you can tighten them:

    ```yaml theme={null}
    ssh:
      blocked_commands:
        - "rm -rf"
        - "dd"
        - ":(){ :|:& };:"  # fork bomb
      allowed_dirs: []     # empty = no directory restriction

    audit:
      enabled: true
      log_path: "./reacher-audit.log"

    dry_run: false
    ```

    Environment variables always take precedence over YAML config values.
  </Step>

  <Step title="Enable Tailscale SSH on target devices">
    For `ssh_exec` to reach a machine, Tailscale SSH must be enabled on it. Run this on each device you want Reacher to control:

    ```bash theme={null}
    sudo tailscale up --ssh
    ```

    Then verify SSH access works from your server:

    ```bash theme={null}
    ssh user@device-hostname
    ```

    If that succeeds manually, Reacher will be able to reach it too.

    <Tip>
      You can skip this step initially and come back to it. The `tailscale_status` tool works without SSH being enabled, and you can enable SSH per device as you need it.
    </Tip>
  </Step>

  <Step title="Start the server">
    Choose your runtime:

    <CodeGroup>
      ```bash Docker (recommended) theme={null}
      docker compose up -d
      ```

      ```bash Bare Node theme={null}
      npm install
      node index.js
      ```
    </CodeGroup>

    Check the server started correctly:

    <CodeGroup>
      ```bash Docker theme={null}
      docker compose logs -f reacher
      ```

      ```bash Bare Node theme={null}
      # The server prints a startup message:
      # ✅ MCP Server started on http://localhost:3000
      #    POST http://localhost:3000/mcp
      #    GET  http://localhost:3000/health
      ```
    </CodeGroup>

    <Warning>
      If startup fails with "Missing required environment variables", check that `MCP_SECRET`, `TAILSCALE_API_KEY`, and `GITHUB_TOKEN` are all set in your `.env` file.
    </Warning>
  </Step>

  <Step title="Verify the server is responding">
    Run a `tools/list` request against the local server to confirm everything is working:

    ```bash theme={null}
    curl -X POST "http://localhost:3000/mcp?token=YOUR_MCP_SECRET" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
    ```

    Replace `YOUR_MCP_SECRET` with the value you set in `.env`. You should get back a JSON response listing all six tools: `ssh_exec`, `tailscale_status`, `fetch_external`, `github_search`, `gist_kb`, and `browser`.

    You can also check the health endpoint (requires the same token):

    ```bash theme={null}
    curl "http://localhost:3000/health?token=YOUR_MCP_SECRET"
    ```

    Expected response:

    ```json theme={null}
    { "status": "ok", "timestamp": "...", "dry_run": false }
    ```
  </Step>

  <Step title="Expose the server over HTTPS">
    Claude.ai requires a public HTTPS URL to connect to your server. If you're running on a VPS, set up a reverse proxy in front of port 3000.

    <CodeGroup>
      ```text Caddy theme={null}
      # /etc/caddy/Caddyfile
      mcp.yourdomain.com {
        reverse_proxy localhost:3000
      }
      ```

      ```nginx Nginx theme={null}
      # /etc/nginx/sites-available/reacher
      server {
          listen 80;
          server_name mcp.yourdomain.com;

          location / {
              proxy_pass http://localhost:3000;
              proxy_http_version 1.1;
              proxy_set_header Host $host;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_set_header X-Forwarded-Proto $scheme;
          }
      }
      ```
    </CodeGroup>

    <Note>
      Caddy handles HTTPS certificate provisioning automatically via Let's Encrypt. With Nginx, you'll need to run Certbot separately to obtain and renew a certificate.
    </Note>

    After setting up the proxy, confirm it's reachable from the public internet:

    ```bash theme={null}
    curl -X POST "https://mcp.yourdomain.com/mcp?token=YOUR_MCP_SECRET" \
      -H "Content-Type: application/json" \
      -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
    ```
  </Step>

  <Step title="Connect to Claude.ai">
    1. Go to **Claude.ai** > **Settings** > **Integrations**
    2. Click **Add custom connector**
    3. Paste your server URL: `https://mcp.yourdomain.com/mcp?token=YOUR_MCP_SECRET`
    4. Save and start a new conversation

    Try asking: *"What devices are on my Tailscale network?"* — Claude should call `tailscale_status` and list your devices.

    See [Connecting to Claude](/reacher/connecting-to-claude) for full instructions and troubleshooting.
  </Step>
</Steps>

***

## Next steps

<CardGroup>
  <Card title="Connect to Claude" icon="plug" href="/reacher/connecting-to-claude">
    Step-by-step instructions for adding the connector in Claude.ai settings.
  </Card>

  <Card title="Tools reference" icon="wrench" href="/reacher/tools/overview">
    Learn what each tool does and how to use it effectively.
  </Card>

  <Card title="Configuration" icon="sliders" href="/reacher/configuration/environment-variables">
    Full reference for all environment variables and YAML config options.
  </Card>

  <Card title="Safety settings" icon="shield" href="/reacher/operations/safety">
    Configure blocked commands, directory restrictions, and audit logging.
  </Card>
</CardGroup>


# browser
Source: https://docs.ouim.me/reacher/tools/browser

CDP-based headless browser control via the agent-browser CLI — navigate, click, fill, and snapshot.

`browser` controls a headless browser by running `agent-browser` CLI commands. It connects to any CDP-compatible browser (such as [Lightpanda](https://github.com/lightpanda-io/browser)) over the Chrome DevTools Protocol WebSocket interface.

`agent-browser` maintains its own daemon session between calls, so a `navigate` in one call and a `click` in the next operate on the same browser state.

## Prerequisites

<Steps>
  <Step title="Install agent-browser">
    Install the `agent-browser` CLI globally on the server where Reacher is deployed:

    ```bash theme={null}
    npm install -g agent-browser
    ```
  </Step>

  <Step title="Start a CDP-compatible browser">
    Run a CDP-compatible browser and expose its WebSocket debugger. Lightpanda is a lightweight option:

    ```bash theme={null}
    lightpanda serve --host 127.0.0.1 --port 9222
    ```

    Any Chromium-based browser launched with `--remote-debugging-port=9222` also works.
  </Step>

  <Step title="Configure Reacher (optional)">
    By default Reacher connects to `ws://127.0.0.1:9222`. Override with environment variables if your browser is on a different host or port:

    ```bash theme={null}
    BROWSER_CDP_HOST=127.0.0.1
    BROWSER_CDP_PORT=9222
    ```
  </Step>
</Steps>

## Parameters

<ParamField type="string">
  An `agent-browser` command string. The tool parses this into arguments respecting quoted strings before passing to the CLI.

  Supported commands:

  * `open <url>` — navigate to a URL
  * `snapshot -i` — take an accessibility/DOM snapshot of the current page
  * `click @<elementId>` — click an element by its agent-browser element ID
  * `fill @<elementId> <value>` — fill a form field with a value
  * `close` — close the current page/session

  Example values: `"open https://example.com"`, `"snapshot -i"`, `"click @e2"`, `"fill @e3 hello world"`
</ParamField>

## Configuration

| Variable           | Default     | Description                        |
| ------------------ | ----------- | ---------------------------------- |
| `BROWSER_CDP_HOST` | `127.0.0.1` | Host of the CDP-compatible browser |
| `BROWSER_CDP_PORT` | `9222`      | WebSocket debugger port            |

The tool connects to `ws://<BROWSER_CDP_HOST>:<BROWSER_CDP_PORT>` and passes it to `agent-browser` via the `--cdp` flag.

## Return value

<ResponseField name="success" type="boolean">
  `true` if `agent-browser` exited with code 0.
</ResponseField>

<ResponseField name="command" type="string">
  The command string that was executed.
</ResponseField>

<ResponseField name="stdout" type="string">
  Trimmed standard output from `agent-browser`. For `snapshot`, this contains the page's accessibility tree or DOM representation.
</ResponseField>

<ResponseField name="stderr" type="string">
  Trimmed standard error output. If `agent-browser` is not installed, this will contain a helpful installation message.
</ResponseField>

<ResponseField name="exitCode" type="number">
  Process exit code from `agent-browser`. `0` means success.
</ResponseField>

## Usage examples

<CodeGroup>
  ```json Navigate to a page theme={null}
  {
    "command": "open https://example.com"
  }
  ```

  ```json Snapshot the current page theme={null}
  {
    "command": "snapshot -i"
  }
  ```

  ```json Click an element theme={null}
  {
    "command": "click @e5"
  }
  ```

  ```json Fill a form field theme={null}
  {
    "command": "fill @e3 user@example.com"
  }
  ```

  ```json Close the browser session theme={null}
  {
    "command": "close"
  }
  ```
</CodeGroup>

## Common use cases

**Scrape a page**

Navigate to a URL, take a snapshot to see the page structure, then extract the relevant content from `stdout`.

```
1. open https://status.myservice.com
2. snapshot -i
```

**Fill and submit a form**

Navigate to a page, take a snapshot to discover element IDs, then fill and submit the form.

```
1. open https://app.example.com/login
2. snapshot -i          ← read element IDs from output
3. fill @e2 myusername
4. fill @e3 mypassword
5. click @e4            ← submit button
6. snapshot -i          ← verify logged-in state
```

**Take a visual snapshot for monitoring**

Navigate to a dashboard or status page and snapshot it to check current state as part of an automated check.

**Automate repetitive web tasks**

Sequence multiple commands across calls to automate multi-step flows — the `agent-browser` daemon preserves session state between tool calls.

<Warning>
  The `agent-browser` binary must be installed on the server where Reacher runs, not on the machine Claude is accessed from. If it's missing, `stderr` will contain: `agent-browser binary not found. Run npm install -g agent-browser on the server where Reacher is deployed.`
</Warning>


# fetch_external
Source: https://docs.ouim.me/reacher/tools/fetch-external

Authenticated HTTP proxy with per-domain token injection — add any API with one line in your config.

`fetch_external` is Reacher's general-purpose HTTP proxy. It forwards requests to external APIs, automatically injecting the right authentication token based on the target domain. Tokens stay on the server — Claude never sees them.

This is the core insight behind Reacher's design: Claude already knows REST APIs. It doesn't need a dedicated tool for GitHub, Linear, or Notion. It needs a way to call those APIs with your credentials. `fetch_external` is that mechanism.

```
PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app,api.notion.com
```

That's three API integrations. One tool.

## Prerequisites

* The target domain must be listed in `PROXY_ALLOWED_DOMAINS` (comma-separated)
* For authenticated APIs, add the domain-to-token mapping in `FETCH_EXTERNAL_TOKEN_MAP`

```bash theme={null}
# .env
PROXY_ALLOWED_DOMAINS=api.github.com,api.linear.app
FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN","api.linear.app":"LINEAR_TOKEN"}
GITHUB_TOKEN=ghp_xxxxxxxxxxxx
LINEAR_TOKEN=lin_api_xxxxxxxxxxxx
```

When a request hits `api.github.com`, the tool looks up `"api.github.com"` in `FETCH_EXTERNAL_TOKEN_MAP`, finds `"GITHUB_TOKEN"`, reads that env var, and injects `Authorization: Bearer ghp_xxx` automatically.

## Parameters

<ParamField type="string">
  The full URL to fetch. Must be a valid URL including scheme (e.g. `https://api.github.com/user`).
</ParamField>

<ParamField type="string">
  HTTP method. Accepted values: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`. Defaults to `GET`.
</ParamField>

<ParamField type="object">
  Request body for `POST`, `PUT`, and `PATCH` requests. Serialized as JSON. `Content-Type: application/json` is added automatically if not already present.
</ParamField>

<ParamField type="object">
  Additional headers to include in the request. Merged with any injected auth headers. If you specify `Authorization` here it will be overridden by the injected token for the domain.
</ParamField>

## Return value

<ResponseField name="success" type="boolean">
  `true` if the HTTP response status was in the 2xx range (`response.ok`).
</ResponseField>

<ResponseField name="status" type="number">
  HTTP status code returned by the upstream server.
</ResponseField>

<ResponseField name="statusText" type="string">
  HTTP status text (e.g. `"OK"`, `"Not Found"`).
</ResponseField>

<ResponseField name="headers" type="object">
  Response headers as a key-value object.
</ResponseField>

<ResponseField name="body" type="object | string">
  Parsed response body. JSON responses are returned as a parsed object. All other content types are returned as a string.
</ResponseField>

<ResponseField name="url" type="string">
  The URL that was fetched.
</ResponseField>

## Security

When a request targets a domain not in `PROXY_ALLOWED_DOMAINS`, the tool returns immediately without making any network request:

```json theme={null}
{
  "success": false,
  "error": "Domain not allowed",
  "url": "https://evil.example.com/steal",
  "hostname": "evil.example.com"
}
```

This prevents the server from being used as a proxy to arbitrary destinations. Only explicitly allowed domains are reachable.

## Usage examples

<CodeGroup>
  ```json GitHub — get authenticated user theme={null}
  {
    "url": "https://api.github.com/user",
    "method": "GET"
  }
  ```

  ```json GitHub — list open PRs theme={null}
  {
    "url": "https://api.github.com/repos/thezem/reacher/pulls?state=open",
    "method": "GET"
  }
  ```

  ```json Linear — create an issue theme={null}
  {
    "url": "https://api.linear.app/graphql",
    "method": "POST",
    "body": {
      "query": "mutation { issueCreate(input: { title: \"Fix the thing\", teamId: \"TEAM_ID\" }) { success } }"
    }
  }
  ```

  ```json Notion — query a database theme={null}
  {
    "url": "https://api.notion.com/v1/databases/DATABASE_ID/query",
    "method": "POST",
    "headers": {
      "Notion-Version": "2022-06-28"
    },
    "body": {
      "filter": {
        "property": "Status",
        "select": { "equals": "In Progress" }
      }
    }
  }
  ```
</CodeGroup>

<Tip>
  For GitHub-specific searches (PRs by author, commits by date), use the dedicated `github_search` tool. It returns clean minimal output optimized for that use case.
</Tip>


# gist_kb
Source: https://docs.ouim.me/reacher/tools/gist-kb

Persistent knowledge base backed by private GitHub Gists, namespaced with the cc-- prefix.

`gist_kb` gives Claude a persistent, writable memory store that survives across conversations. It wraps the GitHub Gist API, storing each entry as a private gist with a `cc--` filename prefix to namespace all Reacher-managed content.

Unlike in-context memory, entries written to `gist_kb` are available in any future session — no need to re-establish context, re-discover devices, or re-paste configuration.

## How it works

Each entry is a private GitHub Gist where the main file's name starts with `cc--`. The prefix is enforced automatically — if you pass `title: "device-map"`, the gist file is created as `cc--device-map`. This namespacing ensures `list` only returns Reacher-managed entries and never clutters other gists.

Operations map directly to GitHub Gist API calls:

* `list` — paginate all gists and filter to those with `cc--` files
* `get` — fetch the full content of a gist by ID
* `create` — create a new private gist
* `update` — patch an existing gist's file content
* `delete` — delete a gist permanently

<Note>
  Requires `GITHUB_TOKEN` with the `gist` OAuth scope.
</Note>

## Parameters

<ParamField type="string">
  The operation to perform. One of: `"list"`, `"get"`, `"create"`, `"update"`, `"delete"`.
</ParamField>

<ParamField type="string">
  Gist ID. Required for `get`, `update`, and `delete`. Obtain from a `list` or `create` response.
</ParamField>

<ParamField type="string">
  Filename without the `cc--` prefix — the tool adds it automatically. Required for `create` and `update`. Example: `"device-map"` creates a file named `cc--device-map`.
</ParamField>

<ParamField type="string">
  File content as a string. Required for `create` and `update`.
</ParamField>

<ParamField type="string">
  Optional gist description. Used in `create`. Visible in the GitHub Gists UI.
</ParamField>

## Return value

Return shape varies by action.

<ResponseField name="success" type="boolean">
  `true` on success.
</ResponseField>

**`list` response**

<ResponseField name="count" type="number">
  Number of matching gists found.
</ResponseField>

<ResponseField name="gists" type="array">
  Array of matching gist summaries.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Gist ID.</ResponseField>
    <ResponseField name="description" type="string">Gist description.</ResponseField>
    <ResponseField name="files" type="array">Array of filenames with the `cc--` prefix.</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
    <ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
  </Expandable>
</ResponseField>

**`get` response**

<ResponseField name="id" type="string">Gist ID.</ResponseField>
<ResponseField name="description" type="string">Gist description.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>
<ResponseField name="files" type="object">Key-value map of filename → file content string.</ResponseField>

**`create` response**

<ResponseField name="id" type="string">ID of the newly created gist.</ResponseField>
<ResponseField name="description" type="string">Gist description.</ResponseField>
<ResponseField name="file" type="string">Full filename including the `cc--` prefix.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>

**`update` response**

<ResponseField name="id" type="string">Gist ID.</ResponseField>
<ResponseField name="file" type="string">Full filename including the `cc--` prefix.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>

**`delete` response**

<ResponseField name="id" type="string">ID of the deleted gist.</ResponseField>
<ResponseField name="deleted" type="boolean">`true` on successful deletion.</ResponseField>

## Usage examples

<CodeGroup>
  ```json Save a device map theme={null}
  {
    "action": "create",
    "title": "device-map",
    "content": "homelab: home NAS and media server (linux)\nprod-server: production VPS running reacher (linux)\nwin-workstation: Windows dev machine",
    "description": "Tailscale device map"
  }
  ```

  ```json List all knowledge base entries theme={null}
  {
    "action": "list"
  }
  ```

  ```json Read a specific entry theme={null}
  {
    "action": "get",
    "id": "abc123def456"
  }
  ```

  ```json Update an existing entry theme={null}
  {
    "action": "update",
    "id": "abc123def456",
    "title": "device-map",
    "content": "homelab: home NAS and media server (linux)\nprod-server: production VPS (linux) — reacher deployed here\nwin-workstation: Windows dev machine\nnew-rpi: Raspberry Pi 4 in the office"
  }
  ```

  ```json Delete an entry theme={null}
  {
    "action": "delete",
    "id": "abc123def456"
  }
  ```
</CodeGroup>

## Common use cases

**Saving a device map after first-time setup**

After running `tailscale_status` and probing SSH access for each device, save the results. Future sessions pick up the map without re-running discovery.

**Storing project configs**

Save deploy commands, environment-specific notes, or service endpoints so they're available in any conversation without re-pasting.

**Persisting notes across conversations**

Write observations, decisions, or action items during a session. Read them back at the start of the next session to restore context.

**Bootstrapping with AGENT.MD**

The `AGENT.MD` file included in Reacher is a Claude-readable guide that instructs Claude to run `gist_kb list` at the start of each session to check for existing device maps and configs. Drop `AGENT.MD` into a new conversation to trigger automatic context restoration.

<Tip>
  Use descriptive `title` values like `"device-map"`, `"deploy-commands"`, or `"project-notes-reacher"` so `list` output is self-explanatory.
</Tip>


# github_search
Source: https://docs.ouim.me/reacher/tools/github-search

Search GitHub for pull requests or commits by author and date, with clean minimal output.

`github_search` is a focused tool for querying GitHub activity. It searches for pull requests or commits by author within a date range and returns only the essential fields — no pagination tokens, no nested objects, no raw API noise.

Unlike calling the GitHub API through `fetch_external`, this tool handles query construction, header setup (commits search requires a special `Accept` header), and response shaping automatically.

## Prerequisites

* `GITHUB_TOKEN` must be set in your environment
* `api.github.com` must be in `PROXY_ALLOWED_DOMAINS`
* The token must be configured for injection in `FETCH_EXTERNAL_TOKEN_MAP`:
  ```bash theme={null}
  PROXY_ALLOWED_DOMAINS=api.github.com
  FETCH_EXTERNAL_TOKEN_MAP={"api.github.com":"GITHUB_TOKEN"}
  GITHUB_TOKEN=ghp_xxxxxxxxxxxx
  ```

## Parameters

<ParamField type="string">
  What to search for. Must be either `"prs"` (pull requests) or `"commits"`.
</ParamField>

<ParamField type="string">
  Repository in `owner/repo` format (e.g. `"thezem/reacher"`).
</ParamField>

<ParamField type="string">
  GitHub username to filter by (e.g. `"thezem"`).
</ParamField>

<ParamField type="string">
  ISO date string. Returns items created on or after this date (e.g. `"2026-03-01"`). For commits this filters by committer date.
</ParamField>

<ParamField type="number">
  Number of results to return. Min `1`, max `100`. Defaults to `25`.
</ParamField>

## Return value

<ResponseField name="success" type="boolean">
  `true` on a successful GitHub API response.
</ResponseField>

<ResponseField name="items" type="array">
  Array of result objects. Shape depends on `type`.

  <Expandable title="PR fields (type: prs)">
    <ResponseField name="number" type="number">
      Pull request number.
    </ResponseField>

    <ResponseField name="title" type="string">
      PR title.
    </ResponseField>

    <ResponseField name="url" type="string">
      HTML URL to the PR on GitHub.
    </ResponseField>

    <ResponseField name="state" type="string">
      `"open"` or `"closed"`.
    </ResponseField>

    <ResponseField name="draft" type="boolean">
      Whether the PR is a draft.
    </ResponseField>

    <ResponseField name="merged" type="boolean">
      Whether the PR has been merged.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO date (date portion only, e.g. `"2026-03-10"`).
    </ResponseField>
  </Expandable>

  <Expandable title="Commit fields (type: commits)">
    <ResponseField name="sha" type="string">
      Short SHA (first 7 characters).
    </ResponseField>

    <ResponseField name="message" type="string">
      First line of the commit message only.
    </ResponseField>

    <ResponseField name="date" type="string">
      ISO date of the commit (date portion only, e.g. `"2026-03-10"`).
    </ResponseField>

    <ResponseField name="url" type="string">
      HTML URL to the commit on GitHub.
    </ResponseField>
  </Expandable>
</ResponseField>

## Usage examples

<CodeGroup>
  ```json Find open PRs by author theme={null}
  {
    "type": "prs",
    "repo": "thezem/reacher",
    "author": "thezem",
    "created_after": "2026-01-01"
  }
  ```

  ```json Find recent merged PRs theme={null}
  {
    "type": "prs",
    "repo": "thezem/reacher",
    "author": "thezem",
    "created_after": "2026-03-01",
    "per_page": 10
  }
  ```

  ```json Find commits this week theme={null}
  {
    "type": "commits",
    "repo": "thezem/reacher",
    "author": "thezem",
    "created_after": "2026-03-10"
  }
  ```
</CodeGroup>

## Example output

<CodeGroup>
  ```json PR results theme={null}
  {
    "success": true,
    "items": [
      {
        "number": 42,
        "title": "Add browser tool with CDP support",
        "url": "https://github.com/thezem/reacher/pull/42",
        "state": "closed",
        "draft": false,
        "merged": true,
        "created_at": "2026-03-12"
      }
    ]
  }
  ```

  ```json Commit results theme={null}
  {
    "success": true,
    "items": [
      {
        "sha": "a1b2c3d",
        "message": "fix: handle CDP connection timeout gracefully",
        "date": "2026-03-15",
        "url": "https://github.com/thezem/reacher/commit/a1b2c3d"
      }
    ]
  }
  ```
</CodeGroup>

<Note>
  The GitHub commits search API requires the `Accept: application/vnd.github.cloak-preview` header. This is handled automatically by the tool — you don't need to pass it.
</Note>


# Tools Overview
Source: https://docs.ouim.me/reacher/tools/overview

All six Reacher tools — what they do, how they're registered, and when to use each one.

Reacher exposes six tools to Claude. Each tool is a single self-contained file in `src/tools/`. They share a common registration pattern but are otherwise fully independent — no shared state, no cross-tool dependencies.

## Design philosophy

The surface area is intentional. Rather than shipping a dedicated tool for every API (GitHub, Linear, Notion, Jira…), Reacher ships one authenticated HTTP proxy — `fetch_external` — and lets you add any API by adding its domain to an allowlist. Claude already knows REST APIs. It just needs a way to call them with your credentials without you pasting tokens into every prompt.

The result is six tools that cover the full infrastructure loop:

* **Discover** your machines (`tailscale_status`)
* **Execute** commands on them (`ssh_exec`)
* **Call** any allowed API (`fetch_external`)
* **Search** GitHub activity (`github_search`)
* **Persist** knowledge across conversations (`gist_kb`)
* **Automate** web tasks (`browser`)

## Tool registration pattern

Every tool in `src/tools/*.js` exports four things:

```js theme={null}
export const name = 'tool_name'
export const description = '...'
export const schema = { param: z.string().describe('...') } // Zod shape
export async function handler(args, ...envArgs) { ... }
```

All tools are registered in `src/mcp-server.js` via `server.tool(name, description, schema, handler)`. The server wraps each handler to inject the appropriate environment variables (API keys, allowed domains) so Claude never receives them directly.

```js theme={null}
// Example from mcp-server.js
server.tool(sshExec.name, sshExec.description, sshExec.schema, async args => {
  const result = await sshExec.handler(args)
  await auditLog(sshExec.name, args, result)
  return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
})
```

Each handler receives only the env vars it needs — not the full environment — following a least-privilege principle.

## Tools summary

| Tool               | What it does                                                 | Key use case                                                 |
| ------------------ | ------------------------------------------------------------ | ------------------------------------------------------------ |
| `ssh_exec`         | Run shell commands on any Tailscale device                   | Manage servers, check logs, run deployments                  |
| `tailscale_status` | List all devices with online/offline status, IPs, OS         | Discover hostnames before SSHing, debug connectivity         |
| `fetch_external`   | Proxy HTTP requests with injected auth per domain            | Call GitHub, Jira, or any API without pasting tokens         |
| `github_search`    | Search GitHub for pull requests or commits                   | Find work by author and date range with minimal output       |
| `gist_kb`          | Read/write a private knowledge base backed by GitHub Gists   | Persist notes, configs, and context across conversations     |
| `browser`          | Control a headless browser via CDP using `agent-browser` CLI | Scrape pages, fill forms, take snapshots, automate web tasks |

## All tools

<CardGroup>
  <Card title="ssh_exec" icon="terminal" href="/tools/ssh-exec">
    Execute shell commands on remote Tailscale devices. Supports Linux and Windows (cmd/PowerShell), with a command blocklist and directory allowlist.
  </Card>

  <Card title="tailscale_status" icon="network-wired" href="/tools/tailscale-status">
    List every device in your Tailscale network with IPs, OS, online status, and last-seen time.
  </Card>

  <Card title="fetch_external" icon="globe" href="/tools/fetch-external">
    Authenticated HTTP proxy with per-domain token injection. Add any API by adding one line to your config.
  </Card>

  <Card title="github_search" icon="github" href="/tools/github-search">
    Search GitHub for pull requests or commits by author and date range, with clean minimal output.
  </Card>

  <Card title="gist_kb" icon="book" href="/tools/gist-kb">
    Persistent knowledge base backed by private GitHub Gists. Read, write, list, and delete entries across conversations.
  </Card>

  <Card title="browser" icon="browser" href="/tools/browser">
    CDP-based headless browser control via the `agent-browser` CLI. Navigate, click, fill forms, and take snapshots.
  </Card>
</CardGroup>


# ssh_exec
Source: https://docs.ouim.me/reacher/tools/ssh-exec

Execute shell commands on remote Tailscale devices — no manual SSH key setup required.

`ssh_exec` runs a shell command on a remote device over Tailscale SSH. It uses the Tailscale hostname directly — no IP addresses, no manual `known_hosts` management. The server spawns a real `ssh` process using a dedicated key mounted at `/root/.ssh/reacher-key`.

Windows targets are supported via `cmd` (default) or `powershell`. PowerShell commands are automatically encoded as Base64 UTF-16LE before being sent, which prevents quoting and escaping issues.

<Warning>
  Tailscale SSH must be explicitly enabled on each target device before this tool can connect. Run `sudo tailscale up --ssh` on the device to enable it.
</Warning>

## Parameters

<ParamField type="string">
  Tailscale hostname of the target device (e.g. `"myserver"`). Use `tailscale_status` to list available hostnames.
</ParamField>

<ParamField type="string">
  Shell command to execute on the remote device.
</ParamField>

<ParamField type="string">
  SSH user to connect as. The schema default is `hazem` (the project author's username — you will almost certainly need to override this). Always specify the correct user for your target device, e.g. `ubuntu`, `root`, or your own username.
</ParamField>

<ParamField type="string">
  Shell to use on Windows targets. Accepted values: `cmd` or `powershell`. Defaults to `cmd`. Ignored on non-Windows hosts.
</ParamField>

## Return value

<ResponseField name="success" type="boolean">
  `true` if the command exited with code 0.
</ResponseField>

<ResponseField name="hostname" type="string">
  The target hostname as provided.
</ResponseField>

<ResponseField name="user" type="string">
  The SSH user used for the connection.
</ResponseField>

<ResponseField name="command" type="string">
  The command that was executed.
</ResponseField>

<ResponseField name="shell" type="string">
  The shell used (`cmd` or `powershell`).
</ResponseField>

<ResponseField name="stdout" type="string">
  Trimmed standard output from the command.
</ResponseField>

<ResponseField name="stderr" type="string">
  Trimmed standard error output.
</ResponseField>

<ResponseField name="exitCode" type="number">
  Process exit code. `0` means success.
</ResponseField>

<ResponseField name="blocked" type="boolean">
  Present and `true` when the command was blocked by a safety rule. Also includes `reason` and `matched_rule` fields.
</ResponseField>

<ResponseField name="dry_run" type="boolean">
  Present and `true` when `DRY_RUN=true` is set. Includes a `would_execute` field instead of running the command.
</ResponseField>

## Usage examples

<CodeGroup>
  ```json Check disk usage theme={null}
  {
    "hostname": "homelab",
    "command": "df -h /"
  }
  ```

  ```json Tail application logs theme={null}
  {
    "hostname": "prod-server",
    "command": "tail -n 50 /var/log/myapp/app.log"
  }
  ```

  ```json List running processes theme={null}
  {
    "hostname": "prod-server",
    "command": "ps aux --sort=-%cpu | head -20"
  }
  ```

  ```json Run a deployment script theme={null}
  {
    "hostname": "deploy-box",
    "command": "/home/deploy/scripts/deploy.sh"
  }
  ```

  ```json PowerShell on Windows theme={null}
  {
    "hostname": "win-workstation",
    "command": "Get-Process | Sort-Object CPU -Descending | Select-Object -First 10",
    "shell": "powershell"
  }
  ```
</CodeGroup>

## Safety considerations

Reacher enforces two optional safety layers configured in `reacher.config.yaml`:

### Command blocklist

`ssh.blocked_commands` is a list of substrings. If any blocked string appears in the command (case-insensitive), the tool returns immediately with `success: false` and `blocked: true` — the SSH connection is never made.

```yaml theme={null}
ssh:
  blocked_commands:
    - 'rm -rf'
    - 'shutdown'
    - 'reboot'
```

### Directory allowlist

`ssh.allowed_dirs` restricts SSH operations to specific paths. The tool parses path tokens from the command (tokens starting with `/`, `~`, or `./`) and checks each one against the list. An empty list means no restriction.

```yaml theme={null}
ssh:
  allowed_dirs:
    - /home/deploy
    - /var/log/myapp
```

### Dry-run mode

Set `DRY_RUN=true` to have `ssh_exec` evaluate safety rules and return a `would_execute` response without making any SSH connection. Useful for testing configurations.

<Note>
  All tool calls are written to `reacher-audit.log` with timestamp, arguments, and result. Sensitive keys are stripped automatically.
</Note>

## Common use cases

* **Check logs** — `tail`, `journalctl`, `cat` on log files
* **Inspect processes** — `ps`, `top`, `htop` snapshots
* **Run deployments** — trigger deploy scripts, `git pull`, `docker compose up`
* **System health** — `df`, `free`, `uptime`, `systemctl status`
* **File inspection** — read configs, check file permissions, list directory contents

<Tip>
  Run `tailscale_status` first to discover available hostnames and verify a device is online before attempting SSH.
</Tip>


# tailscale_status
Source: https://docs.ouim.me/reacher/tools/tailscale-status

List all devices in your Tailscale network with IPs, OS, online status, and last-seen time.

`tailscale_status` queries the Tailscale API and returns every device enrolled in your tailnet. It separates devices into online and offline, and returns key metadata for each one.

This tool is the natural starting point for any SSH workflow — use it to discover available hostnames before calling `ssh_exec`, or to debug why a device isn't reachable.

<Note>
  Requires `TAILSCALE_API_KEY` to be set in your environment. Generate a key at [tailscale.com/admin/settings/keys](https://tailscale.com/admin/settings/keys).
</Note>

## Parameters

This tool takes no parameters. It fetches your entire tailnet automatically.

## Return value

<ResponseField name="success" type="boolean">
  Always `true` on a successful API call.
</ResponseField>

<ResponseField name="summary" type="object">
  Aggregate counts for the tailnet.

  <Expandable title="properties">
    <ResponseField name="total" type="number">
      Total number of devices enrolled.
    </ResponseField>

    <ResponseField name="online" type="number">
      Number of devices currently online.
    </ResponseField>

    <ResponseField name="offline" type="number">
      Number of devices currently offline.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="devices" type="array">
  Array of device objects, one per enrolled device.

  <Expandable title="properties">
    <ResponseField name="name" type="string">
      Full device name as registered in Tailscale (includes tailnet domain suffix).
    </ResponseField>

    <ResponseField name="hostname" type="string">
      Short hostname of the device. Use this value as the `hostname` parameter in `ssh_exec`.
    </ResponseField>

    <ResponseField name="status" type="string">
      Either `"online"` or `"offline"`.
    </ResponseField>

    <ResponseField name="os" type="string">
      Operating system reported by Tailscale (e.g. `linux`, `windows`, `macOS`).
    </ResponseField>

    <ResponseField name="ips" type="array">
      Array of Tailscale IP addresses assigned to the device.
    </ResponseField>

    <ResponseField name="clientVersion" type="string">
      Tailscale client version running on the device.
    </ResponseField>

    <ResponseField name="lastSeen" type="string">
      ISO 8601 timestamp of when the device was last seen by the Tailscale coordination server.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example output

```json theme={null}
{
  "success": true,
  "summary": {
    "total": 4,
    "online": 3,
    "offline": 1
  },
  "devices": [
    {
      "name": "homelab.tail1234.ts.net",
      "hostname": "homelab",
      "status": "online",
      "os": "linux",
      "ips": ["100.64.0.1"],
      "clientVersion": "1.58.2-t8b4a2e60f-g4b2e60f",
      "lastSeen": "2026-03-18T10:22:00Z"
    },
    {
      "name": "win-workstation.tail1234.ts.net",
      "hostname": "win-workstation",
      "status": "online",
      "os": "windows",
      "ips": ["100.64.0.2"],
      "clientVersion": "1.58.2",
      "lastSeen": "2026-03-18T10:21:45Z"
    },
    {
      "name": "old-vps.tail1234.ts.net",
      "hostname": "old-vps",
      "status": "offline",
      "os": "linux",
      "ips": ["100.64.0.3"],
      "clientVersion": "1.52.0",
      "lastSeen": "2026-02-10T08:00:00Z"
    }
  ]
}
```

## Common use cases

**Discover hostnames before SSH**

Call `tailscale_status` at the start of a session to build a map of available devices. The `hostname` field is what you pass directly to `ssh_exec`.

**Check online status before running commands**

If `ssh_exec` fails to connect, `tailscale_status` will show whether the device is offline vs. a real SSH configuration problem.

**Audit your network**

Spot devices running old client versions (`clientVersion`), identify machines that haven't been seen recently (`lastSeen`), or verify a new device enrolled successfully.

**Save a device map to the knowledge base**

After discovering your devices, use `gist_kb` to save the hostname-to-purpose mapping so future sessions don't need to re-run discovery.

```json theme={null}
// Follow-up gist_kb call to save the device map
{
  "action": "create",
  "title": "device-map",
  "content": "homelab: home NAS and media server\nprod-server: production VPS\nwin-workstation: Windows dev machine",
  "description": "Tailscale device map"
}
```