npm package: @nodeops-createos/integration-oauth
Description: NodeOps PKCE OAuth 2.0 for Next.js
Latest version: 0.0.3

# @nodeops-createos/integration-oauth

NodeOps PKCE OAuth 2.0 authentication for Next.js (App Router).

## Quick Setup via Claude Code

The fastest way to add auth — install the package and let Claude handle the rest:

```bash
npm install @nodeops-createos/integration-oauth
```

After install, a Claude Code skill is automatically added to your project. Open Claude Code and say:

> **"add auth"**

Claude will create all the required files and remind you to fill in your env vars.

---

## Manual Setup

If you prefer to set things up yourself, follow the steps below.

### 1. Install

```bash
npm install @nodeops-createos/integration-oauth
# or
pnpm add @nodeops-createos/integration-oauth
# or
yarn add @nodeops-createos/integration-oauth
```

### 2. Create the API routes

Create two route files:

`app/api/auth/me/route.ts`:

```ts
export { GET } from '@nodeops-createos/integration-oauth/server/me';
```

`app/api/auth/token/route.ts`:

```ts
export { POST } from '@nodeops-createos/integration-oauth/server/token';
```

### 3. Wrap your layout

In `app/layout.tsx`, import `AuthProvider` and wrap `{children}`:

```tsx
import { AuthProvider } from '@nodeops-createos/integration-oauth';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <AuthProvider>{children}</AuthProvider>
      </body>
    </html>
  );
}
```

### 4. Create the callback page

Create `app/callback/page.tsx`:

```tsx
"use client";
import { useCallbackHandler } from "@nodeops-createos/integration-oauth";

export default function Callback() {
  const { loading, error } = useCallbackHandler({ redirectTo: "/dashboard" });

  if (loading) return (
    <div style={{ display: "flex", justifyContent: "center", alignItems: "center", height: "100vh" }}>
      <p>Signing in...</p>
    </div>
  );
  if (error) return <p>Login failed: {error}</p>;
  return null;
}
```

### 5. Add environment variables

Create a `.env.local` file at your project root:

```env
# Client-side (exposed to browser)
NEXT_PUBLIC_NODEOPS_AUTH_URL=https://id.nodeops.network/oauth2/auth
NEXT_PUBLIC_NODEOPS_CLIENT_ID=your_client_id_here
NEXT_PUBLIC_NODEOPS_REDIRECT_URI=http://localhost:3000/callback
NEXT_PUBLIC_NODEOPS_SCOPES=offline_access offline openid

# Server-side only (never sent to browser)
NODEOPS_CLIENT_SECRET=your_client_secret_here
NODEOPS_TOKEN_URL=https://id.nodeops.network/oauth2/token
NODEOPS_USERINFO_URL=https://autogen-v2-api.nodeops.network/v1/users/me
```

Get your `NEXT_PUBLIC_NODEOPS_CLIENT_ID` and `NODEOPS_CLIENT_SECRET` from the [NodeOps developer portal](https://nodeops.network).

---

## Usage

### `useAuth()`

Access auth state and actions from any client component:

```tsx
"use client";
import { useAuth } from "@nodeops-createos/integration-oauth";

export default function Navbar() {
  const { isAuthenticated, loading, login, logout } = useAuth();

  if (loading) return null;

  return isAuthenticated
    ? <button onClick={logout}>Sign out</button>
    : <button onClick={login}>Sign in</button>;
}
```

### `useUser()`

Get the current user's profile:

```tsx
"use client";
import { useUser } from "@nodeops-createos/integration-oauth";

export default function Profile() {
  const { user, loading } = useUser();

  if (loading) return <p>Loading...</p>;
  if (!user) return <p>Not signed in</p>;

  return <p>Hello, {user.displayName}</p>;
}
```

### `useCallbackHandler(options)`

Handles the OAuth callback — call it on your `/callback` page.

| Option | Type | Default | Description |
|---|---|---|---|
| `redirectTo` | `string` | `"/dashboard"` | Where to redirect after successful login |
| `onSuccess` | `() => void` | — | Custom success handler (overrides `redirectTo`) |
| `onError` | `(err: string) => void` | — | Called when login fails |

Returns `{ loading: boolean, error: string \| null }`.

---

## API Reference

### Exports from `@nodeops-createos/integration-oauth`

| Export | Type | Description |
|---|---|---|
| `AuthProvider` | Component | Wrap your layout with this |
| `useAuth` | Hook | Auth state + login/logout |
| `useUser` | Hook | Current user profile |
| `useCallbackHandler` | Hook | Handles OAuth callback |
| `startLogin` | Function | Imperatively start login flow |
| `getTokens` | Function | Read stored tokens |
| `setTokens` | Function | Write tokens to storage |
| `clearTokens` | Function | Remove tokens from storage |

### Exports from `@nodeops-createos/integration-oauth/server/me`

| Export | Description |
|---|---|
| `GET` | Next.js route handler — fetches user info |

### Exports from `@nodeops-createos/integration-oauth/server/token`

| Export | Description |
|---|---|
| `POST` | Next.js route handler — exchanges auth code for tokens |

---

## How it works

1. `login()` generates a PKCE code verifier + challenge and redirects to the NodeOps auth server
2. After the user authenticates, they are redirected to `/callback` with a `code` param
3. `useCallbackHandler` sends the code and verifier to `POST /api/auth/token`
4. The server exchanges them for tokens (keeping `client_secret` server-side)
5. Tokens are stored in `localStorage` and the user is redirected to your app

## Requirements

- Next.js 14 or later (App Router)
- React 18 or later