npm package: @gzl10/nexus-plugin-pocketid
Description: PocketID OIDC authentication provider plugin for Nexus
Author: G10 Labs
Latest version: 0.1.2

# @gzl10/nexus-plugin-pocketid

PocketID authentication plugin for [Nexus BaaS](https://gitlab.gzl10.com/oss/nexus). Adds passwordless login via passkeys using [Pocket ID](https://pocket-id.org) as OIDC provider.

## Features

- OIDC Authorization Code Flow with PKCE
- Auto-registration or manual account linking
- Email domain allowlist
- SCIM 2.0 provisioning (users & groups)

## Requirements

- `@gzl10/nexus-backend` >= 0.13.0
- `@gzl10/nexus-sdk` >= 0.13.0
- A running [Pocket ID](https://pocket-id.org) instance

## Installation

```bash
pnpm add @gzl10/nexus-plugin-pocketid
```

## 1. Configure Pocket ID

In the Pocket ID admin panel:

1. Go to **OIDC Clients** > **Create Client**
2. Set **Name**: `my-app` (or whatever you prefer)
3. Add **Redirect URI**: `https://your-backend.com/api/v1/pocketid_auth/callback`
4. Note the **Client ID** and **Client Secret**

> The redirect URI must point to your Nexus backend's callback endpoint, not the frontend.

## 2. Configure Nexus

Add environment variables:

```env
POCKETID_URL=https://auth.example.com
POCKETID_CLIENT_ID=your-client-id
POCKETID_CLIENT_SECRET=your-client-secret
```

Register the plugin in your backend:

```typescript
import { start } from '@gzl10/nexus-backend'
import { pocketIdPlugin } from '@gzl10/nexus-plugin-pocketid'

await start({ plugins: [pocketIdPlugin] })
```

On first start, the plugin auto-seeds its configuration from the environment variables.

## 3. Frontend

The plugin registers an auth provider that nexus-ui picks up automatically. A "Sign in with PocketID" button appears on the login page.

For custom frontends, redirect users to:

```
GET /api/v1/pocketid_auth/authorize?redirect_uri=https://your-frontend.com/login
```

After authentication, the backend redirects back with tokens in the URL fragment:

```
https://your-frontend.com/login#accessToken=...&refreshToken=...
```

On error:

```
https://your-frontend.com/login#error=Your+account+does+not+exist
```

## Configuration

The plugin creates a `pocketid_config` table on first run. Options:

| Field | Default | Description |
|-------|---------|-------------|
| `enabled` | `true` | Enable/disable PocketID login |
| `default_role` | `VIEWER` | Role assigned to new users |
| `allowed_domains` | `null` | JSON array of allowed email domains (null = all) |
| `scopes` | `openid profile email` | OIDC scopes |

## API Endpoints

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| GET | `/api/v1/pocketid_auth/authorize` | No | Start OIDC flow |
| GET | `/api/v1/pocketid_auth/callback` | No | Handle OIDC callback |
| GET | `/api/v1/pocketid_auth/link` | Yes | Link existing account |
| GET | `/api/v1/pocketid_auth/status` | Yes | Check if PocketID is linked |

### SCIM 2.0

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/v1/scim/ServiceProviderConfig` | SCIM capabilities |
| GET | `/api/v1/scim/Schemas` | User & Group schemas |
| GET/POST | `/api/v1/scim/Users` | List / create users |
| GET/PUT/PATCH/DELETE | `/api/v1/scim/Users/:id` | Manage user |
| GET/POST | `/api/v1/scim/Groups` | List / create groups |
| GET/PUT/PATCH/DELETE | `/api/v1/scim/Groups/:id` | Manage group |

SCIM endpoints require Bearer token authentication configured in `pocketid_scim_config`.

## License

MIT