Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,42 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version
- The backend's OpenAPI watcher no longer runs mypy on every save (it took longer than the reload) and leaves
`openapi.json` alone when the schema hasn't changed, so the frontend doesn't regenerate its client for nothing.

- **OAuth sign-in for API and MCP clients.** Apps can sign people in with their Lens account instead of asking them
for a key: Lens is an OAuth 2.1 authorization server with PKCE (S256, required), dynamic client registration
(RFC 7591) and discovery (`/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`), as MCP
clients expect. Decided with the project owner: Lens issues the tokens itself; they carry the person's roles and
last as long as the token-lifetime settings say; no account is created through OAuth.
- API: `POST /api/v1/oauth/register`, `GET`/`POST …/authorize` (the consent page's question and answer),
`POST …/token` (authorization code and refresh token; refresh tokens rotate, and one that comes back after it
was swapped ends the access), `POST …/revoke`, `GET …/grants` and `DELETE …/grants/{id}`; new `oauth_client`,
`oauth_code`, `oauth_grant` and `oauth_token` tables, holding only hashes of codes, tokens and app secrets
(docs/authentication.md#oauth, docs/api.md#oauth). The bearer path takes an app's access token (`lo_…`) next to
sessions and API keys; `GET /auth/me` says `via: "oauth"`. Audited as `oauth.client.register`, `oauth.grant`
and `oauth.revoke`.
- An app asks for `read` or `read write`, and the person may give read only. An admin's app has the admin's roles
in every namespace but can't administer the archive (people, settings, the audit log, everyone's keys).
- New settings (Settings → API keys, docs/configuration.md#api-keys): `tokens.oauth_access_minutes` (60) and
`tokens.oauth_refresh_days` (30, at most `tokens.max_days`).
- Redirect addresses are https, this machine's (any port) or the app's own scheme; ones with a user name or a
backslash in them, and the browser's and the system's own schemes, are refused. Discovery names the web app's
address only as a trusted proxy reports it, else `FRONTEND_URL`.
- Web app: the consent page at `/oauth/authorize` (signing in first when needed) names the app, where it returns
you to and what it asks for, with Allow and Deny; API tokens → Apps with access lists the apps you allowed,
with Revoke; `/.well-known/…` is served on the web app's address too. The web app now passes the address the
browser used (its `Host`, or what a reverse proxy in front reports) on to the API.
- A code that comes back after it was swapped ends the access it gave; a rotated refresh token that comes back
within a minute is refused without ending anything. Expired codes are swept. A 401 asking for a token names the
protected resource metadata (`WWW-Authenticate: Bearer resource_metadata="…"`). The consent page can't be framed.
- The web app passes a browser's own `X-Forwarded-Host` and `-Proto` on to the API only with
`TRUST_PROXY_HEADERS=true` (a reverse proxy in front sets them); otherwise it reports the `Host` it was sent.
- Checked in the browser, playing the app: it finds the endpoints on the web app's address and registers; a
signed-out viewer is sent to sign in and comes back to the consent page, switches "Make changes" off and
allows; the app gets its code with its state, swaps it for tokens that have the viewer's one role, and renews
them; on a phone in dark mode the viewer sees the app under Apps with access and revokes it, and its token
stops working; a request with an address the app didn't register says so and sends nobody anywhere; an admin
in dark mode denies (the app hears `access_denied`), then allows: the app reads resources and can't read the
audit log; Settings → API keys shows the two lifetimes. No console errors besides the 400 of the refused
request.
- **Fixes for the Docker stacks.** From running `make dev` on an Apple Silicon Mac with Colima and reading its logs.
- `make` finds Compose by itself: `docker compose`, or the standalone `docker-compose` where there's no `docker`
plugin (Colima, Podman); `DOCKER_COMPOSE=…` still chooses.
Expand Down
41 changes: 40 additions & 1 deletion docs/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

The API lives under `/api/v1`. Interactive docs with every request and response schema are at `/docs` (Swagger UI) and `/redoc` on the backend; the schema at `/openapi.json` generates the frontend's typed client (one class per tag, e.g. `Recordings.getRecording`).

Authenticate with `Authorization: Bearer <token>`: an access token from `POST /api/v1/auth/login`, or an API token (`la_…`). See [Authentication](authentication.md). Errors are JSON `{"detail": …}`; validation errors answer 422. Namespaces you can't read answer 404.
Authenticate with `Authorization: Bearer <token>`: an access token from `POST /api/v1/auth/login`, an API token (`la_…`), or the access token of an app someone gave access to through OAuth (`lo_…`). See [Authentication](authentication.md). Errors are JSON `{"detail": …}`; validation errors answer 422. Namespaces you can't read answer 404.

Outside `/api/v1`: IIIF resources under `/iiif/…` ([IIIF](iiif.md)), the embeddable player at `/embed/<id>` (and at a share link's short address, `/s/<code>`) and stored reports at `/reports/<namespace>/…`.

Expand Down Expand Up @@ -40,6 +40,45 @@ than `tokens.max_days`, or `0` (never expires) when `tokens.never_expire` is off
`{default_days, max_days, never_expire}`. `/admin/tokens` lists everyone's keys with their owner's `email` (admins), and
`DELETE /admin/tokens/{token_id}` revokes any of them; revoking is audited as `token.revoke`.

## oauth

```
GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource
POST /api/v1/oauth/register
GET /api/v1/oauth/authorize
POST /api/v1/oauth/authorize
POST /api/v1/oauth/token
POST /api/v1/oauth/revoke
GET /api/v1/oauth/grants
DELETE /api/v1/oauth/grants/{grant_id}
```

Lens is an OAuth 2.1 authorization server for API and MCP clients ([Authentication](authentication.md#oauth)).

* `POST /oauth/register {redirect_uris, client_name?, client_uri?, token_endpoint_auth_method?}` (RFC 7591, no sign-in,
201) registers an app: `client_id` (`lc_…`), and a `client_secret` (`ls_…`, shown once) when it asked for
`client_secret_post` or `client_secret_basic` instead of `none`. Redirect addresses are https, `http://localhost`
or `127.0.0.1` (any port), or the app's own scheme; other metadata is ignored. Errors are
`{error, error_description}`; more than 8 apps from one address in 15 minutes is a 429.
* `GET /oauth/authorize?client_id=&redirect_uri=&code_challenge=&code_challenge_method=S256&scope=` (signed in, as a
person) answers what the consent page shows: `{client: {id, name, uri}, redirect_uri, scope, granted}`, `scope`
being `read` or `read write` and `granted` what this app was given before. A request that can't be answered (an
unknown app, an address it didn't register, no S256 challenge) is a 400 with the reason.
* `POST /oauth/authorize {client_id, redirect_uri, code_challenge, code_challenge_method, scope?, state?, resource?,
approve, grant?}` answers it: `{redirect_to}`, the app's address with `code` and `state`, or with
`error=access_denied`. `grant: "read"` gives less than was asked for.
* `POST /oauth/token` (form-encoded) with `grant_type=authorization_code`, `code`, `redirect_uri`, `code_verifier` and
`client_id` (and `client_secret`, or HTTP Basic, for apps that have one), or with `grant_type=refresh_token` and
`refresh_token`: `{access_token, token_type: "Bearer", expires_in, refresh_token, scope}`. Errors are
`{error, error_description}` (`invalid_grant`, `invalid_client` with 401, `unsupported_grant_type`).
* `POST /oauth/revoke` (form-encoded: `token`, `client_id`) ends the access the token belongs to; it answers
`{ok: true}` whether or not the token was known.
* `GET /oauth/grants` lists the apps you gave access to (`id`, `client`, `name`, `uri`, `scope`, `created_at`,
`last_used_at`, `expires_at`); `DELETE /oauth/grants/{grant_id}` takes one's access away.

`GET /auth/me` says `via: "oauth"` for an app's token, with `scope` `read` or `write`.

## users

```
Expand Down
65 changes: 63 additions & 2 deletions docs/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Sign out ──► POST /api/v1/auth/logout (ends the session on the API too)
| `GET /api/v1/auth/status` | `{setup_required, wizard_pending}`: the sign-in page shows the setup form while the first admin is missing; admins are taken to the setup wizard while it is pending |
| `POST /api/v1/auth/setup` | first admin, with the setup code |
| `POST /api/v1/auth/login` · `/refresh` · `/logout` | token pairs |
| `GET /api/v1/auth/me` | the account, roles by namespace, and how the caller authenticated |
| `GET /api/v1/auth/me` | the account, roles by namespace, and how the caller authenticated (`via`: `access`, `token` or `oauth`) |
| `PATCH /api/v1/auth/me` | change your own name |
| `POST /api/v1/auth/password` | change your own password with your current one (signed in, not with an API token); wrong guesses are throttled like sign-ins; audited as `password.change` |
| `POST /api/v1/auth/password/forgot` · `/reset` | email a one-time reset link (60 minutes); answers the same for unknown emails |
Expand All @@ -54,6 +54,67 @@ For scripts and integrations: `POST /api/v1/tokens` (while signed in) returns `l
curl -H "Authorization: Bearer la_…" https://lens.example.org/api/v1/resources
```

## OAuth

For apps that sign people in instead of asking them for a key: MCP clients (Claude, Cursor and others), desktop and
web apps. Lens is the OAuth 2.1 authorization server itself: it issues the tokens, and people sign in with the Lens
account they have. Nothing here creates an account.

```
app ──► GET /.well-known/oauth-authorization-server where everything is
app ──► POST /api/v1/oauth/register { client_id } (once per app)
app ──► browser: /oauth/authorize?client_id=…&redirect_uri=…&code_challenge=…&code_challenge_method=S256&scope=…&state=…
the person signs in if they aren't, sees which app asks and for what, and chooses Allow or Deny
◄── browser: <redirect_uri>?code=…&state=…
app ──► POST /api/v1/oauth/token grant_type=authorization_code, code, redirect_uri, code_verifier, client_id
◄── { access_token (lo_…), refresh_token (lr_…), expires_in, scope }
app ──► API with Authorization: Bearer lo_…
app ──► POST /api/v1/oauth/token grant_type=refresh_token before the access token expires
```

* **Apps register themselves** (dynamic client registration, RFC 7591), without an account: registering gives an app
nothing until someone allows it. Its redirect addresses must be https, this machine's (`http://localhost` or
`127.0.0.1`, any port, for desktop apps), or a scheme of its own (`cursor://…`); addresses with a user name or a
backslash in them, and the browser's and the operating system's own schemes, are refused. Apps nobody gave access
to are forgotten after a week, and one address registers at most 8 apps in 15 minutes.
* **PKCE is required** (S256). The code works once, for five minutes, only with the verifier and the redirect address
it was given for. A code that comes back after it was swapped ends the access it gave (it was probably
intercepted). The consent page can't be framed by another site.
* **The consent page** (`/oauth/authorize` in the web app) names the app, where it returns the person to and what it
asks for: `read` (browse, search, chat), or `read write` (also import, edit, reprocess). The person can give read
only to an app that asked for both. Only a signed-in person answers it: API keys and other apps can't.
* **Tokens act as the person**, with their roles in each namespace and collection, exactly like the API does for them:
what they can't see, the app can't. An admin's app has the admin's roles in every namespace but not the
administration (people, settings, the audit log, everyone's keys): that stays with admins signed in or with their
own API key.
* **Lifetimes** are the admins' ([Configuration](configuration.md#api-keys)): the access token lasts
`tokens.oauth_access_minutes` (60), and the app stays signed in for `tokens.oauth_refresh_days` (30) after it last
renewed, at most `tokens.max_days`.
* **Refresh tokens rotate**: each renewal gives a new one. A swapped one that comes back within 60 seconds is refused
and changes nothing (two requests at once: the app keeps the pair it got first); after that it ends the access,
because it was probably copied. Only hashes of tokens, codes and app secrets are kept.
* **Taking access away**: people see the apps they allowed under API tokens → Apps with access, and revoke one there
(`DELETE /api/v1/oauth/grants/<id>`); an app hands its token back with `POST /api/v1/oauth/revoke`. Either way its
tokens stop working at once. Disabling an account stops its apps too. Allowing an app again replaces what it had.
* Registering, allowing and revoking are audited: `oauth.client.register`, `oauth.grant`, `oauth.revoke`.

`/.well-known/oauth-authorization-server` (RFC 8414) and `/.well-known/oauth-protected-resource` (RFC 9728) are
served on the web app's address as well as the API's, and every 401 that asks for a token points at the second in
`WWW-Authenticate: Bearer resource_metadata="…"`, as MCP clients expect. The addresses in them are the web app's when the request came
through it: the host it reports in `X-Forwarded-Host` when the web app is a trusted proxy
([Configuration](configuration.md#trusted-proxies)), else `FRONTEND_URL`. The web app reports the `Host` the browser
sent, or, with `TRUST_PROXY_HEADERS=true`, what a reverse proxy in front of it says in `X-Forwarded-Host`; leave that
off unless such a proxy sets the header, or anyone could choose the address. Set `FRONTEND_URL` to the address people
use, or apps will be sent to the wrong place to sign in.

| Endpoint | |
|---|---|
| `POST /api/v1/oauth/register` | register an app |
| `GET` · `POST /api/v1/oauth/authorize` | what the consent page shows, and the person's answer |
| `POST /api/v1/oauth/token` | a code or a refresh token for a new pair of tokens (form-encoded) |
| `POST /api/v1/oauth/revoke` | an app hands back a token |
| `GET /api/v1/oauth/grants` · `DELETE …/{id}` | the apps you gave access to; take one's away |

## Share links and signed links

* **Share links** give read-only access to one recording's player and embed, and expire. Each has a short address
Expand All @@ -74,5 +135,5 @@ posts a token only to the viewer's origin; the probe service answers with a shor

## Audit

Changes to people, roles, settings, sources, shares, tokens and curation go into the audit log (`GET /api/v1/audit`,
Changes to people, roles, settings, sources, shares, tokens, apps given access and curation go into the audit log (`GET /api/v1/audit`,
admins).
8 changes: 6 additions & 2 deletions docs/configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ with AES-GCM and are write-only: the API reports whether one is set, never its v
| `LENS_NAMESPACE` | | create the first namespace at startup, while there is none |
| `LENS_LLM_BASE_URL` / `LENS_LLM_MODEL` / `LENS_LLM_API_KEY` / `LENS_LLM_VISION_MODEL` | | the model provider; wins over Settings, which show these locked |
| `LENS_SETUP_WIZARD` | | `off`: never show the setup wizard |
| `FRONTEND_URL` | `http://localhost:3000` | links in emails |
| `FRONTEND_URL` | `http://localhost:3000` | the web app's address as people use it: links in emails, and where apps send people to sign in ([OAuth](authentication.md#oauth)) |
| `CORS_ORIGINS` | `["http://localhost:3000"]` | origins allowed to call the API from a browser |
| `OPENAPI_URL` | `/openapi.json` | `""` disables `/docs` and the schema |
| `MAIL_SERVER`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_FROM`, `MAIL_STARTTLS`, `MAIL_SSL_TLS`, `USE_CREDENTIALS`, `VALIDATE_CERTS` | | SMTP for password reset and for telling owners about requests for access; without `MAIL_SERVER` the links are logged |
Expand Down Expand Up @@ -63,6 +63,7 @@ show locked. Installs that already had accounts never see the wizard. The API si
| `AUTH_SECRET` | encrypts the NextAuth session cookie (`npx auth secret`) |
| `AUTH_URL` | the public URL of the web app, when it can't be inferred |
| `AUTH_TRUST_HOST` | `true` behind a proxy or in Docker |
| `TRUST_PROXY_HEADERS` | `true` when a reverse proxy in front of the web app sets `X-Forwarded-Host` and `-Proto`: they're passed on to the API, which names that address in OAuth discovery. Off, the web app reports the `Host` the browser sent |

## archive.yaml

Expand Down Expand Up @@ -224,8 +225,11 @@ Settings → API keys:
| `tokens.default_days` | 90 | how long a new key lasts when its maker doesn't say, 1–3650 days (at most `tokens.max_days`) |
| `tokens.max_days` | 365 | the longest a key may last, 1–3650 days |
| `tokens.never_expire` | false | whether keys may be made that never expire |
| `tokens.oauth_access_minutes` | 60 | how long the access token of an app someone signed in to lasts ([OAuth](authentication.md#oauth)), 5–1440 minutes; the app renews it by itself |
| `tokens.oauth_refresh_days` | 30 | how long such an app stays signed in after it last renewed its access, 1–3650 days (at most `tokens.max_days`) |

The limits apply to keys made after a change: keys made before keep their expiry. Settings → API keys also lists
The limits apply to keys made after a change: keys made before keep their expiry; apps get the new lifetimes the
next time they renew. Settings → API keys also lists
everyone's keys (whose, what scope, when they expire and were last used), and an admin can revoke any of them; that's
audited as `token.revoke`.

Expand Down
Loading
Loading