diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c6d5efa8..5d9ce266a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/docs/api.md b/docs/api.md index bc989fb70..98b9fc296 100644 --- a/docs/api.md +++ b/docs/api.md @@ -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 `: 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 `: 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/` (and at a share link's short address, `/s/`) and stored reports at `/reports//…`. @@ -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 ``` diff --git a/docs/authentication.md b/docs/authentication.md index ffae55e00..5b6ba2f05 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -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 | @@ -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: ?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/`); 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 @@ -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). diff --git a/docs/configuration.md b/docs/configuration.md index cff0ee805..c8cab5a62 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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 | @@ -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 @@ -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`. diff --git a/fastapi_backend/app/api/deps.py b/fastapi_backend/app/api/deps.py index 0b6c1f74f..146254f5b 100644 --- a/fastapi_backend/app/api/deps.py +++ b/fastapi_backend/app/api/deps.py @@ -1,8 +1,9 @@ """Request dependencies: the database, the effective configuration, who is calling and what they may touch. Who is calling comes from the ``Authorization: Bearer`` header, which carries either an access token issued at sign-in -(the web app, through NextAuth) or an API token (``la_...``). Access tokens can write; API tokens are read-only unless -created with the write scope. No cookies are involved, so there is nothing for CSRF to ride on. +(the web app, through NextAuth), an API token (``la_...``) or the access token of an app the person gave access to +through OAuth (``lo_...``, app/domain/oauth.py). Access tokens can write; API tokens and apps are read-only unless +they have the write scope. No cookies are involved, so there is nothing for CSRF to ride on. Access is per namespace. A namespace you have no role in behaves as if it didn't exist (404); one you can read but not change says so (403). Admins own every namespace. A role on a collection adds to that for the recordings in it (and in @@ -22,7 +23,7 @@ from app.core import security from app.domain import access as acc -from app.domain import auth, hierarchy, ipgroups, store +from app.domain import auth, hierarchy, ipgroups, oauth, store from app.domain.store import DB Config = dict[str, Any] @@ -46,7 +47,7 @@ class Principal: email: str name: str | None admin: bool - via: Literal["access", "token"] # a signed-in session, or an API token + via: Literal["access", "token", "oauth"] # a signed-in session, an API token, or an app given access (OAuth) scope: Literal["read", "write"] = "write" sid: str | None = None roles: dict[int, str] = field(default_factory=dict) @@ -72,6 +73,10 @@ def _principal(request: Request, db: DB) -> Principal | None: p = Principal( u["id"], u["email"], u.get("name"), bool(u.get("admin")), "token", "write" if u.get("scope") == "write" else "read" ) + elif raw.startswith("lo_"): + u = oauth.token_account(db, raw) + if u: + p = Principal(u["id"], u["email"], u.get("name"), bool(u.get("admin")), "oauth", u["scope"]) elif raw: claims = security.decode_access_token(raw) u = auth.active_account(db, claims.account) if claims and auth.session_active(db, claims.sid) else None @@ -101,16 +106,22 @@ def writer(user: Annotated[Principal, Depends(current_user)]) -> Principal: return user -def admin_reader(user: Annotated[Principal, Depends(current_user)]) -> Principal: +def _admin(user: Principal) -> Principal: + """Administration (people, settings, the audit log) is for admins themselves, signed in or with their API key. An + app an admin gave access to has the admin's roles in every namespace, not the administration.""" if not user.admin: raise HTTPException(403, "admins only") + if user.via == "oauth": + raise HTTPException(403, "admins only: apps given access can't administer the archive") return user +def admin_reader(user: Annotated[Principal, Depends(current_user)]) -> Principal: + return _admin(user) + + def admin_writer(user: Annotated[Principal, Depends(writer)]) -> Principal: - if not user.admin: - raise HTTPException(403, "admins only") - return user + return _admin(user) OptionalUser = Annotated[Principal | None, Depends(optional_user)] diff --git a/fastapi_backend/app/api/v1/router.py b/fastapi_backend/app/api/v1/router.py index 17648d3ae..b3e071e24 100644 --- a/fastapi_backend/app/api/v1/router.py +++ b/fastapi_backend/app/api/v1/router.py @@ -21,6 +21,7 @@ namespaces, notes, notifications, + oauth, pipelines, public, recordings, @@ -42,6 +43,7 @@ api_router = APIRouter() api_router.include_router(auth.router) api_router.include_router(auth.tokens) +api_router.include_router(oauth.router) for module in ( users, admin, diff --git a/fastapi_backend/app/api/v1/routes/oauth.py b/fastapi_backend/app/api/v1/routes/oauth.py new file mode 100644 index 000000000..a1d8bea5a --- /dev/null +++ b/fastapi_backend/app/api/v1/routes/oauth.py @@ -0,0 +1,287 @@ +"""OAuth 2.1 for API and MCP clients: Lens issues the tokens itself (docs/authentication.md#oauth). + +An app registers (``POST /oauth/register``), sends the person to the web app's consent page (``/oauth/authorize``, +which asks ``GET``/``POST /oauth/authorize`` here with the person's own session), swaps the code for tokens +(``POST /oauth/token``) and renews them there. People see the apps they gave access to and take it away +(``/oauth/grants``); an app can hand its token back (``POST /oauth/revoke``). ``/.well-known/…`` says where all of this +is, as MCP clients expect. +""" + +from __future__ import annotations + +import base64 +import binascii +import ipaddress +import re +import time +from typing import Annotated, Any + +from fastapi import APIRouter, Form, HTTPException, Query, Request +from fastapi.exception_handlers import http_exception_handler +from fastapi.responses import JSONResponse, Response +from starlette.exceptions import HTTPException as StarletteHTTPException + +from app.api.deps import Cfg, CurrentUser, Db, client_ip, domain_errors, visitor_address +from app.config import settings +from app.domain import auth, oauth +from app.schemas.common import Ok +from app.schemas.oauth import ( + ClientRegistered, + ClientRegistration, + Consent, + ConsentAnswer, + ConsentResult, + OAuthGrant, + OAuthTokens, +) + +router = APIRouter(prefix="/oauth", tags=["oauth"]) +well_known = APIRouter(include_in_schema=False, tags=["oauth-discovery"]) + +API = "/api/v1/oauth" +HOST = re.compile(r"[A-Za-z0-9.\-]+(:\d+)?|\[[0-9A-Fa-f:.]+\](:\d+)?") +RESOURCE = re.compile(r"[A-Za-z0-9_\-]+(/[A-Za-z0-9_\-]+)*") +NO_STORE = {"Cache-Control": "no-store", "Pragma": "no-cache"} + + +def _first(value: str | None) -> str: + return (value or "").split(",")[0].strip() + + +def _from_trusted_proxy(request: Request) -> bool: + peer = request.client.host if request.client else "" + trusted = request.app.state.settings.current()["server"].get("trusted_proxies") or () + try: + addr = ipaddress.ip_address(peer) + except ValueError: + return False + return any(addr in ipaddress.ip_network(t, strict=False) for t in trusted) + + +def public_base(request: Request) -> str: + """The address clients reach Lens at. Through the web app, that's the web app's: what it says in + X-Forwarded-Host when it's a trusted proxy (server.trusted_proxies), else FRONTEND_URL, so nobody who can reach + the API can make it name another host. Reached directly, it's this server's (the Host header was checked).""" + h = request.headers + host = _first(h.get("x-forwarded-host")) + if not host: + return str(request.base_url).rstrip("/") + proto = _first(h.get("x-forwarded-proto")) or request.url.scheme + if _from_trusted_proxy(request) and HOST.fullmatch(host) and proto in ("http", "https"): + return f"{proto}://{host}" + return settings.FRONTEND_URL.rstrip("/") + + +def _consent_page(request: Request) -> str: + """The consent page is the web app's: on this address when the request came through it, else FRONTEND_URL.""" + through_web_app = bool(_first(request.headers.get("x-forwarded-host"))) + return (public_base(request) if through_web_app else settings.FRONTEND_URL.rstrip("/")) + "/oauth/authorize" + + +def _discovery(doc: dict[str, Any]) -> JSONResponse: + # no-store: the addresses depend on how the request arrived, so no cache may hand them to someone else + return JSONResponse(doc, headers={"Cache-Control": "no-store", "Access-Control-Allow-Origin": "*"}) + + +def _oauth_error(e: oauth.OAuthError) -> JSONResponse: + headers = {**NO_STORE, **({"WWW-Authenticate": "Basic"} if e.status == 401 else {})} + return JSONResponse({"error": e.error, "error_description": e.description}, status_code=e.status, headers=headers) + + +def _client_credentials(request: Request, client_id: str | None, client_secret: str | None) -> tuple[str | None, str | None]: + """The app's id and secret, from the form or from HTTP Basic (client_secret_basic).""" + h = request.headers.get("authorization", "") + if h.lower().startswith("basic "): + try: + cid, _, secret = base64.b64decode(h[6:].strip(), validate=True).decode().partition(":") + return cid, secret + except (binascii.Error, UnicodeDecodeError): + raise oauth.OAuthError("invalid_client", "the Authorization header isn't Basic credentials", 401) from None + return client_id, client_secret + + +async def bearer_challenge(request: Request, exc: StarletteHTTPException) -> Response: + """401s that ask for a bearer token say where to find out how to get one (RFC 9728 §5.1), as MCP clients expect.""" + if exc.status_code == 401 and (exc.headers or {}).get("WWW-Authenticate") == "Bearer": + meta = f"{public_base(request)}/.well-known/oauth-protected-resource" + exc = StarletteHTTPException( + 401, exc.detail, headers={**(exc.headers or {}), "WWW-Authenticate": f'Bearer resource_metadata="{meta}"'} + ) + return await http_exception_handler(request, exc) + + +@well_known.get("/.well-known/oauth-authorization-server") +@well_known.get("/.well-known/oauth-authorization-server/{rest:path}") +def authorization_server(request: Request) -> JSONResponse: + """Authorization server metadata (RFC 8414).""" + base = public_base(request) + doc = { + "issuer": base, + "authorization_endpoint": _consent_page(request), + "token_endpoint": f"{base}{API}/token", + "registration_endpoint": f"{base}{API}/register", + "revocation_endpoint": f"{base}{API}/revoke", + "response_types_supported": ["code"], + "grant_types_supported": ["authorization_code", "refresh_token"], + "code_challenge_methods_supported": ["S256"], + "token_endpoint_auth_methods_supported": list(oauth.AUTH_METHODS), + "revocation_endpoint_auth_methods_supported": list(oauth.AUTH_METHODS), + "scopes_supported": list(oauth.SCOPES), + } + return _discovery(doc) + + +@well_known.get("/.well-known/oauth-protected-resource") +@well_known.get("/.well-known/oauth-protected-resource/{rest:path}") +def protected_resource(request: Request, rest: str = "") -> JSONResponse: + """Protected resource metadata (RFC 9728): who issues the tokens this server takes.""" + base = public_base(request) + if rest and not RESOURCE.fullmatch(rest): + raise HTTPException(404, "not found") + doc = { + "resource": f"{base}/{rest}" if rest else base, + "authorization_servers": [base], + "bearer_methods_supported": ["header"], + "scopes_supported": list(oauth.SCOPES), + "resource_name": settings.PROJECT_NAME, + } + return _discovery(doc) + + +@router.post("/register", status_code=201, response_model=ClientRegistered, responses={400: {"description": "OAuth error"}}) +def register(body: ClientRegistration, request: Request, db: Db) -> Any: + """An app registers itself (RFC 7591), without signing in: it gets a `client_id`, and a `client_secret` if it + asked for one. It can do nothing until someone gives it access. Audited as `oauth.client.register`.""" + key = f"oauth-register|{visitor_address(request) or client_ip(request)}" + if auth.throttled(key): + raise HTTPException(429, "too many apps registered from this address; try again in a few minutes") + try: + c = oauth.register_client(db, body.client_name, body.redirect_uris, body.client_uri, body.token_endpoint_auth_method) + except oauth.OAuthError as e: + return _oauth_error(e) + auth.hit(key) + auth.audit( + db, None, "oauth.client.register", f"oauth_client:{c['client_id']}", {"name": c["name"], "redirect_uris": c["redirect_uris"]} + ) + return JSONResponse( + ClientRegistered( + client_id=c["client_id"], + client_secret=c.get("client_secret"), + client_id_issued_at=int(time.time()), + client_name=c["name"], + client_uri=c.get("uri"), + redirect_uris=c["redirect_uris"], + token_endpoint_auth_method=c["auth_method"], + ).model_dump(exclude_none=True), + status_code=201, + headers=NO_STORE, + ) + + +def _person(user: CurrentUser) -> None: + if user.via != "access": + raise HTTPException(403, "sign in to give an app access; API tokens and apps can't") + + +@router.get("/authorize") +def consent( + user: CurrentUser, + db: Db, + client_id: str = Query(), + redirect_uri: str = Query(), + code_challenge: str = Query(""), + code_challenge_method: str = Query(""), + response_type: str = Query("code"), + scope: str | None = Query(None), +) -> Consent: + """What the consent page shows for an app's request: the app, where it takes you back to and what it asks for. + 400 when the request can't be answered (an unknown app, an address it didn't register, no PKCE challenge).""" + _person(user) + with domain_errors(): + return Consent( + **oauth.authorization(db, user.id, client_id, redirect_uri, response_type, code_challenge, code_challenge_method, scope) + ) + + +@router.post("/authorize") +def answer(body: ConsentAnswer, user: CurrentUser, db: Db) -> ConsentResult: + """Your answer to an app's request. Yes gives it a one-time code (five minutes) at its redirect address, which + it swaps for tokens that act as you, with your roles; no sends it `error=access_denied`. Audited as + `oauth.grant`.""" + _person(user) + with domain_errors(): + info = oauth.authorization( + db, user.id, body.client_id, body.redirect_uri, body.response_type, body.code_challenge, body.code_challenge_method, body.scope + ) + if not body.approve: + return ConsentResult(redirect_to=oauth.with_params(body.redirect_uri, error="access_denied", state=body.state)) + code, scope = oauth.approve(db, user.id, info, body.code_challenge, body.grant, body.resource) + auth.audit(db, user.as_audit(), "oauth.grant", f"oauth_client:{body.client_id}", {"name": info["client"]["name"], "scope": scope}) + return ConsentResult(redirect_to=oauth.with_params(body.redirect_uri, code=code, state=body.state)) + + +@router.post("/token", response_model=OAuthTokens, responses={400: {"description": "OAuth error"}, 401: {"description": "OAuth error"}}) +def token( + request: Request, + db: Db, + cfg: Cfg, + grant_type: Annotated[str, Form()], + code: Annotated[str | None, Form()] = None, + redirect_uri: Annotated[str | None, Form()] = None, + code_verifier: Annotated[str | None, Form()] = None, + refresh_token: Annotated[str | None, Form()] = None, + client_id: Annotated[str | None, Form()] = None, + client_secret: Annotated[str | None, Form()] = None, +) -> Any: + """The app swaps its code (`grant_type=authorization_code`, with `code_verifier` and the same `redirect_uri`) + or its refresh token (`grant_type=refresh_token`) for an access token and a new refresh token. Form-encoded, as + OAuth has it; errors are `{error, error_description}`.""" + try: + cid, secret = _client_credentials(request, client_id, client_secret) + if grant_type == "authorization_code": + tokens, _ = oauth.exchange_code(db, cfg, cid, secret, code, redirect_uri, code_verifier) + elif grant_type == "refresh_token": + tokens = oauth.refresh(db, cfg, cid, secret, refresh_token) + else: + raise oauth.OAuthError("unsupported_grant_type", "grant_type is authorization_code or refresh_token") + except oauth.OAuthError as e: + return _oauth_error(e) + return JSONResponse(tokens, headers=NO_STORE) + + +@router.post("/revoke", response_model=Ok, responses={401: {"description": "OAuth error"}}) +def revoke( + request: Request, + db: Db, + token: Annotated[str, Form()], + client_id: Annotated[str | None, Form()] = None, + client_secret: Annotated[str | None, Form()] = None, +) -> Any: + """An app hands back a token, access or refresh (RFC 7009): the access it was given ends. Answers the same + whether or not the token was known. Audited as `oauth.revoke`.""" + try: + cid, secret = _client_credentials(request, client_id, client_secret) + g = oauth.revoke_token(db, cid, secret, token) + except oauth.OAuthError as e: + return _oauth_error(e) + if g: + acct = auth.active_account(db, g["account"]) or {"id": g["account"]} + auth.audit(db, acct, "oauth.revoke", f"oauth_client:{g['client']}", {"name": g["name"], "by": "app"}) + return Ok() + + +@router.get("/grants") +def list_grants(user: CurrentUser, db: Db) -> list[OAuthGrant]: + """The apps you gave access to, the latest first.""" + return [OAuthGrant(**g) for g in oauth.grants(db, user.id)] + + +@router.delete("/grants/{grant_id}") +def revoke_grant(grant_id: int, user: CurrentUser, db: Db) -> Ok: + """Take an app's access away: its tokens stop working now. Audited as `oauth.revoke`.""" + _person(user) + g = oauth.revoke_grant(db, user.id, grant_id) + if not g: + raise HTTPException(404, "not found") + auth.audit(db, user.as_audit(), "oauth.revoke", f"oauth_client:{g['client']}", {"name": g["name"]}) + return Ok() diff --git a/fastapi_backend/app/domain/auth.py b/fastapi_backend/app/domain/auth.py index f51919020..c0d6b7324 100644 --- a/fastapi_backend/app/domain/auth.py +++ b/fastapi_backend/app/domain/auth.py @@ -106,6 +106,12 @@ def throttled(key): return len(_FAILS[key]) >= 8 +def hit(key): + """Count one more towards `key`'s throttle (throttled() says when there were too many).""" + with _FL: + _FAILS.setdefault(key, []).append(time.time()) + + def login(db, email, password, key=""): """Returns the account or None. Unknown emails cost the same time as wrong passwords.""" u = find_account(db, email) diff --git a/fastapi_backend/app/domain/oauth.py b/fastapi_backend/app/domain/oauth.py new file mode 100644 index 000000000..68ceb0870 --- /dev/null +++ b/fastapi_backend/app/domain/oauth.py @@ -0,0 +1,371 @@ +"""Lens as an OAuth 2.1 authorization server, for API and MCP clients (docs/authentication.md). + +An app registers itself (RFC 7591), sends the person to the consent page with a PKCE challenge (S256, required), and +swaps the code it gets back for an access token and a refresh token. The tokens act as the person who consented, with +their roles, read only or read and write. Like API keys they are random and only their hashes are kept, so revoking a +grant works at once. Refresh tokens rotate; one that comes back after it was swapped ends the grant (it was probably +copied). No account is created here: people sign in with the one they have. +""" + +from __future__ import annotations + +import base64 +import datetime as dt +import hashlib +import hmac +import re +import secrets +import urllib.parse + +from . import auth, store + +R = store.R +SCOPES = ("read", "write") +CODE_SECONDS = 300 +CODE_REMEMBERED_SECONDS = 86400 # a spent code is remembered this long, so that its coming back ends what it gave +REUSE_GRACE_SECONDS = auth.REUSE_GRACE_SECONDS +UNUSED_CLIENT_DAYS = 7 # a registered app nobody gave access to is forgotten after this +AUTH_METHODS = ("none", "client_secret_post", "client_secret_basic") +LOOPBACK = ("localhost", "127.0.0.1", "[::1]", "::1") +# schemes an app's own redirect address may never use: they'd run or read things in the browser that sends people there +BAD_SCHEMES = { + *("javascript", "data", "vbscript", "file", "blob", "about", "view-source", "ws", "wss", "ftp", "sftp", "ssh", "smb", "nfs"), + *("ldap", "ldaps", "telnet", "mailto", "tel", "sms", "intent", "chrome", "edge", "resource", "jar", "search-ms"), +} +BAD_SCHEME_PREFIXES = ("ms-", "x-apple", "itms") # the operating system's own handlers +SCHEME = re.compile(r"^[a-z][a-z0-9+.-]*$") +PKCE = re.compile(r"[A-Za-z0-9._~-]{43,128}") + + +class OAuthError(Exception): + """An error in OAuth's own words (RFC 6749 §5.2): `error`, a sentence for people, and the HTTP status.""" + + def __init__(self, error, description, status=400): + super().__init__(description) + self.error, self.description, self.status = error, description, status + + +def _later(seconds): + return (dt.datetime.now(dt.timezone.utc) + dt.timedelta(seconds=seconds)).isoformat(timespec="seconds") + + +def lifetimes(cfg): + """How long an app's tokens last (tokens settings): {access_minutes, refresh_days}.""" + t = {**store.DEFAULTS["tokens"], **(cfg.get("tokens") or {})} + return {"access_minutes": int(t["oauth_access_minutes"]), "refresh_days": int(t["oauth_refresh_days"])} + + +# ---------- scopes and redirect addresses ---------- +def scopes(raw, default="read"): + """The scopes asked for, as Lens knows them: `read`, or `read write`. Others are ignored; nothing asks for read.""" + asked = set((raw or "").split()) & set(SCOPES) + if not asked: + asked = set(default.split()) + return "read write" if "write" in asked else "read" + + +def can_write(scope): + return "write" in (scope or "").split() + + +def check_redirect(uri): + """A redirect address an app may register: https, http on this machine (loopback), or the app's own scheme. + Returns it; ValueError otherwise.""" + if not isinstance(uri, str) or not uri or len(uri) > 2000 or any(c.isspace() or ord(c) < 32 for c in uri): + raise ValueError("a redirect address is one URL") + p = urllib.parse.urlsplit(uri) + scheme = p.scheme.lower() + if "\\" in uri or p.username is not None or p.password is not None or "@" in p.netloc: + # browsers read a backslash as a slash and what's before an @ as a sign-in, so the host isn't what it seems + raise ValueError("a redirect address has no backslash and no user name in it") + if not SCHEME.match(scheme) or scheme in BAD_SCHEMES or scheme.startswith(BAD_SCHEME_PREFIXES): + raise ValueError(f"redirect addresses can't use {scheme or 'no scheme'}:") + if p.fragment or "#" in uri: + raise ValueError("a redirect address has no fragment") + if scheme == "https": + if not p.hostname: + raise ValueError("a redirect address needs a host") + elif scheme == "http": + if (p.hostname or "") not in LOOPBACK: + raise ValueError("http redirect addresses are for this machine only (localhost); use https") + return uri + + +def _loopback(p): + return p.scheme.lower() == "http" and (p.hostname or "") in LOOPBACK + + +def redirect_ok(registered, uri): + """Whether `uri` is one of the app's redirect addresses: the same string, or, on this machine, the same but for + its port (apps listen on whichever is free, RFC 8252 §7.3).""" + if uri in registered: + return True + try: + p = urllib.parse.urlsplit(check_redirect(uri)) + if not _loopback(p): + return False + for r in registered: + q = urllib.parse.urlsplit(r) + if _loopback(q) and (q.hostname, q.path, q.query) == (p.hostname, p.path, p.query): + return True + except ValueError: + return False + return False + + +def with_params(uri, **params): + """`uri` with these query parameters added to the ones it has.""" + p = urllib.parse.urlsplit(uri) + query = urllib.parse.parse_qsl(p.query, keep_blank_values=True) + [(k, v) for k, v in params.items() if v is not None] + return urllib.parse.urlunsplit((p.scheme, p.netloc, p.path, urllib.parse.urlencode(query), "")) + + +# ---------- apps (clients) ---------- +def register_client(db, name, redirect_uris, uri=None, auth_method="none"): + """A new app (RFC 7591): {client_id, client_secret?, …}. Apps that can keep a secret get one, shown once.""" + name = " ".join(str(name or "").split())[:80] or "An app" + if not isinstance(redirect_uris, list) or not redirect_uris or len(redirect_uris) > 10: + raise OAuthError("invalid_redirect_uri", "give 1 to 10 redirect addresses") + try: + uris = [check_redirect(u) for u in redirect_uris] + except ValueError as e: + raise OAuthError("invalid_redirect_uri", str(e)) from None + if auth_method not in AUTH_METHODS: + raise OAuthError("invalid_client_metadata", f"token_endpoint_auth_method is one of: {', '.join(AUTH_METHODS)}") + if uri is not None and not (isinstance(uri, str) and re.match(r"^https?://[^\s]+$", uri) and len(uri) <= 500): + uri = None + forget_unused_clients(db) + cid = "lc_" + secrets.token_urlsafe(16) + secret = None if auth_method == "none" else "ls_" + secrets.token_urlsafe(32) + db.q( + "CREATE $r CONTENT $d", + r=R("oauth_client", cid), + d=store.clean( + { + "name": name, + "redirect_uris": uris, + "uri": uri, + "auth_method": auth_method, + "secret": auth.sha(secret) if secret else None, + "created_at": store.now(), + "used": False, + } + ), + ) + return store.clean( + {"client_id": cid, "client_secret": secret, "name": name, "redirect_uris": uris, "uri": uri, "auth_method": auth_method} + ) + + +def forget_unused_clients(db): + """Registering is open to anyone, so apps nobody ever gave access to don't pile up.""" + db.q("DELETE oauth_client WHERE used != true AND created_at < $t", t=_later(-UNUSED_CLIENT_DAYS * 86400)) + + +def get_client(db, cid): + if not cid or not isinstance(cid, str) or not cid.startswith("lc_"): + return None + return db.one("SELECT record::id(id) AS id, name, redirect_uris, uri, auth_method, secret FROM $r", r=R("oauth_client", cid)) + + +def _client(db, cid, secret=None, check_secret=False): + c = get_client(db, cid) + if not c: + raise OAuthError("invalid_client", "unknown client_id", 401) + if check_secret and c.get("secret") and not hmac.compare_digest(c["secret"], auth.sha(secret or "")): + raise OAuthError("invalid_client", "wrong client_secret", 401) + return c + + +# ---------- consent ---------- +def authorization(db, uid, client_id, redirect_uri, response_type, code_challenge, code_challenge_method, scope): + """What the consent page shows: the app, where it takes the person back to and what it asks for. ValueError when + the request can't be answered (the page says so and sends nobody anywhere).""" + c = get_client(db, client_id) + if not c: + raise ValueError("This app isn't registered here (unknown client_id).") + if not redirect_uri or not redirect_ok(c["redirect_uris"], redirect_uri): + raise ValueError("The address this app wants to return to isn't one it registered.") + if response_type != "code": + raise ValueError("Only the authorization code flow is supported (response_type=code).") + if code_challenge_method != "S256" or not PKCE.fullmatch(code_challenge or "") or len(code_challenge) != 43: + raise ValueError("The app has to send a PKCE challenge (code_challenge with code_challenge_method=S256).") + before = db.one("SELECT scope FROM oauth_grant WHERE account = $a AND client = $c LIMIT 1", a=uid, c=c["id"]) + return { + "client": {"id": c["id"], "name": c["name"], "uri": c.get("uri")}, + "redirect_uri": redirect_uri, + "scope": scopes(scope), + "granted": (before or {}).get("scope"), + } + + +def approve(db, uid, info, code_challenge, granted_scope=None, resource=None): + """The person said yes: a one-time code for the app, good for five minutes. The scope given may be less than + what was asked for (read only), never more.""" + scope = scopes(granted_scope, info["scope"]) if granted_scope else info["scope"] + if can_write(scope) and not can_write(info["scope"]): + scope = "read" + code = secrets.token_urlsafe(32) + db.q("DELETE oauth_code WHERE expires_at < $now", now=store.now()) # codes never swapped, and spent codes' marks + db.q( + "CREATE $r CONTENT $d", + r=R("oauth_code", auth.sha(code)), + d=store.clean( + { + "client": info["client"]["id"], + "account": uid, + "redirect_uri": info["redirect_uri"], + "challenge": code_challenge, + "scope": scope, + "resource": (resource or None) and str(resource)[:500], + "expires_at": _later(CODE_SECONDS), + } + ), + ) + return code, scope + + +# ---------- tokens ---------- +def _verifier_ok(verifier, challenge): + if not PKCE.fullmatch(verifier or ""): + return False + calc = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip("=") + return hmac.compare_digest(calc, challenge or "") + + +def _issue(db, cfg, grant, uid, scope): + life = lifetimes(cfg) + access, refresh = "lo_" + secrets.token_urlsafe(32), "lr_" + secrets.token_urlsafe(32) + ttl = life["access_minutes"] * 60 + ends = _later(life["refresh_days"] * 86400) + base = {"gid": grant, "account": uid, "scope": scope, "created_at": store.now()} + # a grant revoked while its app was renewing gets nothing: the tokens hang off the grant + if not db.rows("UPDATE $g SET expires_at = $ends RETURN id", g=R("oauth_grant", grant), ends=ends): + raise OAuthError("invalid_grant", "this access was revoked") + db.run( + ["CREATE $a CONTENT $ad", "CREATE $f CONTENT $fd"], + a=R("oauth_token", auth.sha(access)), + ad={**base, "kind": "access", "expires_at": _later(ttl)}, + f=R("oauth_token", auth.sha(refresh)), + fd={**base, "kind": "refresh", "expires_at": ends}, + ) + return {"access_token": access, "token_type": "Bearer", "expires_in": ttl, "refresh_token": refresh, "scope": scope} + + +def exchange_code(db, cfg, client_id, client_secret, code, redirect_uri, verifier): + """The app swaps its code for tokens (once). Returns (tokens, grant): the grant is new, and replaces any this + person gave the same app before.""" + c = _client(db, client_id, client_secret, check_secret=True) + # deleting it is what makes a code work once, whoever else is trying it at the same moment + key = R("oauth_code", auth.sha(code or "")) + row = (db.rows("DELETE $r RETURN BEFORE", r=key) or [None])[0] if code else None + if row and row.get("spent"): + # a code that was swapped already came back: it was probably intercepted, so the tokens it gave stop working + # (RFC 6749 §4.1.2) + if row.get("gid") is not None: + drop_grant(db, row["gid"]) + raise OAuthError("invalid_grant", "the code is wrong, was used already or has expired") + if not row or row.get("expires_at", "") < store.now() or row["client"] != c["id"]: + raise OAuthError("invalid_grant", "the code is wrong, was used already or has expired") + if row["redirect_uri"] != redirect_uri: + raise OAuthError("invalid_grant", "redirect_uri isn't the one the code was given for") + if not _verifier_ok(verifier, row["challenge"]): + raise OAuthError("invalid_grant", "code_verifier doesn't match the challenge") + if not auth.active_account(db, row["account"]): + raise OAuthError("invalid_grant", "the account is no longer active") + for old in db.values("SELECT VALUE record::id(id) FROM oauth_grant WHERE account = $a AND client = $c", a=row["account"], c=c["id"]): + drop_grant(db, old) + gid = db.next_id("oauth_grant") + db.run( + ["CREATE $g CONTENT $d", "UPDATE $c SET used = true", "CREATE $k CONTENT $spent"], + k=key, + spent={"spent": True, "gid": gid, "expires_at": _later(CODE_REMEMBERED_SECONDS)}, + g=R("oauth_grant", gid), + d={ + "account": row["account"], + "client": c["id"], + "name": c["name"], + "uri": c.get("uri"), + "scope": row["scope"], + "created_at": store.now(), + }, + c=R("oauth_client", c["id"]), + ) + return _issue(db, cfg, gid, row["account"], row["scope"]), {"id": gid, "account": row["account"], "client": c["id"], "name": c["name"]} + + +def refresh(db, cfg, client_id, client_secret, raw): + """A new pair for a refresh token, which then stops working. One that was swapped a while ago and comes back + ends the grant: it was probably copied.""" + c = _client(db, client_id, client_secret, check_secret=True) + t = db.one("SELECT gid, account, kind, scope, expires_at, rotated, rotated_at FROM $r", r=R("oauth_token", auth.sha(raw or ""))) + g = db.one("SELECT client FROM $r", r=R("oauth_grant", t["gid"])) if t else None + if not t or not g or t["kind"] != "refresh" or g["client"] != c["id"] or t["expires_at"] < store.now(): + raise OAuthError("invalid_grant", "the refresh token is wrong, was revoked or has expired") + if t.get("rotated"): + # within the grace period it's more likely the app renewing twice at once (it keeps the pair it got first); + # later it was probably copied, so the access ends + if (t.get("rotated_at") or "") < _later(-REUSE_GRACE_SECONDS): + drop_grant(db, t["gid"]) + raise OAuthError("invalid_grant", "the refresh token was used already; ask for access again") + raise OAuthError("invalid_grant", "the refresh token was used already; use the tokens it was swapped for") + if not auth.active_account(db, t["account"]): + raise OAuthError("invalid_grant", "the account is no longer active") + now = store.now() + db.run( + ["UPDATE $old SET rotated = true, rotated_at = rotated_at OR $now", "DELETE oauth_token WHERE gid = $g AND expires_at < $now"], + old=R("oauth_token", auth.sha(raw)), + now=now, + g=t["gid"], + ) + return _issue(db, cfg, t["gid"], t["account"], t["scope"]) + + +def token_account(db, raw): + """The account an access token acts as ({…account, scope}), or None. Refresh tokens don't open the API.""" + if not raw or not raw.startswith("lo_"): + return None + t = db.one("SELECT gid, account, kind, scope, expires_at FROM $r", r=R("oauth_token", auth.sha(raw))) + if not t or t["kind"] != "access" or t["expires_at"] < store.now(): + return None + u = auth.active_account(db, t["account"]) + if not u: + return None + if not db.rows("UPDATE $r SET last_used_at = $n RETURN id", r=R("oauth_grant", t["gid"]), n=store.now()): + return None # its grant is gone + return {**u, "scope": "write" if can_write(t["scope"]) else "read", "grant": t["gid"]} + + +# ---------- grants: the apps a person gave access to ---------- +def grants(db, uid): + """The apps this person gave access to, the latest first.""" + rows = db.rows( + "SELECT record::id(id) AS id, client, name, uri, scope, created_at, last_used_at, expires_at FROM oauth_grant WHERE account = $a", + a=uid, + ) + return sorted(rows, key=lambda r: (r.get("created_at") or "", r["id"]), reverse=True) + + +def drop_grant(db, gid): + """End a grant: its tokens stop working now.""" + db.run(["DELETE oauth_token WHERE gid = $g", "DELETE $r"], g=gid, r=R("oauth_grant", gid)) + + +def revoke_grant(db, uid, gid): + """Take an app's access away (this person's grant); the grant, or None when they have no such grant.""" + g = db.one("SELECT record::id(id) AS id, client, name FROM $r WHERE account = $a", r=R("oauth_grant", gid), a=uid) + if g: + drop_grant(db, gid) + return g + + +def revoke_token(db, client_id, client_secret, raw): + """An app hands back a token (RFC 7009): its grant ends. Returns the grant ({id, account, client, name}) or None + when the token is unknown, which the app isn't told.""" + c = _client(db, client_id, client_secret, check_secret=True) + t = db.one("SELECT gid FROM $r", r=R("oauth_token", auth.sha(raw or ""))) + g = db.one("SELECT record::id(id) AS id, account, client, name FROM $r", r=R("oauth_grant", t["gid"])) if t else None + if not g or g["client"] != c["id"]: + return None + drop_grant(db, g["id"]) + return g diff --git a/fastapi_backend/app/domain/settings.py b/fastapi_backend/app/domain/settings.py index 242377908..fbf123dda 100644 --- a/fastapi_backend/app/domain/settings.py +++ b/fastapi_backend/app/domain/settings.py @@ -109,6 +109,7 @@ def locked(section): "convert_seconds": (10, 3600), } TOKEN_DAYS = (1, 3650) +OAUTH_ACCESS_MINUTES = (5, 1440) VIEWER_URL = re.compile(r"^https?://[^\s]+$") _KEYS, _KL = {}, threading.Lock() @@ -272,6 +273,11 @@ def _check(section, key, value, default): if not (isinstance(value, (int, float)) and not isinstance(value, bool) and 0.05 <= value <= 0.95): raise ValueError("video.object_min_score is a number from 0.05 to 0.95") return float(value) + if (section, key) == ("tokens", "oauth_access_minutes"): + lo, hi = OAUTH_ACCESS_MINUTES + if not (isinstance(value, int) and not isinstance(value, bool) and lo <= value <= hi): + raise ValueError(f"tokens.oauth_access_minutes is a whole number of minutes from {lo} to {hi}") + return value if section == "tokens" and key != "never_expire": lo, hi = TOKEN_DAYS if not (isinstance(value, int) and not isinstance(value, bool) and lo <= value <= hi): @@ -371,6 +377,8 @@ def save(db, base, section, changes, user=None): raise ValueError("thresholds must satisfy 0 ≤ review ≤ match ≤ 1") if section == "tokens" and data.get("default_days", defaults["default_days"]) > data.get("max_days", defaults["max_days"]): raise ValueError("tokens.default_days can't be more than tokens.max_days") + if section == "tokens" and data.get("oauth_refresh_days", defaults["oauth_refresh_days"]) > data.get("max_days", defaults["max_days"]): + raise ValueError("tokens.oauth_refresh_days can't be more than tokens.max_days") if ( section == "server" and "allowed_hosts" in data diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index d89941729..7f6d3b1a3 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -175,8 +175,9 @@ def labels(): "trusted_proxies": ["127.0.0.0/8", "::1/128"], }, # how long API keys last (docs/configuration.md): what a new key gets, the most it may get, and whether keys may - # never expire - "tokens": {"default_days": 90, "max_days": 365, "never_expire": False}, + # never expire; and how long the tokens of apps given access through OAuth last (domain/oauth.py): the access token, + # and the grant after the app last renewed it + "tokens": {"default_days": 90, "max_days": 365, "never_expire": False, "oauth_access_minutes": 60, "oauth_refresh_days": 30}, # audio, video, documents and images uploaded in the web app, in pieces (docs/configuration.md); transcript files use # server.max_upload_mb "uploads": {"max_mb": 4096, "extensions": list(MEDIA_EXT + DOCUMENT_EXT + IMAGE_EXT), "chunk_mb": 8, "expire_hours": 24}, @@ -586,6 +587,14 @@ def close(self): "DEFINE TABLE IF NOT EXISTS api_token SCHEMALESS", "DEFINE INDEX IF NOT EXISTS api_token_hash ON api_token FIELDS hash UNIQUE", "DEFINE INDEX IF NOT EXISTS api_token_account ON api_token FIELDS account", + # OAuth (app/domain/oauth.py): apps that registered, one-time codes, the access people gave them, and its tokens + # (oauth_client:; oauth_code and oauth_token by the hash of the code or token) + "DEFINE TABLE IF NOT EXISTS oauth_client SCHEMALESS", + "DEFINE TABLE IF NOT EXISTS oauth_code SCHEMALESS", + "DEFINE TABLE IF NOT EXISTS oauth_grant SCHEMALESS", + "DEFINE INDEX IF NOT EXISTS oauth_grant_account ON oauth_grant FIELDS account", + "DEFINE TABLE IF NOT EXISTS oauth_token SCHEMALESS", + "DEFINE INDEX IF NOT EXISTS oauth_token_gid ON oauth_token FIELDS gid", "DEFINE TABLE IF NOT EXISTS share_link SCHEMALESS", "DEFINE INDEX IF NOT EXISTS share_link_rec ON share_link FIELDS recording", "DEFINE INDEX IF NOT EXISTS share_link_short ON share_link FIELDS short", diff --git a/fastapi_backend/app/main.py b/fastapi_backend/app/main.py index 97fbbc17b..6f7343a44 100644 --- a/fastapi_backend/app/main.py +++ b/fastapi_backend/app/main.py @@ -14,10 +14,13 @@ from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from fastapi.staticfiles import StaticFiles +from starlette.exceptions import HTTPException as StarletteHTTPException from app.api.iiif import router as iiif_router from app.api.pages import router as pages_router from app.api.v1.router import api_router +from app.api.v1.routes.oauth import bearer_challenge +from app.api.v1.routes.oauth import well_known as oauth_well_known from app.config import settings from app.core import middleware from app.core.runtime import Archive @@ -77,6 +80,8 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: app.add_middleware(middleware.ResourcePaths) app.include_router(api_router, prefix="/api/v1") + app.include_router(oauth_well_known) + app.add_exception_handler(StarletteHTTPException, bearer_challenge) # type: ignore[arg-type] app.include_router(iiif_router) app.include_router(pages_router) app.mount("/static", StaticFiles(directory=str(WEB_DIR)), name="static") diff --git a/fastapi_backend/app/schemas/auth.py b/fastapi_backend/app/schemas/auth.py index 2f7d19e78..68ba6a901 100644 --- a/fastapi_backend/app/schemas/auth.py +++ b/fastapi_backend/app/schemas/auth.py @@ -53,7 +53,7 @@ class Me(ResponseModel): partial: list[str] = Field( default_factory=list, description="namespaces you have no role in but see some collections of (roles on collections)" ) - via: Literal["access", "token"] + via: Literal["access", "token", "oauth"] scope: Literal["read", "write"] diff --git a/fastapi_backend/app/schemas/oauth.py b/fastapi_backend/app/schemas/oauth.py new file mode 100644 index 000000000..bfa53ea78 --- /dev/null +++ b/fastapi_backend/app/schemas/oauth.py @@ -0,0 +1,92 @@ +"""OAuth: apps that register, the consent page's questions and answers, tokens, and the apps a person gave access to.""" + +from __future__ import annotations + +from typing import Literal + +from pydantic import BaseModel, ConfigDict, Field + +from app.schemas.common import RequestModel, ResponseModel + +Scope = Literal["read", "read write"] + + +class ClientRegistration(BaseModel): + """Dynamic client registration (RFC 7591). Metadata Lens has no use for is ignored, as the RFC asks.""" + + model_config = ConfigDict(extra="ignore") + + redirect_uris: list[str] = Field(description="https, http://localhost (any port), or the app's own scheme; 1 to 10") + client_name: str | None = Field(None, description="shown on the consent page and in the list of apps with access") + client_uri: str | None = None + token_endpoint_auth_method: str = Field("none", description="none (public apps), client_secret_post or client_secret_basic") + grant_types: list[str] | None = None + response_types: list[str] | None = None + scope: str | None = None + + +class ClientRegistered(ResponseModel): + client_id: str + client_secret: str | None = Field(None, description="only for apps that asked for one; shown once") + client_id_issued_at: int + client_secret_expires_at: int = Field(0, description="0: it doesn't expire") + client_name: str + client_uri: str | None = None + redirect_uris: list[str] + token_endpoint_auth_method: str + grant_types: list[str] = ["authorization_code", "refresh_token"] + response_types: list[str] = ["code"] + scope: str = "read write" + + +class ConsentClient(ResponseModel): + id: str + name: str + uri: str | None = None + + +class Consent(ResponseModel): + """What the consent page shows.""" + + client: ConsentClient + redirect_uri: str + scope: Scope = Field(description="what the app asks for: read, or read and write") + granted: Scope | None = Field(None, description="what you gave this app before, if anything") + + +class ConsentAnswer(RequestModel): + client_id: str + redirect_uri: str + response_type: str = "code" + code_challenge: str + code_challenge_method: str = "S256" + scope: str | None = None + state: str | None = Field(None, max_length=2000) + resource: str | None = Field(None, max_length=500) + approve: bool + grant: Scope | None = Field(None, description="give less than was asked for (read); default: what was asked for") + + +class ConsentResult(ResponseModel): + redirect_to: str = Field(description="send the browser here: the app's address with its code, or with error=access_denied") + + +class OAuthTokens(ResponseModel): + access_token: str + token_type: Literal["Bearer"] = "Bearer" + expires_in: int = Field(description="seconds until the access token expires") + refresh_token: str + scope: Scope + + +class OAuthGrant(ResponseModel): + """An app you gave access to.""" + + id: int + client: str + name: str + uri: str | None = None + scope: Scope + created_at: str + last_used_at: str | None = None + expires_at: str | None = Field(None, description="when its access ends unless the app renews it before") diff --git a/fastapi_backend/tests/api/test_oauth.py b/fastapi_backend/tests/api/test_oauth.py new file mode 100644 index 000000000..a4f3d1579 --- /dev/null +++ b/fastapi_backend/tests/api/test_oauth.py @@ -0,0 +1,427 @@ +"""OAuth for API and MCP clients (docs/authentication.md#oauth): apps register, people consent, tokens act as them +with their roles, refresh tokens rotate, and access is taken away at once.""" + +from __future__ import annotations + +import base64 +import hashlib +import secrets +import urllib.parse + +from fastapi.testclient import TestClient + +from app.domain import auth, oauth, store +from tests.helpers import login, make_user, seed + +BACK = "https://app.example/callback" +O = "/api/v1/oauth" + + +def _pkce(): + verifier = secrets.token_urlsafe(48) + return verifier, base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip("=") + + +def _register(client, **over): + r = client.post(f"{O}/register", json={"client_name": "Harbour Notes", "redirect_uris": [BACK], **over}) + assert r.status_code == 201, r.text + return r.json() + + +def _ask(app, challenge, **over): + return {"client_id": app["client_id"], "redirect_uri": BACK, "code_challenge": challenge, "code_challenge_method": "S256", **over} + + +def _code(client, h, app, challenge, **over): + r = client.post(f"{O}/authorize", headers=h, json={**_ask(app, challenge), "approve": True, "state": "xyz", **over}) + assert r.status_code == 200, r.text + q = dict(urllib.parse.parse_qsl(urllib.parse.urlsplit(r.json()["redirect_to"]).query)) + assert q["state"] == "xyz" + return q["code"] + + +def _tokens(client, app, code, verifier, **over): + form = { + "grant_type": "authorization_code", + "client_id": app["client_id"], + "code": code, + "redirect_uri": BACK, + "code_verifier": verifier, + } + return client.post(f"{O}/token", data={**form, **over}) + + +def _grant(client, h, app=None, **over): + """An app with access: (app, tokens).""" + app = app or _register(client) + verifier, challenge = _pkce() + r = _tokens(client, app, _code(client, h, app, challenge, **over), verifier) + assert r.status_code == 200, r.text + return app, r.json() + + +def _bearer(tokens): + return {"Authorization": f"Bearer {tokens['access_token']}"} + + +def test_discovery_says_where_everything_is(client, app): + meta = client.get("/.well-known/oauth-authorization-server").json() + assert meta["issuer"] == "http://127.0.0.1" + assert meta["token_endpoint"] == "http://127.0.0.1/api/v1/oauth/token" + assert meta["registration_endpoint"] == "http://127.0.0.1/api/v1/oauth/register" + assert meta["authorization_endpoint"] == "http://localhost:3000/oauth/authorize" # the web app (FRONTEND_URL) + assert meta["code_challenge_methods_supported"] == ["S256"] and meta["response_types_supported"] == ["code"] + # through the web app, everything is on its address: the one it reports when it's a trusted proxy + via = {"x-forwarded-host": "lens.example.org", "x-forwarded-proto": "https"} + web = TestClient(app, base_url="http://127.0.0.1", client=("127.0.0.1", 50000)) + r = web.get("/.well-known/oauth-authorization-server", headers=via) + meta = r.json() + assert r.headers["cache-control"] == "no-store" + assert meta["issuer"] == "https://lens.example.org" + assert meta["authorization_endpoint"] == "https://lens.example.org/oauth/authorize" + assert meta["revocation_endpoint"] == "https://lens.example.org/api/v1/oauth/revoke" + res = web.get("/.well-known/oauth-protected-resource/mcp", headers=via).json() + assert res == { + "resource": "https://lens.example.org/mcp", + "authorization_servers": ["https://lens.example.org"], + "bearer_methods_supported": ["header"], + "scopes_supported": ["read", "write"], + "resource_name": "Lens", + } + assert web.get("/.well-known/oauth-protected-resource/a b mine[0]["created_at"] + assert client.get(f"{O}/authorize", headers=hv, params=_ask(app, challenge)).json()["granted"] == "read write" + assert client.delete(f"{O}/grants/{mine[0]['id']}", headers=he).status_code == 404 # someone else's + assert client.delete(f"{O}/grants/{mine[0]['id']}", headers=_bearer(tv)).status_code == 403 + assert client.delete(f"{O}/grants/{mine[0]['id']}", headers=hv).status_code == 200 + assert client.get("/api/v1/auth/me", headers=_bearer(tv)).status_code == 401 + r = client.post(f"{O}/token", data={"grant_type": "refresh_token", "client_id": app["client_id"], "refresh_token": tv["refresh_token"]}) + assert (r.status_code, r.json()["error"]) == (400, "invalid_grant") + assert client.get(f"{O}/grants", headers=hv).json() == [] + + audit = sorted( + (a["action"], a.get("email"), (a.get("detail") or {}).get("scope")) for a in client.get("/api/v1/audit", headers=hr).json() + ) + assert ("oauth.client.register", None, None) in audit + assert ("oauth.grant", "vi@x.io", "read write") in audit and ("oauth.grant", "ed@x.io", "read") in audit + assert ("oauth.revoke", "vi@x.io", None) in audit + + +def test_refresh_tokens_rotate_and_a_copied_one_ends_the_grant(client, db): + make_user(db, "vi@x.io", "viewer password 1", roles={"pods": "viewer"}) + h = login(client, "vi@x.io", "viewer password 1") + app, first = _grant(client, h) + renew = lambda t: client.post(f"{O}/token", data={"grant_type": "refresh_token", "client_id": app["client_id"], "refresh_token": t}) # noqa: E731 + r = renew(first["refresh_token"]) + assert r.status_code == 200 and r.headers["cache-control"] == "no-store" + second = r.json() + assert second["refresh_token"] != first["refresh_token"] and second["access_token"] != first["access_token"] + assert client.get("/api/v1/auth/me", headers=_bearer(second)).status_code == 200 + # two requests at once may both carry the old one: within a minute it gets nothing new, and the access stays + assert renew(first["refresh_token"]).json()["error"] == "invalid_grant" + assert client.get("/api/v1/auth/me", headers=_bearer(second)).status_code == 200 + # another app can't use it, and an access token isn't a refresh token + other = _register(client, client_name="Other") + r = client.post( + f"{O}/token", data={"grant_type": "refresh_token", "client_id": other["client_id"], "refresh_token": second["refresh_token"]} + ) + assert r.json()["error"] == "invalid_grant" + assert renew(second["access_token"]).json()["error"] == "invalid_grant" + # later, the old one coming back means it was copied: the grant ends, the newest tokens with it + db.q("UPDATE $r SET rotated_at = $t", r=store.R("oauth_token", auth.sha(first["refresh_token"])), t=oauth._later(-120)) + assert renew(first["refresh_token"]).json()["error"] == "invalid_grant" + assert client.get("/api/v1/auth/me", headers=_bearer(second)).status_code == 401 + assert renew(second["refresh_token"]).status_code == 400 + assert client.get(f"{O}/grants", headers=h).json() == [] + assert not db.values("SELECT VALUE id FROM oauth_token") + + +def test_tokens_end_when_they_expire_or_the_account_is_disabled(client, db): + make_user(db, "root@x.io", "root password 1", admin=True) + uid = make_user(db, "vi@x.io", "viewer password 1", roles={"pods": "viewer"}) + hr, h = login(client, "root@x.io", "root password 1"), login(client, "vi@x.io", "viewer password 1") + # admins set how long they last + put = lambda body: client.put("/api/v1/settings/tokens", headers=hr, json=body) # noqa: E731 + assert put({"oauth_access_minutes": 4}).status_code == 400 + assert put({"oauth_access_minutes": 1441}).status_code == 400 + assert put({"oauth_access_minutes": "60"}).status_code == 400 + assert put({"oauth_refresh_days": 0}).status_code == 400 + assert put({"oauth_refresh_days": 366}).status_code == 400 # more than the most a key may last + assert put({"oauth_access_minutes": 10, "oauth_refresh_days": 7}).status_code == 200 + app, t = _grant(client, h) + assert t["expires_in"] == 600 + g = client.get(f"{O}/grants", headers=h).json()[0] + assert 6 <= (store_time(g["expires_at"]) - store_time(g["created_at"])).days <= 7 + # an expired access token stops; its refresh token still renews + db.q("UPDATE $r SET expires_at = $t", r=store.R("oauth_token", auth.sha(t["access_token"])), t=oauth._later(-5)) + assert client.get("/api/v1/auth/me", headers=_bearer(t)).status_code == 401 + r = client.post(f"{O}/token", data={"grant_type": "refresh_token", "client_id": app["client_id"], "refresh_token": t["refresh_token"]}) + assert r.status_code == 200 + t2 = r.json() + assert not db.values("SELECT VALUE id FROM $r", r=store.R("oauth_token", auth.sha(t["access_token"]))) # swept + # an expired refresh token doesn't + db.q("UPDATE $r SET expires_at = $t", r=store.R("oauth_token", auth.sha(t2["refresh_token"])), t=oauth._later(-5)) + r = client.post(f"{O}/token", data={"grant_type": "refresh_token", "client_id": app["client_id"], "refresh_token": t2["refresh_token"]}) + assert r.json()["error"] == "invalid_grant" + # a disabled account's apps stop too + assert client.get("/api/v1/auth/me", headers=_bearer(t2)).status_code == 200 + assert client.patch(f"/api/v1/users/{uid}", headers=hr, json={"disabled": True}).status_code == 200 + assert client.get("/api/v1/auth/me", headers=_bearer(t2)).status_code == 401 + + +def store_time(s): + import datetime as dt + + return dt.datetime.fromisoformat(s) + + +def test_codes_work_once_with_the_right_verifier(client, db): + make_user(db, "vi@x.io", "viewer password 1", roles={"pods": "viewer"}) + h = login(client, "vi@x.io", "viewer password 1") + app = _register(client) + verifier, challenge = _pkce() + err = lambda r: (r.status_code, r.json()["error"]) # noqa: E731 + + assert err(_tokens(client, app, _code(client, h, app, challenge), "x" * 43)) == (400, "invalid_grant") # the wrong verifier + assert err(_tokens(client, app, _code(client, h, app, challenge), "short")) == (400, "invalid_grant") + assert err(_tokens(client, app, _code(client, h, app, challenge), verifier, redirect_uri=BACK + "/other")) == (400, "invalid_grant") + assert err(_tokens(client, app, "not-a-code", verifier)) == (400, "invalid_grant") + assert err(_tokens(client, app, _code(client, h, app, challenge), verifier, client_id="lc_nobody")) == (401, "invalid_client") + other = _register(client, client_name="Other") + assert err(_tokens(client, app, _code(client, h, app, challenge), verifier, client_id=other["client_id"])) == (400, "invalid_grant") + assert err(_tokens(client, app, _code(client, h, app, challenge), verifier, grant_type="password")) == (400, "unsupported_grant_type") + assert _tokens(client, app, "", verifier).status_code == 400 + assert client.post(f"{O}/token", data={"client_id": app["client_id"]}).status_code == 422 # no grant_type + + # each failed try used its code up: none of them left a grant + assert client.get(f"{O}/grants", headers=h).json() == [] + code = _code(client, h, app, challenge) + r = _tokens(client, app, code, verifier) + assert r.status_code == 200 + assert client.get("/api/v1/auth/me", headers=_bearer(r.json())).status_code == 200 + # once: a code that comes back was probably intercepted, so the tokens it gave stop working + assert err(_tokens(client, app, code, verifier)) == (400, "invalid_grant") + assert client.get("/api/v1/auth/me", headers=_bearer(r.json())).status_code == 401 + assert client.get(f"{O}/grants", headers=h).json() == [] + # and only for five minutes + late = _code(client, h, app, challenge) + db.q("UPDATE $r SET expires_at = $t", r=store.R("oauth_code", auth.sha(late)), t=oauth._later(-1)) + assert err(_tokens(client, app, late, verifier)) == (400, "invalid_grant") + # codes nobody swapped don't pile up: the next one made sweeps those that expired + unused = _code(client, h, app, challenge) + db.q("UPDATE $r SET expires_at = $t", r=store.R("oauth_code", auth.sha(unused)), t=oauth._later(-1)) + _code(client, h, app, challenge) + assert not db.values("SELECT VALUE id FROM $r", r=store.R("oauth_code", auth.sha(unused))) + + +def test_consent_refuses_requests_it_cant_answer(client, db): + make_user(db, "vi@x.io", "viewer password 1", roles={"pods": "viewer"}) + h = login(client, "vi@x.io", "viewer password 1") + app = _register(client) + _, challenge = _pkce() + ask = lambda **over: client.get(f"{O}/authorize", headers=h, params={**_ask(app, challenge), **over}) # noqa: E731 + assert ask().status_code == 200 + assert "isn't registered" in ask(client_id="lc_nobody").json()["detail"] + assert "isn't one it registered" in ask(redirect_uri="https://evil.example/callback").json()["detail"] + assert "authorization code" in ask(response_type="token").json()["detail"] + assert "PKCE" in ask(code_challenge_method="plain").json()["detail"] + assert "PKCE" in ask(code_challenge="short").json()["detail"] + assert ask(code_challenge="").status_code == 400 + # the answer is checked the same way, and never sends anyone to an address the app didn't register + r = client.post( + f"{O}/authorize", headers=h, json={**_ask(app, challenge), "redirect_uri": "https://evil.example/callback", "approve": True} + ) + assert r.status_code == 400 + assert client.post(f"{O}/authorize", headers=h, json={**_ask(app, challenge), "approve": True, "extra": 1}).status_code == 422 + assert client.post(f"{O}/authorize", json={**_ask(app, challenge), "approve": True}).status_code == 401 + # no: the app hears so, with its state, and gets no code + r = client.post(f"{O}/authorize", headers=h, json={**_ask(app, challenge), "approve": False, "state": "s 1"}) + assert r.json() == {"redirect_to": BACK + "?error=access_denied&state=s+1"} + assert not db.values("SELECT VALUE id FROM oauth_code") + assert not [a for a in db.rows("SELECT action FROM audit_log") if a["action"] == "oauth.grant"] + + +def test_registering_apps(client, db): + reg = lambda **body: client.post(f"{O}/register", json=body) # noqa: E731 + bad = lambda *uris: reg(redirect_uris=list(uris)).json().get("error") # noqa: E731 + assert bad("javascript:alert(1)") == "invalid_redirect_uri" + assert bad("data:text/html,x") == "invalid_redirect_uri" + assert bad("http://example.org/callback") == "invalid_redirect_uri" # http only on this machine + assert bad("https://app.example/cb#frag") == "invalid_redirect_uri" + assert bad("https:///nohost") == "invalid_redirect_uri" + assert bad("no scheme") == "invalid_redirect_uri" + assert bad("https://user@app.example/cb") == "invalid_redirect_uri" + assert bad("http://evil.example\\@localhost/cb") == "invalid_redirect_uri" + assert bad("ms-msdt:/id") == "invalid_redirect_uri" and bad("intent://x#Intent;end") == "invalid_redirect_uri" + assert bad() == "invalid_redirect_uri" + assert bad(*[f"https://app.example/{n}" for n in range(11)]) == "invalid_redirect_uri" + assert reg(client_name="X").status_code == 422 + assert reg(redirect_uris=[BACK], token_endpoint_auth_method="private_key_jwt").json()["error"] == "invalid_client_metadata" + assert not db.values("SELECT VALUE id FROM oauth_client") + + # metadata Lens has no use for is ignored; names are tidied; apps on this machine and with their own scheme register + r = reg( + client_name=" Desk App ", + redirect_uris=["http://127.0.0.1:7777/cb", "cursor://anysphere.cursor/oauth/callback"], + client_uri="https://desk.example", + logo_uri="https://desk.example/logo.png", + grant_types=["authorization_code", "refresh_token"], + software_id="desk", + ) + assert r.status_code == 201 and r.headers["cache-control"] == "no-store" + desk = r.json() + assert (desk["client_name"], desk["client_uri"], desk["client_secret_expires_at"]) == ("Desk App", "https://desk.example", 0) + assert reg(redirect_uris=[BACK]).json()["client_name"] == "An app" + assert reg(redirect_uris=[BACK], client_uri="javascript:alert(1)").json().get("client_uri") is None + + # on this machine an app listens on whichever port is free + make_user(db, "vi@x.io", "viewer password 1", roles={"pods": "viewer"}) + h = login(client, "vi@x.io", "viewer password 1") + _, challenge = _pkce() + ask = lambda uri: client.get(f"{O}/authorize", headers=h, params={**_ask(desk, challenge), "redirect_uri": uri}).status_code # noqa: E731 + assert ask("http://127.0.0.1:51234/cb") == 200 + assert ask("http://127.0.0.1:51234/other") == 400 + assert ask("http://localhost:7777/cb") == 400 + assert ask("http://evil.example\\@127.0.0.1:7777/cb") == 400 # browsers read the backslash as a slash + assert ask("http://evil.example@127.0.0.1:7777/cb") == 400 + assert ask("cursor://anysphere.cursor/oauth/callback") == 200 + assert ask("cursor://anysphere.cursor/oauth/elsewhere") == 400 + + # apps nobody gave access to are forgotten after a week; ones in use stay + used, _ = _grant(client, h) + db.q("UPDATE oauth_client SET created_at = $t", t=oauth._later(-8 * 86400)) + assert reg(redirect_uris=[BACK]).status_code == 201 + left = db.values("SELECT VALUE record::id(id) FROM oauth_client WHERE created_at < $t", t=oauth._later(-86400)) + assert left == [used["client_id"]] + + # registering is open, so it's throttled per address + auth._FAILS.clear() + codes = [reg(redirect_uris=[BACK]).status_code for _ in range(9)] + assert codes == [201] * 8 + [429] + + +def test_apps_with_a_secret_have_to_show_it(client, db): + make_user(db, "vi@x.io", "viewer password 1", roles={"pods": "viewer"}) + h = login(client, "vi@x.io", "viewer password 1") + app = _register(client, token_endpoint_auth_method="client_secret_post") + assert app["client_secret"].startswith("ls_") + assert not db.values("SELECT VALUE id FROM oauth_client WHERE secret = $s", s=app["client_secret"]) # only its hash is kept + verifier, challenge = _pkce() + r = _tokens(client, app, _code(client, h, app, challenge), verifier) + assert (r.status_code, r.json()["error"], r.headers["www-authenticate"]) == (401, "invalid_client", "Basic") + assert _tokens(client, app, _code(client, h, app, challenge), verifier, client_secret="ls_wrong").status_code == 401 + t = _tokens(client, app, _code(client, h, app, challenge), verifier, client_secret=app["client_secret"]).json() + assert t["scope"] == "read" + # or in the Authorization header (client_secret_basic) + basic = lambda secret: {"Authorization": "Basic " + base64.b64encode(f"{app['client_id']}:{secret}".encode()).decode()} # noqa: E731 + renew = {"grant_type": "refresh_token", "refresh_token": t["refresh_token"]} + assert client.post(f"{O}/token", data=renew, headers=basic("ls_wrong")).status_code == 401 + assert client.post(f"{O}/token", data=renew, headers={"Authorization": "Basic !!!"}).status_code == 401 + t = client.post(f"{O}/token", data=renew, headers=basic(app["client_secret"])).json() + + # the app hands its token back: the grant ends; unknown tokens answer the same + revoke = lambda token, **over: client.post(f"{O}/revoke", data={"token": token, "client_id": app["client_id"], **over}) # noqa: E731 + assert revoke(t["refresh_token"]).status_code == 401 # without its secret + assert revoke("lr_unknown", client_secret=app["client_secret"]).json() == {"ok": True} + assert client.get("/api/v1/auth/me", headers=_bearer(t)).status_code == 200 + other = _register(client, client_name="Other") + assert client.post(f"{O}/revoke", data={"token": t["access_token"], "client_id": other["client_id"]}).json() == {"ok": True} + assert client.get("/api/v1/auth/me", headers=_bearer(t)).status_code == 200 # another app's token: left alone + assert revoke(t["access_token"], client_secret=app["client_secret"]).json() == {"ok": True} + assert client.get("/api/v1/auth/me", headers=_bearer(t)).status_code == 401 + assert client.get(f"{O}/grants", headers=h).json() == [] + row = db.one("SELECT email, detail FROM audit_log WHERE action = 'oauth.revoke'") + assert row["email"] == "vi@x.io" and row["detail"]["by"] == "app" + + +def test_redirects_keep_the_apps_own_query(): + assert oauth.with_params("https://a.example/cb?x=1", code="c d", state=None) == "https://a.example/cb?x=1&code=c+d" + assert oauth.scopes("write") == "read write" and oauth.scopes("email profile") == "read" and oauth.scopes(None) == "read" + assert not oauth.redirect_ok(["https://a.example/cb"], "http://[bad") + assert oauth.token_account(None, "la_not_oauth") is None and oauth.get_client(None, "nope") is None diff --git a/nextjs-frontend/.env.example b/nextjs-frontend/.env.example index 1ef736974..e5a81724a 100644 --- a/nextjs-frontend/.env.example +++ b/nextjs-frontend/.env.example @@ -7,6 +7,9 @@ API_BASE_URL=http://localhost:8000 AUTH_SECRET=change-me # Trust the Host / X-Forwarded-* headers (needed behind docker or a reverse proxy). AUTH_TRUST_HOST=true +# Pass a reverse proxy's X-Forwarded-Host / -Proto on to the API (OAuth discovery names that address). +# Leave off unless a proxy in front of this app sets them: browsers could otherwise choose them. +# TRUST_PROXY_HEADERS=true # The public URL of this app; only needed when it can't be inferred from the request. # AUTH_URL=http://localhost:3000 diff --git a/nextjs-frontend/__tests__/backend-proxy.test.ts b/nextjs-frontend/__tests__/backend-proxy.test.ts new file mode 100644 index 000000000..e25d4692e --- /dev/null +++ b/nextjs-frontend/__tests__/backend-proxy.test.ts @@ -0,0 +1,43 @@ +/** @jest-environment node */ +import { browserAddress, trustProxyHeaders } from "@/lib/api/backend-proxy"; + +describe("browserAddress", () => { + const incoming = new URL("http://127.0.0.1:3000/.well-known/oauth-authorization-server"); + const spoofed = new Headers({ host: "lens.example", "x-forwarded-host": "evil.tld", "x-forwarded-proto": "https" }); + + it("ignores a browser's own X-Forwarded-* unless a proxy is trusted", () => { + expect(browserAddress(spoofed, incoming, false)).toEqual({ host: "lens.example", proto: "http" }); + }); + + it("passes on what a trusted reverse proxy reports, its first value", () => { + const h = new Headers({ + host: "web:3000", + "x-forwarded-host": "lens.example, inner", + "x-forwarded-proto": "https", + }); + expect(browserAddress(h, incoming, true)).toEqual({ host: "lens.example", proto: "https" }); + }); + + it("falls back to Host and Next's own address", () => { + expect(browserAddress(new Headers({ host: "lens.example" }), incoming, true)).toEqual({ + host: "lens.example", + proto: "http", + }); + expect(browserAddress(new Headers(), incoming, false)).toEqual({ host: "127.0.0.1:3000", proto: "http" }); + }); + + it("trusts proxy headers only when TRUST_PROXY_HEADERS says so", () => { + const before = process.env.TRUST_PROXY_HEADERS; + try { + delete process.env.TRUST_PROXY_HEADERS; + expect(trustProxyHeaders()).toBe(false); + process.env.TRUST_PROXY_HEADERS = "true"; + expect(trustProxyHeaders()).toBe(true); + process.env.TRUST_PROXY_HEADERS = "no"; + expect(trustProxyHeaders()).toBe(false); + } finally { + if (before === undefined) delete process.env.TRUST_PROXY_HEADERS; + else process.env.TRUST_PROXY_HEADERS = before; + } + }); +}); diff --git a/nextjs-frontend/__tests__/oauth-model.test.ts b/nextjs-frontend/__tests__/oauth-model.test.ts new file mode 100644 index 000000000..2a1d53642 --- /dev/null +++ b/nextjs-frontend/__tests__/oauth-model.test.ts @@ -0,0 +1,78 @@ +import { ACCESS_LABEL, appHost, canWrite, consentRequest, returnsTo, safeToFollow } from "@/components/oauth/model"; + +describe("the consent request in the page's query", () => { + it("reads what the app asked for", () => { + expect( + consentRequest({ + client_id: "lc_1", + redirect_uri: "https://app.example/cb", + code_challenge: "c".repeat(43), + code_challenge_method: "S256", + scope: "read write", + state: ["s1", "s2"], + }), + ).toEqual({ + client_id: "lc_1", + redirect_uri: "https://app.example/cb", + response_type: "code", + code_challenge: "c".repeat(43), + code_challenge_method: "S256", + scope: "read write", + state: "s1", + resource: undefined, + }); + }); + + it("is nothing without an app or an address to return to", () => { + expect(consentRequest({ redirect_uri: "https://app.example/cb" })).toBeNull(); + expect(consentRequest({ client_id: "lc_1" })).toBeNull(); + expect(consentRequest({ client_id: "lc_1", redirect_uri: "x" })?.code_challenge).toBe(""); + }); +}); + +describe("where the browser may be sent", () => { + it("follows https, this machine and an app's own scheme", () => { + expect(safeToFollow("https://app.example/cb?code=1")).toBe(true); + expect(safeToFollow("http://127.0.0.1:7777/cb?code=1")).toBe(true); + expect(safeToFollow("http://localhost/cb")).toBe(true); + expect(safeToFollow("cursor://anysphere.cursor/oauth?code=1")).toBe(true); + }); + + it("never follows addresses the browser or the system would run", () => { + for (const bad of [ + "javascript:alert(1)", + "data:text/html,x", + "ms-msdt:/id", + "intent://x", + "http://example.org/cb", + "https://user:pw@app.example/cb", + "http://evil.example\\@localhost/cb", + "not a url", + ]) + expect(safeToFollow(bad)).toBe(false); + }); + + it("says where an app returns to in words people know", () => { + expect(returnsTo("https://app.example/cb")).toBe("app.example"); + expect(returnsTo("http://127.0.0.1:7777/cb")).toBe("an app on this computer"); + expect(returnsTo("http://example.org/cb")).toBe("example.org"); + expect(returnsTo("cursor://x/y")).toBe("an app on this device (cursor://)"); + expect(returnsTo("nonsense")).toBe("nonsense"); + }); +}); + +describe("what an app may do", () => { + it("labels scopes", () => { + expect(canWrite("read write")).toBe(true); + expect(canWrite("read")).toBe(false); + expect(canWrite(null)).toBe(false); + expect(ACCESS_LABEL("read write")).toBe("Read & write"); + expect(ACCESS_LABEL("read")).toBe("Read only"); + }); + + it("shows an app's site by its host", () => { + expect(appHost("https://desk.example/about")).toBe("desk.example"); + expect(appHost("nope")).toBeNull(); + expect(appHost(null)).toBeNull(); + }); +}); diff --git a/nextjs-frontend/__tests__/oauth-ui.test.tsx b/nextjs-frontend/__tests__/oauth-ui.test.tsx new file mode 100644 index 000000000..078da7521 --- /dev/null +++ b/nextjs-frontend/__tests__/oauth-ui.test.tsx @@ -0,0 +1,178 @@ +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { fireEvent, render, screen, waitFor, within } from "@testing-library/react"; +import "@testing-library/jest-dom"; + +import type { Consent, OAuthGrant } from "@/app/openapi-client/types.gen"; +import { ConnectedApps } from "@/components/account/apps"; +import { ConsentCard, leave } from "@/components/oauth/consent"; +import type { ConsentRequest } from "@/components/oauth/model"; +import { TooltipProvider } from "@/components/ui/tooltip"; + +const ok = (data: unknown) => Promise.resolve({ data, response: { ok: true, status: 200 } }); +const fail = (status: number, detail: string) => + Promise.resolve({ error: { detail }, response: { ok: false, status } }); +const api = { + consent: jest.fn, [unknown]>(), + answer: jest.fn, [unknown]>(), + listGrants: jest.fn, [unknown]>(), + revokeGrant: jest.fn, [unknown]>(), +}; +jest.mock("@/app/openapi-client", () => ({ + Oauth: { + consent: (a: unknown) => api.consent(a), + answer: (a: unknown) => api.answer(a), + listGrants: (a: unknown) => api.listGrants(a), + revokeGrant: (a: unknown) => api.revokeGrant(a), + }, +})); +jest.mock("next-auth/react", () => ({ useSession: () => ({ data: { accessToken: "t" } }) })); +const toast = jest.fn(); +jest.mock("@/components/ui/toast", () => ({ useToast: () => toast })); + +const request: ConsentRequest = { + client_id: "lc_1", + redirect_uri: "https://app.example/cb", + response_type: "code", + code_challenge: "c".repeat(43), + code_challenge_method: "S256", + scope: "read write", + state: "s1", +}; +const consent = (over: Partial = {}): Consent => ({ + client: { id: "lc_1", name: "Harbour Notes", uri: "https://harbour.example" }, + redirect_uri: "https://app.example/cb", + scope: "read write", + granted: null, + ...over, +}); + +function show(ui: React.ReactNode) { + const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } }); + return render( + + {ui} + , + ); +} + +describe("the consent page", () => { + let go: jest.SpyInstance; + beforeEach(() => { + go = jest.spyOn(leave, "to").mockImplementation(() => {}); + }); + + it("says which app asks and for what, and Allow sends the browser back with the code", async () => { + api.consent.mockReturnValue(ok(consent())); + api.answer.mockReturnValue(ok({ redirect_to: "https://app.example/cb?code=abc&state=s1" })); + show(); + expect(await screen.findByRole("heading", { name: "Give Harbour Notes access?" })).toBeInTheDocument(); + expect(screen.getByText("vi@x.io")).toBeInTheDocument(); + expect(screen.getByText("app.example")).toBeInTheDocument(); + expect(screen.getByText(/harbour\.example/)).toBeInTheDocument(); + expect(screen.getByRole("switch", { name: "Let it make changes" })).toBeChecked(); + fireEvent.click(screen.getByRole("button", { name: "Allow" })); + await waitFor(() => expect(go).toHaveBeenCalledWith("https://app.example/cb?code=abc&state=s1")); + expect(api.answer).toHaveBeenCalledWith( + expect.objectContaining({ body: { ...request, approve: true, grant: "read write" } }), + ); + }); + + it("gives read only when changes are switched off, and asks for nothing more when only read was asked", async () => { + api.consent.mockReturnValue(ok(consent({ granted: "read" }))); + api.answer.mockReturnValue(ok({ redirect_to: "https://app.example/cb?code=abc" })); + const first = show(); + expect(await screen.findByText(/You gave this app access before/)).toBeInTheDocument(); + fireEvent.click(screen.getByRole("switch", { name: "Let it make changes" })); + fireEvent.click(screen.getByRole("button", { name: "Allow" })); + await waitFor(() => expect(go).toHaveBeenCalled()); + expect(api.answer).toHaveBeenCalledWith( + expect.objectContaining({ body: expect.objectContaining({ grant: "read" }) }), + ); + first.unmount(); + + api.consent.mockReturnValue(ok(consent({ scope: "read" }))); + show(); + await screen.findByRole("heading", { name: "Give Harbour Notes access?" }); + expect(screen.queryByRole("switch")).not.toBeInTheDocument(); + }); + + it("Deny tells the app so", async () => { + api.consent.mockReturnValue(ok(consent())); + api.answer.mockReturnValue(ok({ redirect_to: "https://app.example/cb?error=access_denied&state=s1" })); + show(); + fireEvent.click(await screen.findByRole("button", { name: "Deny" })); + await waitFor(() => expect(go).toHaveBeenCalledWith("https://app.example/cb?error=access_denied&state=s1")); + expect(api.answer).toHaveBeenCalledWith( + expect.objectContaining({ body: { ...request, approve: false, grant: undefined } }), + ); + }); + + it("sends nobody anywhere for a request the server refuses, an address a browser shouldn't open, or no request", async () => { + api.consent.mockReturnValue(fail(400, "The address this app wants to return to isn't one it registered.")); + const refused = show(); + expect(await screen.findByText(/isn't one it registered/)).toBeInTheDocument(); + expect(screen.queryByRole("button", { name: "Allow" })).not.toBeInTheDocument(); + refused.unmount(); + + api.consent.mockReturnValue(ok(consent())); + api.answer.mockReturnValue(ok({ redirect_to: "javascript:alert(1)" })); + const unsafe = show(); + fireEvent.click(await screen.findByRole("button", { name: "Allow" })); + expect(await screen.findByText(/can’t be opened from a browser/)).toBeInTheDocument(); + unsafe.unmount(); + + api.answer.mockReturnValue(fail(403, "sign in to give an app access; API tokens and apps can't")); + const failed = show(); + fireEvent.click(await screen.findByRole("button", { name: "Allow" })); + expect(await screen.findByText(/sign in to give an app access/)).toBeInTheDocument(); + failed.unmount(); + + show(); + expect(screen.getByRole("heading", { name: "Nothing to give access to" })).toBeInTheDocument(); + expect(go).not.toHaveBeenCalled(); + }); +}); + +describe("apps with access", () => { + const grant = (over: Partial = {}): OAuthGrant => ({ + id: 3, + client: "lc_1", + name: "Harbour Notes", + uri: "https://harbour.example", + scope: "read write", + created_at: "2026-09-30T10:00:00+00:00", + last_used_at: null, + expires_at: "2099-01-01T00:00:00+00:00", + ...over, + }); + + it("lists them and revokes one after asking", async () => { + api.listGrants.mockReturnValue(ok([grant(), grant({ id: 4, name: "Desk", uri: null, scope: "read" })])); + api.revokeGrant.mockReturnValue(ok({ ok: true })); + show(); + const table = await screen.findByRole("table", { name: "Apps with access" }); + expect(within(table).getByText("Harbour Notes")).toBeInTheDocument(); + expect(within(table).getByText("harbour.example")).toBeInTheDocument(); + expect(within(table).getByText("Read & write")).toBeInTheDocument(); + expect(within(table).getByText("Read only")).toBeInTheDocument(); + fireEvent.click(screen.getByRole("button", { name: "Revoke Harbour Notes" })); + const dialog = await screen.findByRole("dialog"); + fireEvent.click(within(dialog).getByRole("button", { name: "Revoke access" })); + await waitFor(() => + expect(api.revokeGrant).toHaveBeenCalledWith(expect.objectContaining({ path: { grant_id: 3 } })), + ); + await waitFor(() => + expect(toast).toHaveBeenCalledWith(expect.objectContaining({ title: "Harbour Notes no longer has access" })), + ); + }); + + it("says when there are none, and when they can't be loaded", async () => { + api.listGrants.mockReturnValue(ok([])); + const none = show(); + expect(await screen.findByText("You haven’t given any app access.")).toBeInTheDocument(); + none.unmount(); + api.listGrants.mockReturnValue(fail(500, "boom")); + show(); + expect(await screen.findByText("Couldn’t load your apps")).toBeInTheDocument(); + }); +}); diff --git a/nextjs-frontend/app/(app)/account/tokens/page.tsx b/nextjs-frontend/app/(app)/account/tokens/page.tsx index 2b2fa6d5a..37f0b9da6 100644 --- a/nextjs-frontend/app/(app)/account/tokens/page.tsx +++ b/nextjs-frontend/app/(app)/account/tokens/page.tsx @@ -1,10 +1,16 @@ import type { Metadata } from "next"; +import { ConnectedApps } from "@/components/account/apps"; import { TokensPage } from "@/components/account/tokens"; export const metadata: Metadata = { title: "API tokens" }; -/** API tokens: list · create · shown once · revoke (Access AC5). */ +/** API tokens: list · create · shown once · revoke (Access AC5); and the apps given access through OAuth. */ export default function AccountTokensPage() { - return ; + return ( + <> + + + + ); } diff --git a/nextjs-frontend/app/.well-known/[...path]/route.ts b/nextjs-frontend/app/.well-known/[...path]/route.ts new file mode 100644 index 000000000..74a133708 --- /dev/null +++ b/nextjs-frontend/app/.well-known/[...path]/route.ts @@ -0,0 +1,6 @@ +import { handlers } from "@/lib/api/backend-proxy"; + +// OAuth discovery for API and MCP clients (docs/authentication.md#oauth), answered by the API with this origin's +// addresses; see lib/api/backend-proxy.ts. +export const dynamic = "force-dynamic"; +export const { GET, HEAD, OPTIONS } = handlers; diff --git a/nextjs-frontend/app/oauth/authorize/page.tsx b/nextjs-frontend/app/oauth/authorize/page.tsx new file mode 100644 index 000000000..4ec4d7632 --- /dev/null +++ b/nextjs-frontend/app/oauth/authorize/page.tsx @@ -0,0 +1,41 @@ +import type { Metadata } from "next"; +import { redirect } from "next/navigation"; +import { SessionProvider } from "next-auth/react"; + +import { auth } from "@/auth"; +import { ConsentCard } from "@/components/oauth/consent"; +import { consentRequest } from "@/components/oauth/model"; +import { AppProviders } from "@/components/providers"; + +export const metadata: Metadata = { title: "Give an app access", robots: { index: false } }; + +/** + * The OAuth consent page (docs/authentication.md#oauth): an app sends someone here; signed in, they see which app + * asks, for what, and say yes or no. proxy.ts sends signed-out people to sign in first and brings them back. + */ +export default async function AuthorizePage({ + searchParams, +}: { + searchParams: Promise>; +}) { + const params = await searchParams; + const session = await auth(); + if (!session || session.error) { + const query = new URLSearchParams( + Object.entries(params).flatMap(([k, v]) => (v === undefined ? [] : [[k, Array.isArray(v) ? v[0] : v]])), + ); + redirect(`/login?callbackUrl=${encodeURIComponent(`/oauth/authorize?${query}`)}`); + } + return ( + // no refetch on focus: leaving for the app's address would start one and cut it off + + +
+
+ +
+
+
+
+ ); +} diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index b09bf79a5..33fb4de2d 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -1,6 +1,6 @@ // This file is auto-generated by @hey-api/openapi-ts -import type { Options as ClientOptions, Client, TDataShape } from "./client"; +import { type Options as ClientOptions, type Client, type TDataShape, urlSearchParamsBodySerializer } from "./client"; import type { StatusData, StatusResponses, @@ -40,6 +40,26 @@ import type { RevokeTokenData, RevokeTokenResponses, RevokeTokenErrors, + RegisterData, + RegisterResponses, + RegisterErrors, + ConsentData, + ConsentResponses, + ConsentErrors, + AnswerData, + AnswerResponses, + AnswerErrors, + TokenData, + TokenResponses, + TokenErrors, + RevokeData, + RevokeResponses, + RevokeErrors, + ListGrantsData, + ListGrantsResponses, + RevokeGrantData, + RevokeGrantResponses, + RevokeGrantErrors, ListUsersData, ListUsersResponses, CreateUserData, @@ -1041,6 +1061,110 @@ export class Tokens { } } +export class Oauth { + /** + * Register + * An app registers itself (RFC 7591), without signing in: it gets a `client_id`, and a `client_secret` if it + * asked for one. It can do nothing until someone gives it access. Audited as `oauth.client.register`. + */ + public static register(options: Options) { + return (options.client ?? client).post({ + url: "/api/v1/oauth/register", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Consent + * What the consent page shows for an app's request: the app, where it takes you back to and what it asks for. + * 400 when the request can't be answered (an unknown app, an address it didn't register, no PKCE challenge). + */ + public static consent(options: Options) { + return (options.client ?? client).get({ + url: "/api/v1/oauth/authorize", + ...options, + }); + } + + /** + * Answer + * Your answer to an app's request. Yes gives it a one-time code (five minutes) at its redirect address, which + * it swaps for tokens that act as you, with your roles; no sends it `error=access_denied`. Audited as + * `oauth.grant`. + */ + public static answer(options: Options) { + return (options.client ?? client).post({ + url: "/api/v1/oauth/authorize", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Token + * The app swaps its code (`grant_type=authorization_code`, with `code_verifier` and the same `redirect_uri`) + * or its refresh token (`grant_type=refresh_token`) for an access token and a new refresh token. Form-encoded, as + * OAuth has it; errors are `{error, error_description}`. + */ + public static token(options: Options) { + return (options.client ?? client).post({ + ...urlSearchParamsBodySerializer, + url: "/api/v1/oauth/token", + ...options, + headers: { + "Content-Type": "application/x-www-form-urlencoded", + ...options.headers, + }, + }); + } + + /** + * Revoke + * An app hands back a token, access or refresh (RFC 7009): the access it was given ends. Answers the same + * whether or not the token was known. Audited as `oauth.revoke`. + */ + public static revoke(options: Options) { + return (options.client ?? client).post({ + ...urlSearchParamsBodySerializer, + url: "/api/v1/oauth/revoke", + ...options, + headers: { + "Content-Type": "application/x-www-form-urlencoded", + ...options.headers, + }, + }); + } + + /** + * List Grants + * The apps you gave access to, the latest first. + */ + public static listGrants(options?: Options) { + return (options?.client ?? client).get({ + url: "/api/v1/oauth/grants", + ...options, + }); + } + + /** + * Revoke Grant + * Take an app's access away: its tokens stop working now. Audited as `oauth.revoke`. + */ + public static revokeGrant(options: Options) { + return (options.client ?? client).delete({ + url: "/api/v1/oauth/grants/{grant_id}", + ...options, + }); + } +} + export class Users { /** * List Users diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 36bec234b..da746f357 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -816,6 +816,58 @@ export type BatchSummary = { [key: string]: unknown | number | string | string | null | string | null | BatchProgress | undefined; }; +/** + * Body_oauth-revoke + */ +export type BodyOauthRevoke = { + /** + * Token + */ + token: string; + /** + * Client Id + */ + client_id?: string | null; + /** + * Client Secret + */ + client_secret?: string | null; +}; + +/** + * Body_oauth-token + */ +export type BodyOauthToken = { + /** + * Grant Type + */ + grant_type: string; + /** + * Code + */ + code?: string | null; + /** + * Redirect Uri + */ + redirect_uri?: string | null; + /** + * Code Verifier + */ + code_verifier?: string | null; + /** + * Refresh Token + */ + refresh_token?: string | null; + /** + * Client Id + */ + client_id?: string | null; + /** + * Client Secret + */ + client_secret?: string | null; +}; + /** * BrowseEntry */ @@ -1157,6 +1209,108 @@ export type ChatUpdate = { model?: string | null; }; +/** + * ClientRegistered + */ +export type ClientRegistered = { + /** + * Client Id + */ + client_id: string; + /** + * Client Secret + * only for apps that asked for one; shown once + */ + client_secret?: string | null; + /** + * Client Id Issued At + */ + client_id_issued_at: number; + /** + * Client Secret Expires At + * 0: it doesn't expire + */ + client_secret_expires_at?: number; + /** + * Client Name + */ + client_name: string; + /** + * Client Uri + */ + client_uri?: string | null; + /** + * Redirect Uris + */ + redirect_uris: Array; + /** + * Token Endpoint Auth Method + */ + token_endpoint_auth_method: string; + /** + * Grant Types + */ + grant_types?: Array; + /** + * Response Types + */ + response_types?: Array; + /** + * Scope + */ + scope?: string; + [key: string]: + | unknown + | string + | string + | null + | number + | string + | null + | Array + | Array + | Array + | undefined; +}; + +/** + * ClientRegistration + * Dynamic client registration (RFC 7591). Metadata Lens has no use for is ignored, as the RFC asks. + */ +export type ClientRegistration = { + /** + * Redirect Uris + * https, http://localhost (any port), or the app's own scheme; 1 to 10 + */ + redirect_uris: Array; + /** + * Client Name + * shown on the consent page and in the list of apps with access + */ + client_name?: string | null; + /** + * Client Uri + */ + client_uri?: string | null; + /** + * Token Endpoint Auth Method + * none (public apps), client_secret_post or client_secret_basic + */ + token_endpoint_auth_method?: string; + /** + * Grant Types + */ + grant_types?: Array | null; + /** + * Response Types + */ + response_types?: Array | null; + /** + * Scope + */ + scope?: string | null; +}; + /** * Collection */ @@ -1781,6 +1935,107 @@ export type CommentUpdate = { resolved?: boolean | null; }; +/** + * Consent + * What the consent page shows. + */ +export type Consent = { + client: ConsentClient; + /** + * Redirect Uri + */ + redirect_uri: string; + /** + * Scope + * what the app asks for: read, or read and write + */ + scope: "read" | "read write"; + /** + * Granted + * what you gave this app before, if anything + */ + granted?: "read" | "read write" | null; + [key: string]: unknown | ConsentClient | string | "read" | "read write" | "read" | "read write" | null | undefined; +}; + +/** + * ConsentAnswer + */ +export type ConsentAnswer = { + /** + * Client Id + */ + client_id: string; + /** + * Redirect Uri + */ + redirect_uri: string; + /** + * Response Type + */ + response_type?: string; + /** + * Code Challenge + */ + code_challenge: string; + /** + * Code Challenge Method + */ + code_challenge_method?: string; + /** + * Scope + */ + scope?: string | null; + /** + * State + */ + state?: string | null; + /** + * Resource + */ + resource?: string | null; + /** + * Approve + */ + approve: boolean; + /** + * Grant + * give less than was asked for (read); default: what was asked for + */ + grant?: "read" | "read write" | null; +}; + +/** + * ConsentClient + */ +export type ConsentClient = { + /** + * Id + */ + id: string; + /** + * Name + */ + name: string; + /** + * Uri + */ + uri?: string | null; + [key: string]: unknown | string | string | null | undefined; +}; + +/** + * ConsentResult + */ +export type ConsentResult = { + /** + * Redirect To + * send the browser here: the app's address with its code, or with error=access_denied + */ + redirect_to: string; + [key: string]: unknown | string; +}; + /** * ContentRules * How a subtype is recognised when nobody chose it: every rule given has to hold. @@ -4158,7 +4413,7 @@ export type Me = { /** * Via */ - via: "access" | "token"; + via: "access" | "token" | "oauth"; /** * Scope */ @@ -4172,6 +4427,7 @@ export type Me = { | Array | "access" | "token" + | "oauth" | "read" | "write" | undefined; @@ -5241,6 +5497,87 @@ export type NotifyTestResult = { [key: string]: unknown | boolean | number | null | string | null | undefined; }; +/** + * OAuthGrant + * An app you gave access to. + */ +export type OAuthGrant = { + /** + * Id + */ + id: number; + /** + * Client + */ + client: string; + /** + * Name + */ + name: string; + /** + * Uri + */ + uri?: string | null; + /** + * Scope + */ + scope: "read" | "read write"; + /** + * Created At + */ + created_at: string; + /** + * Last Used At + */ + last_used_at?: string | null; + /** + * Expires At + * when its access ends unless the app renews it before + */ + expires_at?: string | null; + [key: string]: + | unknown + | number + | string + | string + | null + | "read" + | "read write" + | string + | null + | string + | null + | undefined; +}; + +/** + * OAuthTokens + */ +export type OAuthTokens = { + /** + * Access Token + */ + access_token: string; + /** + * Token Type + */ + token_type?: "Bearer"; + /** + * Expires In + * seconds until the access token expires + */ + expires_in: number; + /** + * Refresh Token + */ + refresh_token: string; + /** + * Scope + */ + scope: "read" | "read write"; + [key: string]: unknown | string | "Bearer" | number | "read" | "read write" | undefined; +}; + /** * ObjectCount */ @@ -11629,6 +11966,219 @@ export type RevokeTokenResponses = { export type RevokeTokenResponse = RevokeTokenResponses[keyof RevokeTokenResponses]; +export type RegisterData = { + body: ClientRegistration; + path?: never; + query?: never; + url: "/api/v1/oauth/register"; +}; + +export type RegisterErrors = { + /** + * OAuth error + */ + 400: unknown; + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type RegisterError = RegisterErrors[keyof RegisterErrors]; + +export type RegisterResponses = { + /** + * Successful Response + */ + 201: ClientRegistered; +}; + +export type RegisterResponse = RegisterResponses[keyof RegisterResponses]; + +export type ConsentData = { + body?: never; + path?: never; + query: { + /** + * Client Id + */ + client_id: string; + /** + * Redirect Uri + */ + redirect_uri: string; + /** + * Code Challenge + */ + code_challenge?: string; + /** + * Code Challenge Method + */ + code_challenge_method?: string; + /** + * Response Type + */ + response_type?: string; + /** + * Scope + */ + scope?: string | null; + }; + url: "/api/v1/oauth/authorize"; +}; + +export type ConsentErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type ConsentError = ConsentErrors[keyof ConsentErrors]; + +export type ConsentResponses = { + /** + * Successful Response + */ + 200: Consent; +}; + +export type ConsentResponse = ConsentResponses[keyof ConsentResponses]; + +export type AnswerData = { + body: ConsentAnswer; + path?: never; + query?: never; + url: "/api/v1/oauth/authorize"; +}; + +export type AnswerErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type AnswerError = AnswerErrors[keyof AnswerErrors]; + +export type AnswerResponses = { + /** + * Successful Response + */ + 200: ConsentResult; +}; + +export type AnswerResponse = AnswerResponses[keyof AnswerResponses]; + +export type TokenData = { + body: BodyOauthToken; + path?: never; + query?: never; + url: "/api/v1/oauth/token"; +}; + +export type TokenErrors = { + /** + * OAuth error + */ + 400: unknown; + /** + * OAuth error + */ + 401: unknown; + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type TokenError = TokenErrors[keyof TokenErrors]; + +export type TokenResponses = { + /** + * Successful Response + */ + 200: OAuthTokens; +}; + +export type TokenResponse = TokenResponses[keyof TokenResponses]; + +export type RevokeData = { + body: BodyOauthRevoke; + path?: never; + query?: never; + url: "/api/v1/oauth/revoke"; +}; + +export type RevokeErrors = { + /** + * OAuth error + */ + 401: unknown; + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type RevokeError = RevokeErrors[keyof RevokeErrors]; + +export type RevokeResponses = { + /** + * Successful Response + */ + 200: Ok; +}; + +export type RevokeResponse = RevokeResponses[keyof RevokeResponses]; + +export type ListGrantsData = { + body?: never; + path?: never; + query?: never; + url: "/api/v1/oauth/grants"; +}; + +export type ListGrantsResponses = { + /** + * Response Oauth-List Grants + * Successful Response + */ + 200: Array; +}; + +export type ListGrantsResponse = ListGrantsResponses[keyof ListGrantsResponses]; + +export type RevokeGrantData = { + body?: never; + path: { + /** + * Grant Id + */ + grant_id: number; + }; + query?: never; + url: "/api/v1/oauth/grants/{grant_id}"; +}; + +export type RevokeGrantErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type RevokeGrantError = RevokeGrantErrors[keyof RevokeGrantErrors]; + +export type RevokeGrantResponses = { + /** + * Successful Response + */ + 200: Ok; +}; + +export type RevokeGrantResponse = RevokeGrantResponses[keyof RevokeGrantResponses]; + export type ListUsersData = { body?: never; path?: never; diff --git a/nextjs-frontend/components/account/apps.tsx b/nextjs-frontend/components/account/apps.tsx new file mode 100644 index 000000000..875931df8 --- /dev/null +++ b/nextjs-frontend/components/account/apps.tsx @@ -0,0 +1,147 @@ +"use client"; + +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; +import { AppWindow } from "lucide-react"; +import { useState } from "react"; + +import { Oauth } from "@/app/openapi-client"; +import type { OAuthGrant } from "@/app/openapi-client/types.gen"; +import { tokenExpiry } from "@/components/account/token-model"; +import { ACCESS_LABEL, appHost } from "@/components/oauth/model"; +import { Banner } from "@/components/ui/banner"; +import { Button } from "@/components/ui/button"; +import { Dialog } from "@/components/ui/dialog"; +import { EmptyState, SkeletonRows } from "@/components/ui/states"; +import { Table, Td, Th, THead, Tr } from "@/components/ui/table"; +import { useToast } from "@/components/ui/toast"; +import { data, useApiClient } from "@/lib/api/browser"; +import { relative, shortDate } from "@/lib/format"; + +/** The apps this person gave access to through OAuth (docs/authentication.md#oauth), each with Revoke. */ +export function ConnectedApps() { + const client = useApiClient(); + const qc = useQueryClient(); + const toast = useToast(); + const [revoking, setRevoking] = useState(null); + const grants = useQuery({ + queryKey: ["oauth", "grants"], + queryFn: () => data(Oauth.listGrants({ client })), + staleTime: 0, // apps are given access in another tab + }); + const revoke = useMutation({ + mutationFn: (g: OAuthGrant) => data(Oauth.revokeGrant({ client, path: { grant_id: g.id } })), + onSuccess: (_r, g) => { + setRevoking(null); + void qc.invalidateQueries({ queryKey: ["oauth", "grants"] }); + toast({ title: `${g.name} no longer has access`, body: "Its tokens stopped working.", tone: "green" }); + }, + }); + const list = grants.data ?? []; + + return ( +
+
+
+

+ Apps with access +

+

+ Apps you signed in to with your Lens account (an assistant, an editor). They act as you, with your roles, + until you revoke them. +

+
+ {grants.isPending ? ( + + ) : grants.isError ? ( + } + title="Couldn’t load your apps" + actions={} + > + {grants.error.message} + + ) : !list.length ? ( +

You haven’t given any app access.

+ ) : ( +
+ + + + + + + + + + + + + {list.map((g) => ( + + + + + + + + + ))} + +
AppAccessGivenLast usedEnds + Actions +
+ {g.name} + {appHost(g.uri) && {appHost(g.uri)}} + + + {ACCESS_LABEL(g.scope)} + + {shortDate(g.created_at)} + {g.last_used_at ? relative(g.last_used_at) : "never"} + + {g.expires_at ? tokenExpiry(g.expires_at).label : "—"} + + +
+
+ )} +
+ { + if (!o) { + revoke.reset(); + setRevoking(null); + } + }} + title={revoking ? `Revoke ${revoking.name}’s access?` : ""} + actions={ + <> + + + + } + > +

+ The app stops working with Lens immediately. To use it again you sign in from the app and allow it once more. +

+ {revoke.isError && {revoke.error.message}} +
+
+ ); +} diff --git a/nextjs-frontend/components/oauth/consent.tsx b/nextjs-frontend/components/oauth/consent.tsx new file mode 100644 index 000000000..ef6cd6f1d --- /dev/null +++ b/nextjs-frontend/components/oauth/consent.tsx @@ -0,0 +1,147 @@ +"use client"; + +import { useMutation, useQuery } from "@tanstack/react-query"; +import Link from "next/link"; +import { useState } from "react"; + +import { Oauth } from "@/app/openapi-client"; +import { AuthAlert, AuthCard } from "@/components/auth/auth-card"; +import { canWrite, returnsTo, safeToFollow, type ConsentRequest } from "@/components/oauth/model"; +import { Button } from "@/components/ui/button"; +import { Switch } from "@/components/ui/field"; +import { Skeleton } from "@/components/ui/states"; +import { data, useApiClient } from "@/lib/api/browser"; + +/** Sends the browser to the app's address. Its own function so tests can watch it. */ +export const leave = { + to(url: string) { + window.location.assign(url); + }, +}; + +/** Which app asks, for what, and Allow or Deny (docs/authentication.md#oauth). Nobody is sent anywhere until the + * server has checked the app and its address. */ +export function ConsentCard({ request, email }: { request: ConsentRequest | null; email: string }) { + const client = useApiClient(); + const [write, setWrite] = useState(true); + const [stuck, setStuck] = useState(null); + const info = useQuery({ + queryKey: ["oauth", "consent", request], + enabled: Boolean(request), + retry: false, + queryFn: () => + data( + Oauth.consent({ + client, + query: { + client_id: request!.client_id, + redirect_uri: request!.redirect_uri, + response_type: request!.response_type, + code_challenge: request!.code_challenge, + code_challenge_method: request!.code_challenge_method, + scope: request!.scope, + }, + }), + ), + }); + const asksWrite = canWrite(info.data?.scope); + const answer = useMutation({ + mutationFn: (approve: boolean) => + data( + Oauth.answer({ + client, + body: { ...request!, approve, grant: approve ? (asksWrite && write ? "read write" : "read") : undefined }, + }), + ), + onSuccess: (r) => { + if (safeToFollow(r.redirect_to)) leave.to(r.redirect_to); + else setStuck("This app’s address can’t be opened from a browser."); + }, + }); + + if (!request) + return ( + + + This page is opened by an app that asks for access to Lens. The link that brought you here is missing the app + or the address to return to. + + + + ); + if (info.isPending) + return ( + + + + + ); + if (info.isError) + return ( + + {info.error.message} +

+ Nothing was shared. If you expected this to work, go back to the app and try connecting again. +

+ +
+ ); + + const app = info.data.client; + const busy = answer.isPending || answer.isSuccess; + return ( + Give {app.name} access?} + description={ + <> + It will use Lens as you ({email}), with your roles: it sees + what you see, nothing more. + + } + footer={ + <> + You can take this back any time under API tokens → Apps with access. Afterwards you’re returned to{" "} + {returnsTo(info.data.redirect_uri)}. + + } + > + {info.data.granted && ( + You gave this app access before; allowing again replaces that. + )} +
    +
  • + Read + Browse, search and chat with the resources you can read. +
  • + {asksWrite && ( +
  • + + Make changes + Import, edit and reprocess, where your roles allow. + + +
  • + )} +
+ {app.uri &&

The app says it’s from {app.uri}

} + {(answer.isError || stuck) && {stuck ?? answer.error?.message}} +
+ + +
+
+ ); +} + +function BackHome() { + return ( + + Back to Lens + + ); +} diff --git a/nextjs-frontend/components/oauth/model.ts b/nextjs-frontend/components/oauth/model.ts new file mode 100644 index 000000000..bcbb669dd --- /dev/null +++ b/nextjs-frontend/components/oauth/model.ts @@ -0,0 +1,81 @@ +/** What an app asks for when it sends someone to /oauth/authorize (the OAuth authorization request). */ +export type ConsentRequest = { + client_id: string; + redirect_uri: string; + response_type: string; + code_challenge: string; + code_challenge_method: string; + scope?: string; + state?: string; + resource?: string; +}; + +type Params = Record; + +/** The request in the page's query, or null when it names no app or no address to return to. */ +export function consentRequest(params: Params): ConsentRequest | null { + const one = (k: string) => { + const v = params[k]; + return (Array.isArray(v) ? v[0] : v) || undefined; + }; + const client_id = one("client_id"); + const redirect_uri = one("redirect_uri"); + if (!client_id || !redirect_uri) return null; + return { + client_id, + redirect_uri, + response_type: one("response_type") ?? "code", + code_challenge: one("code_challenge") ?? "", + code_challenge_method: one("code_challenge_method") ?? "", + scope: one("scope"), + state: one("state"), + resource: one("resource"), + }; +} + +/** Schemes the browser would run or open itself: never followed, whatever the server said. */ +const UNSAFE = new Set([ + ...["javascript:", "data:", "vbscript:", "file:", "blob:", "about:", "view-source:", "intent:", "chrome:"], + ...["search-ms:", "smb:", "ssh:", "ftp:", "ldap:", "telnet:", "mailto:", "tel:", "sms:"], +]); +const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]); + +/** Whether the browser may be sent to an app's address: https, http on this machine, or the app's own scheme. */ +export function safeToFollow(uri: string): boolean { + let u: URL; + try { + u = new URL(uri); + } catch { + return false; + } + if (UNSAFE.has(u.protocol) || u.protocol.startsWith("ms-")) return false; + if (u.username || u.password || uri.includes("\\")) return false; + if (u.protocol === "http:") return LOOPBACK.has(u.hostname); + return true; +} + +/** Where an app takes people back to, as they'd recognise it: "app.example", "this computer", "the Cursor app". */ +export function returnsTo(uri: string): string { + try { + const u = new URL(uri); + if (u.protocol === "https:") return u.host; + if (u.protocol === "http:") return LOOPBACK.has(u.hostname) ? "an app on this computer" : u.host; + return `an app on this device (${u.protocol}//)`; + } catch { + return uri; + } +} + +export const canWrite = (scope: string | null | undefined) => (scope ?? "").split(" ").includes("write"); + +export const ACCESS_LABEL = (scope: string | null | undefined) => (canWrite(scope) ? "Read & write" : "Read only"); + +/** An app's web address as a host name, when it gave one. */ +export function appHost(uri: string | null | undefined): string | null { + if (!uri) return null; + try { + return new URL(uri).host; + } catch { + return null; + } +} diff --git a/nextjs-frontend/components/settings/bodies.tsx b/nextjs-frontend/components/settings/bodies.tsx index e9c461c93..d730ba670 100644 --- a/nextjs-frontend/components/settings/bodies.tsx +++ b/nextjs-frontend/components/settings/bodies.tsx @@ -293,6 +293,10 @@ export function SectionBody({ ctx }: { ctx: BodyCtx }) { +
+ + +

People make API keys on their API tokens page; a key acts as them, with their roles. These limits apply to new keys. diff --git a/nextjs-frontend/components/settings/model.ts b/nextjs-frontend/components/settings/model.ts index 004b2703f..6b61aaa2a 100644 --- a/nextjs-frontend/components/settings/model.ts +++ b/nextjs-frontend/components/settings/model.ts @@ -181,7 +181,7 @@ export const SECTIONS: SectionSpec[] = [ label: "API keys", backend: ["tokens"], description: - "How long the API keys people make for scripts and other apps last, and everyone’s keys, to revoke any of them.", + "How long the API keys people make for scripts last, how long apps they sign in to stay signed in, and everyone’s keys, to revoke any of them.", }, { id: "iiif", @@ -922,6 +922,24 @@ export const FIELDS: FieldSpec[] = [ max: 20, hint: "A failed send waits 30 seconds, then four times longer each time, up to 6 hours", }, + { + section: "tokens", + key: "oauth_access_minutes", + label: "An app’s access token lasts (minutes)", + kind: "int", + min: 5, + max: 1440, + hint: "Apps people sign in to with their Lens account renew it by themselves", + }, + { + section: "tokens", + key: "oauth_refresh_days", + label: "An app stays signed in for (days)", + kind: "int", + min: 1, + max: 3650, + hint: "Counted from when the app last renewed its access; at most as long as a key may last", + }, { section: "uploads", key: "max_mb", @@ -1206,6 +1224,9 @@ export function crossErrors(values: Record): Record md) e["tokens.default_days"] = "A new key can’t last longer than the most a key may last"; + const od = n("tokens.oauth_refresh_days"); + if (typeof od === "number" && typeof md === "number" && od > md) + e["tokens.oauth_refresh_days"] = "An app can’t stay signed in longer than the most a key may last"; const mn = n("diarize.min_speakers"); const mx = n("diarize.max_speakers"); if (typeof mn === "number" && typeof mx === "number" && mn > mx) diff --git a/nextjs-frontend/lib/api/backend-proxy.ts b/nextjs-frontend/lib/api/backend-proxy.ts index 5b4db5107..846de86d4 100644 --- a/nextjs-frontend/lib/api/backend-proxy.ts +++ b/nextjs-frontend/lib/api/backend-proxy.ts @@ -11,6 +11,24 @@ import { apiBaseUrl } from "@/lib/api/client"; */ const HOP = new Set(["connection", "keep-alive", "transfer-encoding", "te", "upgrade", "proxy-connection", "host"]); +/** Whether a reverse proxy in front of the web app sets X-Forwarded-Host and -Proto (TRUST_PROXY_HEADERS=true). */ +export function trustProxyHeaders(): boolean { + return ["1", "true", "yes"].includes((process.env.TRUST_PROXY_HEADERS || "").trim().toLowerCase()); +} + +/** + * The address the browser used, for links the API writes back to this origin (OAuth discovery, the embed player's + * own-site check). The API trusts these headers from the web app, so a browser's own X-Forwarded-* are passed on + * only when a reverse proxy in front is known to set them; otherwise the Host header (the URL Next hands over names + * the host it listens on) and the protocol Next was reached with. + */ +export function browserAddress(h: Headers, incoming: URL, trustProxy: boolean): { host: string; proto: string } { + const first = (v: string | null) => (v ?? "").split(",")[0].trim(); + const host = (trustProxy && first(h.get("x-forwarded-host"))) || h.get("host") || incoming.host; + const proto = (trustProxy && first(h.get("x-forwarded-proto"))) || incoming.protocol.replace(":", ""); + return { host, proto }; +} + async function proxy(req: Request): Promise { const incoming = new URL(req.url); const target = new URL(incoming.pathname + incoming.search, apiBaseUrl()); @@ -18,8 +36,9 @@ async function proxy(req: Request): Promise { req.headers.forEach((v, k) => { if (!HOP.has(k)) headers.set(k, v); }); - headers.set("x-forwarded-host", incoming.host); - headers.set("x-forwarded-proto", incoming.protocol.replace(":", "")); + const { host, proto } = browserAddress(req.headers, incoming, trustProxyHeaders()); + headers.set("x-forwarded-host", host); + headers.set("x-forwarded-proto", proto); // Ask for identity so byte ranges and lengths stay exact. headers.set("accept-encoding", "identity"); diff --git a/nextjs-frontend/next.config.mjs b/nextjs-frontend/next.config.mjs index 8dc7dbc82..766ab0f80 100644 --- a/nextjs-frontend/next.config.mjs +++ b/nextjs-frontend/next.config.mjs @@ -4,6 +4,18 @@ const nextConfig = { distDir: process.env.NEXT_DIST_DIR || ".next", // The dev server would otherwise write an AGENTS.md and a CLAUDE.md into this folder (since Next 16.3). agentRules: false, + // The OAuth consent page may not be framed: a page that framed it could trick people into clicking Allow. + async headers() { + return [ + { + source: "/oauth/:path*", + headers: [ + { key: "Content-Security-Policy", value: "frame-ancestors 'none'" }, + { key: "X-Frame-Options", value: "DENY" }, + ], + }, + ]; + }, }; export default nextConfig; diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index 66690a7c1..0660efe19 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -509,6 +509,351 @@ } } }, + "/api/v1/oauth/register": { + "post": { + "tags": [ + "oauth" + ], + "summary": "Register", + "description": "An app registers itself (RFC 7591), without signing in: it gets a `client_id`, and a `client_secret` if it\nasked for one. It can do nothing until someone gives it access. Audited as `oauth.client.register`.", + "operationId": "register", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientRegistration" + } + } + }, + "required": true + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClientRegistered" + } + } + } + }, + "400": { + "description": "OAuth error" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/oauth/authorize": { + "get": { + "tags": [ + "oauth" + ], + "summary": "Consent", + "description": "What the consent page shows for an app's request: the app, where it takes you back to and what it asks for.\n400 when the request can't be answered (an unknown app, an address it didn't register, no PKCE challenge).", + "operationId": "consent", + "parameters": [ + { + "name": "client_id", + "in": "query", + "required": true, + "schema": { + "type": "string", + "title": "Client Id" + } + }, + { + "name": "redirect_uri", + "in": "query", + "required": true, + "schema": { + "type": "string", + "title": "Redirect Uri" + } + }, + { + "name": "code_challenge", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "", + "title": "Code Challenge" + } + }, + { + "name": "code_challenge_method", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "", + "title": "Code Challenge Method" + } + }, + { + "name": "response_type", + "in": "query", + "required": false, + "schema": { + "type": "string", + "default": "code", + "title": "Response Type" + } + }, + { + "name": "scope", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Scope" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Consent" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "post": { + "tags": [ + "oauth" + ], + "summary": "Answer", + "description": "Your answer to an app's request. Yes gives it a one-time code (five minutes) at its redirect address, which\nit swaps for tokens that act as you, with your roles; no sends it `error=access_denied`. Audited as\n`oauth.grant`.", + "operationId": "answer", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConsentAnswer" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConsentResult" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/oauth/token": { + "post": { + "tags": [ + "oauth" + ], + "summary": "Token", + "description": "The app swaps its code (`grant_type=authorization_code`, with `code_verifier` and the same `redirect_uri`)\nor its refresh token (`grant_type=refresh_token`) for an access token and a new refresh token. Form-encoded, as\nOAuth has it; errors are `{error, error_description}`.", + "operationId": "token", + "requestBody": { + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/Body_oauth-token" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/OAuthTokens" + } + } + } + }, + "400": { + "description": "OAuth error" + }, + "401": { + "description": "OAuth error" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/oauth/revoke": { + "post": { + "tags": [ + "oauth" + ], + "summary": "Revoke", + "description": "An app hands back a token, access or refresh (RFC 7009): the access it was given ends. Answers the same\nwhether or not the token was known. Audited as `oauth.revoke`.", + "operationId": "revoke", + "requestBody": { + "content": { + "application/x-www-form-urlencoded": { + "schema": { + "$ref": "#/components/schemas/Body_oauth-revoke" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "401": { + "description": "OAuth error" + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/oauth/grants": { + "get": { + "tags": [ + "oauth" + ], + "summary": "List Grants", + "description": "The apps you gave access to, the latest first.", + "operationId": "list_grants", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "items": { + "$ref": "#/components/schemas/OAuthGrant" + }, + "type": "array", + "title": "Response Oauth-List Grants" + } + } + } + } + } + } + }, + "/api/v1/oauth/grants/{grant_id}": { + "delete": { + "tags": [ + "oauth" + ], + "summary": "Revoke Grant", + "description": "Take an app's access away: its tokens stop working now. Audited as `oauth.revoke`.", + "operationId": "revoke_grant", + "parameters": [ + { + "name": "grant_id", + "in": "path", + "required": true, + "schema": { + "type": "integer", + "title": "Grant Id" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Ok" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, "/api/v1/users": { "get": { "tags": [ @@ -15611,6 +15956,120 @@ ], "title": "BatchSummary" }, + "Body_oauth-revoke": { + "properties": { + "token": { + "type": "string", + "title": "Token" + }, + "client_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Client Id" + }, + "client_secret": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Client Secret" + } + }, + "type": "object", + "required": [ + "token" + ], + "title": "Body_oauth-revoke" + }, + "Body_oauth-token": { + "properties": { + "grant_type": { + "type": "string", + "title": "Grant Type" + }, + "code": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Code" + }, + "redirect_uri": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Redirect Uri" + }, + "code_verifier": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Code Verifier" + }, + "refresh_token": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Refresh Token" + }, + "client_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Client Id" + }, + "client_secret": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Client Secret" + } + }, + "type": "object", + "required": [ + "grant_type" + ], + "title": "Body_oauth-token" + }, "BrowseEntry": { "properties": { "path": { @@ -16126,25 +16585,201 @@ "title": { "anyOf": [ { - "type": "string" + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Title" + }, + "scope": { + "anyOf": [ + { + "$ref": "#/components/schemas/ChatScope" + }, + { + "type": "null" + } + ] + }, + "model": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Model", + "description": "the model that answers in it (one of GET /chats/capabilities `models`); null: the configured one" + } + }, + "additionalProperties": false, + "type": "object", + "title": "ChatUpdate" + }, + "ClientRegistered": { + "properties": { + "client_id": { + "type": "string", + "title": "Client Id" + }, + "client_secret": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Client Secret", + "description": "only for apps that asked for one; shown once" + }, + "client_id_issued_at": { + "type": "integer", + "title": "Client Id Issued At" + }, + "client_secret_expires_at": { + "type": "integer", + "title": "Client Secret Expires At", + "description": "0: it doesn't expire", + "default": 0 + }, + "client_name": { + "type": "string", + "title": "Client Name" + }, + "client_uri": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Client Uri" + }, + "redirect_uris": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Redirect Uris" + }, + "token_endpoint_auth_method": { + "type": "string", + "title": "Token Endpoint Auth Method" + }, + "grant_types": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Grant Types", + "default": [ + "authorization_code", + "refresh_token" + ] + }, + "response_types": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Response Types", + "default": [ + "code" + ] + }, + "scope": { + "type": "string", + "title": "Scope", + "default": "read write" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "client_id", + "client_id_issued_at", + "client_name", + "redirect_uris", + "token_endpoint_auth_method" + ], + "title": "ClientRegistered" + }, + "ClientRegistration": { + "properties": { + "redirect_uris": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Redirect Uris", + "description": "https, http://localhost (any port), or the app's own scheme; 1 to 10" + }, + "client_name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Client Name", + "description": "shown on the consent page and in the list of apps with access" + }, + "client_uri": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Client Uri" + }, + "token_endpoint_auth_method": { + "type": "string", + "title": "Token Endpoint Auth Method", + "description": "none (public apps), client_secret_post or client_secret_basic", + "default": "none" + }, + "grant_types": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" }, { "type": "null" } ], - "title": "Title" + "title": "Grant Types" }, - "scope": { + "response_types": { "anyOf": [ { - "$ref": "#/components/schemas/ChatScope" + "items": { + "type": "string" + }, + "type": "array" }, { "type": "null" } - ] + ], + "title": "Response Types" }, - "model": { + "scope": { "anyOf": [ { "type": "string" @@ -16153,13 +16788,15 @@ "type": "null" } ], - "title": "Model", - "description": "the model that answers in it (one of GET /chats/capabilities `models`); null: the configured one" + "title": "Scope" } }, - "additionalProperties": false, "type": "object", - "title": "ChatUpdate" + "required": [ + "redirect_uris" + ], + "title": "ClientRegistration", + "description": "Dynamic client registration (RFC 7591). Metadata Lens has no use for is ignored, as the RFC asks." }, "Collection": { "properties": { @@ -17196,6 +17833,186 @@ "type": "object", "title": "CommentUpdate" }, + "Consent": { + "properties": { + "client": { + "$ref": "#/components/schemas/ConsentClient" + }, + "redirect_uri": { + "type": "string", + "title": "Redirect Uri" + }, + "scope": { + "type": "string", + "enum": [ + "read", + "read write" + ], + "title": "Scope", + "description": "what the app asks for: read, or read and write" + }, + "granted": { + "anyOf": [ + { + "type": "string", + "enum": [ + "read", + "read write" + ] + }, + { + "type": "null" + } + ], + "title": "Granted", + "description": "what you gave this app before, if anything" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "client", + "redirect_uri", + "scope" + ], + "title": "Consent", + "description": "What the consent page shows." + }, + "ConsentAnswer": { + "properties": { + "client_id": { + "type": "string", + "title": "Client Id" + }, + "redirect_uri": { + "type": "string", + "title": "Redirect Uri" + }, + "response_type": { + "type": "string", + "title": "Response Type", + "default": "code" + }, + "code_challenge": { + "type": "string", + "title": "Code Challenge" + }, + "code_challenge_method": { + "type": "string", + "title": "Code Challenge Method", + "default": "S256" + }, + "scope": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Scope" + }, + "state": { + "anyOf": [ + { + "type": "string", + "maxLength": 2000 + }, + { + "type": "null" + } + ], + "title": "State" + }, + "resource": { + "anyOf": [ + { + "type": "string", + "maxLength": 500 + }, + { + "type": "null" + } + ], + "title": "Resource" + }, + "approve": { + "type": "boolean", + "title": "Approve" + }, + "grant": { + "anyOf": [ + { + "type": "string", + "enum": [ + "read", + "read write" + ] + }, + { + "type": "null" + } + ], + "title": "Grant", + "description": "give less than was asked for (read); default: what was asked for" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "client_id", + "redirect_uri", + "code_challenge", + "approve" + ], + "title": "ConsentAnswer" + }, + "ConsentClient": { + "properties": { + "id": { + "type": "string", + "title": "Id" + }, + "name": { + "type": "string", + "title": "Name" + }, + "uri": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Uri" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "name" + ], + "title": "ConsentClient" + }, + "ConsentResult": { + "properties": { + "redirect_to": { + "type": "string", + "title": "Redirect To", + "description": "send the browser here: the app's address with its code, or with error=access_denied" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "redirect_to" + ], + "title": "ConsentResult" + }, "ContentRules": { "properties": { "extensions": { @@ -20925,7 +21742,8 @@ "type": "string", "enum": [ "access", - "token" + "token", + "oauth" ], "title": "Via" }, @@ -22687,6 +23505,119 @@ ], "title": "NotifyTestResult" }, + "OAuthGrant": { + "properties": { + "id": { + "type": "integer", + "title": "Id" + }, + "client": { + "type": "string", + "title": "Client" + }, + "name": { + "type": "string", + "title": "Name" + }, + "uri": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Uri" + }, + "scope": { + "type": "string", + "enum": [ + "read", + "read write" + ], + "title": "Scope" + }, + "created_at": { + "type": "string", + "title": "Created At" + }, + "last_used_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Last Used At" + }, + "expires_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Expires At", + "description": "when its access ends unless the app renews it before" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "id", + "client", + "name", + "scope", + "created_at" + ], + "title": "OAuthGrant", + "description": "An app you gave access to." + }, + "OAuthTokens": { + "properties": { + "access_token": { + "type": "string", + "title": "Access Token" + }, + "token_type": { + "type": "string", + "const": "Bearer", + "title": "Token Type", + "default": "Bearer" + }, + "expires_in": { + "type": "integer", + "title": "Expires In", + "description": "seconds until the access token expires" + }, + "refresh_token": { + "type": "string", + "title": "Refresh Token" + }, + "scope": { + "type": "string", + "enum": [ + "read", + "read write" + ], + "title": "Scope" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "access_token", + "expires_in", + "refresh_token", + "scope" + ], + "title": "OAuthTokens" + }, "ObjectCount": { "properties": { "object": { diff --git a/nextjs-frontend/proxy.ts b/nextjs-frontend/proxy.ts index 7788d928f..ee79deecb 100644 --- a/nextjs-frontend/proxy.ts +++ b/nextjs-frontend/proxy.ts @@ -31,10 +31,11 @@ export default auth((req) => { }); export const config = { - // Skip Auth.js, the backend paths (proxied by route handlers, see lib/api/backend-proxy.ts), Next's files and assets. + // Skip Auth.js, the backend paths (proxied by route handlers, see lib/api/backend-proxy.ts; /.well-known is OAuth + // discovery), Next's files and assets. // Under /iiif only the backend's IIIF resources are skipped (collection, discovery, auth, /iiif//…); the app's own // IIIF pages (/iiif, /iiif/collections/…, /iiif/import, /iiif/metadata/…) need the session like any other page. matcher: [ - "/((?!api/|_next/|embed/|s/|iiif/(?:collection(?!s)|discovery|auth|\\d)|reports/|static/|fonts/|favicon\\.ico|icon\\.svg|robots\\.txt).*)", + "/((?!api/|\\.well-known/|_next/|embed/|s/|iiif/(?:collection(?!s)|discovery|auth|\\d)|reports/|static/|fonts/|favicon\\.ico|icon\\.svg|robots\\.txt).*)", ], };