# @clivly/auth-workos

[WorkOS](https://workos.com) implementation of Clivly's `ClivlyAuthAdapter`.
Unseals the host app's AuthKit session cookie to resolve a CRM end-user's
identity.

It answers **"who is this person?"** only. CRM authorization lives separately in
Clivly's `crm_members` layer.

> **Preview-quality surface.** The user mapper, cookie reader, and session
> resolution are unit-tested; broader host-app compatibility coverage is still
> growing.

> **Optional.** You do not need an auth adapter to sync data into Clivly. Only
> reach for one when a Clivly surface must resolve which of *your* users is
> making a request.

This adapter does not participate in sync scheduling or presence transport.

## Prerequisites

| Requirement | Version / note |
| --- | --- |
| Node.js | **≥ 22** |
| `@workos-inc/node` | **≥ 7** — a peer dependency you install yourself |
| WorkOS credentials | API key, client ID, and the AuthKit cookie password |

## Installation

Two equivalent import paths — pick whichever matches how you installed Clivly:

```bash
# If you already installed `clivly` (recommended — this is what `clivly init` does)
npm install @workos-inc/node
# → import from "clivly/auth/workos"

# Or standalone
npm install @clivly/auth-workos @workos-inc/node
# → import from "@clivly/auth-workos"
```

## Quick start

```ts
import { createWorkOSAuthAdapter } from "clivly/auth/workos";

const authAdapter = createWorkOSAuthAdapter({
  apiKey: process.env.WORKOS_API_KEY!,
  clientId: process.env.WORKOS_CLIENT_ID!,
  cookiePassword: process.env.WORKOS_COOKIE_PASSWORD!,
});

const user = await authAdapter.getUser(request); // { id, email, name } | null
```

## Options

| Option | Type | Required | Notes |
| --- | --- | --- | --- |
| `apiKey` | `string` | Yes | WorkOS API key (`sk_…`) |
| `clientId` | `string` | Yes | WorkOS client ID (`client_…`) |
| `cookiePassword` | `string` | Yes | Password used to unseal the AuthKit session cookie |
| `cookieName` | `string` | No | Session cookie name. Defaults to `wos-session` |

## Behaviour

- Reads the sealed AuthKit session cookie from the incoming request and unseals
  it with `cookiePassword`.
- Returns `null` when the cookie is absent, cannot be unsealed, or the session
  user has no email address (Clivly requires one).
- `workosUserToClivlyUser` is exported separately if you already hold a WorkOS
  user object and only need the mapping.

## Related documentation

- **[Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md#auth-adapters-optional)** — where auth adapters fit in the setup
- [`@clivly/core` README](https://github.com/amani-joseph/clivly.com/blob/master/packages/core/README.md) — the `ClivlyAuthAdapter` contract
- [`clivly` CLI README](https://github.com/amani-joseph/clivly.com/blob/master/packages/cli/README.md)

## License

MIT