# Authentication API

Milestone 3 uses first-party authentication only. Cairnquire does not implement OAuth in v1.

## Browser Sessions

Browser users authenticate with passkeys or password fallback. Successful login sets an opaque `cairnquire_session` cookie. The raw session token is never stored; the database stores a SHA-256 hash and revocation metadata.

Endpoints:

- `GET /setup`
- `POST /api/setup`
- `GET /login`
- `GET /password-reset?token=...`
- `GET /account`
- `GET /account/tokens/new`
- `POST /api/auth/register/password`
- `POST /api/auth/login/password`
- `POST /api/auth/password/reset`
- `POST /api/auth/logout`
- `GET /api/auth/me`
- `POST /api/auth/password/change`
- `DELETE /api/auth/account`
- `POST /api/auth/passkeys/register/begin`
- `POST /api/auth/passkeys/register/finish?challengeId=...`
- `POST /api/auth/passkeys/login/begin`
- `POST /api/auth/passkeys/login/finish?challengeId=...`

On an empty database, the one-time `/setup` wizard creates the first `admin`
account and records whether public signup is enabled. Later public
registrations are accepted only when that setting is enabled and always become
`viewer`; role changes are admin-managed from the account screen. Public
registration endpoints only create new accounts. Adding or changing
credentials on an existing account requires an authenticated browser session.

## API Tokens

Developer clients use bearer tokens:

```http
Authorization: Bearer cq_pat_<id>_<secret>
```

The token is shown once. The server stores the token id and SHA-256 hash of the secret. Tokens can be scoped and revoked. Browser users create tokens at `/account/tokens/new`.

Endpoints:

- `GET /api/tokens`
- `POST /api/tokens`
- `DELETE /api/tokens/{id}`

Supported scopes:

- `docs:read`
- `docs:write`
- `sync:read`
- `sync:write`
- `admin`

Authorization is role plus scope: a token must have the required scope, and the owning user role must allow that operation.

## Account Administration

Administrators update user roles and disabled-account state in one bulk form.
Disabled accounts cannot authenticate with passwords, passkeys, existing
sessions, or API tokens. At least one enabled administrator account must remain.

Administrators can send a password-reset email to a user who cannot log in.
Each click creates a fresh one-hour link and invalidates that user's earlier
unused reset links. Completing a reset changes the password, consumes the link,
and revokes the user's existing browser sessions.

Endpoints:

- `PATCH /api/admin/auth-users`
- `POST /api/admin/auth-users/{id}/password-reset`
- `GET /password-reset?token=...`
- `POST /api/auth/password/reset`

## Device Flow

CLI clients can avoid handling browser cookies by using the first-party device flow:

1. Client calls `POST /api/device/start`.
2. Server returns `deviceCode`, `userCode`, `verificationUri`, and polling interval.
3. User opens the verification URL in a browser and signs in normally.
4. User approves the code with `POST /api/device/approve`.
5. Client polls `POST /api/device/token`.
6. Server returns a normal bearer API token and consumes the device code.

This is intentionally inspired by OAuth device authorization, but it is not a general OAuth provider. There are no client registrations, redirect URIs, refresh tokens, consent screens, or third-party identity dependencies.

## Route Protection

- Setup-only until configured: initial setup page and endpoint.
- Public: health, static assets, document reads, login and password-reset pages, password/passkey begin-login/register endpoints when signups are enabled, password-reset submission, device start/token polling.
- Authenticated browser pages: account management and token creation screens.
- Session or bearer token required: auth profile/logout, edit/save APIs, uploads, sync/content APIs, device approval.
- Admin role required: admin APIs and API token management.

WebSocket authentication is session/bearer aware through the shared middleware model. API token creation and account management require a browser session so bearer tokens cannot mint more bearer tokens.