From d6ce41f825671c5619826559f858918d9c797c86 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 22:16:33 +1000 Subject: [PATCH 1/2] OAuth sign-in for API and MCP clients Lens is an OAuth 2.1 authorization server: apps register themselves (RFC 7591), send people to the consent page with a PKCE challenge (S256, required) and swap the code for tokens that act as the person, with their roles, read only or read and write. Discovery is at /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource, on the web app's address too. Tokens are random and kept as hashes; refresh tokens rotate, and one that comes back after it was swapped ends the access. People see the apps they allowed under API tokens and revoke them there. API: /api/v1/oauth/register, authorize (GET and POST), token, revoke, grants; tables oauth_client, oauth_code, oauth_grant, oauth_token; the bearer path takes lo_ tokens; settings tokens.oauth_access_minutes and tokens.oauth_refresh_days; audited as oauth.client.register, oauth.grant and oauth.revoke. An admin's app has the admin's roles in every namespace but not the administration. After a security review: redirect addresses with a user name or a backslash are refused (a loopback match could otherwise be steered to another host), as are the browser's and the system's own schemes; discovery names the web app's address only as a trusted proxy reports it, else FRONTEND_URL; tokens of a revoked grant are dead even if minted during the revoke. Web app: /oauth/authorize (consent, signing in first), Apps with access on the API tokens page, the two lifetimes in Settings, and the proxy passes the browser's Host on. Checked in the browser as a viewer and an admin, in dark mode and at 390 px. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012zJqF1Ht8p2VjBi4j11jfg --- CHANGELOG.md | 31 + docs/api.md | 41 +- docs/authentication.md | 61 +- docs/configuration.md | 7 +- fastapi_backend/app/api/deps.py | 27 +- fastapi_backend/app/api/v1/router.py | 2 + fastapi_backend/app/api/v1/routes/oauth.py | 275 +++++ fastapi_backend/app/domain/auth.py | 6 + fastapi_backend/app/domain/oauth.py | 356 +++++++ fastapi_backend/app/domain/settings.py | 8 + fastapi_backend/app/domain/store.py | 13 +- fastapi_backend/app/main.py | 2 + fastapi_backend/app/schemas/auth.py | 2 +- fastapi_backend/app/schemas/oauth.py | 92 ++ fastapi_backend/tests/api/test_oauth.py | 411 ++++++++ nextjs-frontend/__tests__/oauth-model.test.ts | 78 ++ nextjs-frontend/__tests__/oauth-ui.test.tsx | 178 ++++ .../app/(app)/account/tokens/page.tsx | 10 +- .../app/.well-known/[...path]/route.ts | 6 + nextjs-frontend/app/oauth/authorize/page.tsx | 41 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 126 ++- .../app/openapi-client/types.gen.ts | 552 +++++++++- nextjs-frontend/components/account/apps.tsx | 147 +++ nextjs-frontend/components/oauth/consent.tsx | 147 +++ nextjs-frontend/components/oauth/model.ts | 81 ++ .../components/settings/bodies.tsx | 4 + nextjs-frontend/components/settings/model.ts | 23 +- nextjs-frontend/lib/api/backend-proxy.ts | 6 +- nextjs-frontend/openapi.json | 953 +++++++++++++++++- nextjs-frontend/proxy.ts | 5 +- 30 files changed, 3655 insertions(+), 36 deletions(-) create mode 100644 fastapi_backend/app/api/v1/routes/oauth.py create mode 100644 fastapi_backend/app/domain/oauth.py create mode 100644 fastapi_backend/app/schemas/oauth.py create mode 100644 fastapi_backend/tests/api/test_oauth.py create mode 100644 nextjs-frontend/__tests__/oauth-model.test.ts create mode 100644 nextjs-frontend/__tests__/oauth-ui.test.tsx create mode 100644 nextjs-frontend/app/.well-known/[...path]/route.ts create mode 100644 nextjs-frontend/app/oauth/authorize/page.tsx create mode 100644 nextjs-frontend/components/account/apps.tsx create mode 100644 nextjs-frontend/components/oauth/consent.tsx create mode 100644 nextjs-frontend/components/oauth/model.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index ddf835383..20563489b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,37 @@ 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. + - 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. - **Fix (security): only the server's own media links are signed.** Text shaped like a media link (`/api/v1/recordings/12/audio`) came back signed: titles and transcript lines in API responses, and anything in the embed and report pages, including the transcript data inside them. Someone who could rename a recording or correct diff --git a/docs/api.md b/docs/api.md index 346ca91a2..da276eff0 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 d61c1f535..1c45c7ad2 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -34,7 +34,7 @@ Sign out ──► POST /api/v1/auth/logout (ends the session on the API too) | `GET /api/v1/auth/status` | `{setup_required}`: the sign-in page shows the setup form when true | | `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 | @@ -53,6 +53,63 @@ 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. +* **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 accepted + (two requests at once); 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. 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`. 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 @@ -73,5 +130,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 a964c4d9a..0d17bf2c4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -27,7 +27,7 @@ with AES-GCM and are write-only: the API reports whether one is set, never its v | `ARCHIVE_ALLOWED_HOSTS` | | break-glass override of allowed Host headers if a bad setting locks everyone out | | `RUN_BACKGROUND` | follows `workers.inline` | run job workers and folder watching inside the API process | | `LENS_SETUP_CODE` | random | fix the first-run setup code (automation) | -| `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 | @@ -201,8 +201,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 ae7beba5a..be5bb3bd2 100644 --- a/fastapi_backend/app/api/v1/router.py +++ b/fastapi_backend/app/api/v1/router.py @@ -19,6 +19,7 @@ metadata, namespaces, notes, + oauth, pipelines, public, recordings, @@ -37,6 +38,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..9dcc654f7 --- /dev/null +++ b/fastapi_backend/app/api/v1/routes/oauth.py @@ -0,0 +1,275 @@ +"""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.responses import JSONResponse + +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 + + +@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..b965f31d8 --- /dev/null +++ b/fastapi_backend/app/domain/oauth.py @@ -0,0 +1,356 @@ +"""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 +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( + "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 + row = (db.rows("DELETE $r RETURN BEFORE", r=R("oauth_code", auth.sha(code))) or [None])[0] if code else None + 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"], + 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") and (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") + 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 83a87ee15..cb49cbf0b 100644 --- a/fastapi_backend/app/domain/settings.py +++ b/fastapi_backend/app/domain/settings.py @@ -82,6 +82,7 @@ "convert_seconds": (10, 3600), } TOKEN_DAYS = (1, 3650) +OAUTH_ACCESS_MINUTES = (5, 1440) VIEWER_URL = re.compile(r"^https?://[^\s]+$") _KEYS, _KL = {}, threading.Lock() @@ -242,6 +243,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): @@ -311,6 +317,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 23f730a45..d7b6b0e25 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}, @@ -575,6 +576,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..1744cf5bc 100644 --- a/fastapi_backend/app/main.py +++ b/fastapi_backend/app/main.py @@ -18,6 +18,7 @@ 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 well_known as oauth_well_known from app.config import settings from app.core import middleware from app.core.runtime import Archive @@ -77,6 +78,7 @@ 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.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 e518d501a..7e638a7e8 100644 --- a/fastapi_backend/app/schemas/auth.py +++ b/fastapi_backend/app/schemas/auth.py @@ -51,7 +51,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..bf4a09f00 --- /dev/null +++ b/fastapi_backend/tests/api/test_oauth.py @@ -0,0 +1,411 @@ +"""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 still works + assert renew(first["refresh_token"]).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) + assert _tokens(client, app, code, verifier).status_code == 200 + assert err(_tokens(client, app, code, verifier)) == (400, "invalid_grant") # once + # 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") + + +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/__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 7118e928c..8b063316a 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, @@ -930,6 +950,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 460fa2c7e..d67add3ec 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -812,6 +812,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 */ @@ -1130,6 +1182,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 */ @@ -1754,6 +1908,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; +}; + /** * ContentState */ @@ -3792,7 +4047,7 @@ export type Me = { /** * Via */ - via: "access" | "token"; + via: "access" | "token" | "oauth"; /** * Scope */ @@ -3806,6 +4061,7 @@ export type Me = { | Array | "access" | "token" + | "oauth" | "read" | "write" | undefined; @@ -4529,6 +4785,87 @@ export type NoteUpdate = { shared?: boolean | null; }; +/** + * 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 */ @@ -10080,6 +10417,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 0a531160c..9c180fddb 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 ca32c2562..5398a1cb8 100644 --- a/nextjs-frontend/components/settings/model.ts +++ b/nextjs-frontend/components/settings/model.ts @@ -173,7 +173,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", @@ -871,6 +871,24 @@ export const FIELDS: FieldSpec[] = [ kind: "switch", hint: "Off: every key expires. Keys made before a change keep their expiry; revoke them below.", }, + { + 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", @@ -1155,6 +1173,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..0a805254c 100644 --- a/nextjs-frontend/lib/api/backend-proxy.ts +++ b/nextjs-frontend/lib/api/backend-proxy.ts @@ -18,8 +18,10 @@ 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(":", "")); + // The address the browser used, for links the API writes back to this origin (OAuth discovery): what a reverse + // proxy in front reports, else the Host header (the URL Next hands over names the host it listens on). + headers.set("x-forwarded-host", req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? incoming.host); + headers.set("x-forwarded-proto", req.headers.get("x-forwarded-proto") ?? incoming.protocol.replace(":", "")); // Ask for identity so byte ranges and lengths stay exact. headers.set("accept-encoding", "identity"); diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index ef168c22e..bd1008f85 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": [ @@ -13861,6 +14206,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": { @@ -14352,25 +14811,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" @@ -14379,13 +15014,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": { @@ -15422,6 +16059,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" + }, "ContentState": { "properties": { "content_state": { @@ -18590,7 +19407,8 @@ "type": "string", "enum": [ "access", - "token" + "token", + "oauth" ], "title": "Via" }, @@ -19724,6 +20542,119 @@ "type": "object", "title": "NoteUpdate" }, + "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).*)", ], }; From bc57ea2f6dcf4de28facca5eb71b7cb58b392e4c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 12:57:44 +0000 Subject: [PATCH 2/2] OAuth: review fixes for codes, refresh reuse, forwarded hosts and framing A code that comes back after it was swapped ends the access it gave, and a rotated refresh token that comes back within the grace minute is refused instead of minting another pair. Expired codes are swept when a new one is made. A 401 that asks for a bearer token names the protected resource metadata (RFC 9728), as MCP clients expect. 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; otherwise it reports Host. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01HFiySoDnqG9PX5c3WLPz5C --- CHANGELOG.md | 5 +++ docs/authentication.md | 16 ++++--- docs/configuration.md | 1 + fastapi_backend/app/api/v1/routes/oauth.py | 14 +++++- fastapi_backend/app/domain/oauth.py | 25 ++++++++--- fastapi_backend/app/main.py | 3 ++ fastapi_backend/tests/api/test_oauth.py | 24 +++++++++-- nextjs-frontend/.env.example | 3 ++ .../__tests__/backend-proxy.test.ts | 43 +++++++++++++++++++ nextjs-frontend/lib/api/backend-proxy.ts | 25 +++++++++-- nextjs-frontend/next.config.mjs | 12 ++++++ 11 files changed, 151 insertions(+), 20 deletions(-) create mode 100644 nextjs-frontend/__tests__/backend-proxy.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 20563489b..1c138b6e5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -56,6 +56,11 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version 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 diff --git a/docs/authentication.md b/docs/authentication.md index 1c45c7ad2..355f3c658 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -77,7 +77,8 @@ app ──► POST /api/v1/oauth/token grant_type=refresh_token before th 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. + 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. @@ -88,18 +89,21 @@ app ──► POST /api/v1/oauth/token grant_type=refresh_token before th * **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 accepted - (two requests at once); after that it ends the access, because it was probably copied. Only hashes of tokens, - codes and app secrets are kept. +* **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. The addresses in them are the web app's when the request came +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`. Set `FRONTEND_URL` to the address people +([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 | | diff --git a/docs/configuration.md b/docs/configuration.md index 0d17bf2c4..ac83165af 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -40,6 +40,7 @@ with AES-GCM and are write-only: the API reports whether one is set, never its v | `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 diff --git a/fastapi_backend/app/api/v1/routes/oauth.py b/fastapi_backend/app/api/v1/routes/oauth.py index 9dcc654f7..a1d8bea5a 100644 --- a/fastapi_backend/app/api/v1/routes/oauth.py +++ b/fastapi_backend/app/api/v1/routes/oauth.py @@ -17,7 +17,9 @@ from typing import Annotated, Any from fastapi import APIRouter, Form, HTTPException, Query, Request -from fastapi.responses import JSONResponse +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 @@ -98,6 +100,16 @@ def _client_credentials(request: Request, client_id: str | None, client_secret: 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: diff --git a/fastapi_backend/app/domain/oauth.py b/fastapi_backend/app/domain/oauth.py index b965f31d8..68ceb0870 100644 --- a/fastapi_backend/app/domain/oauth.py +++ b/fastapi_backend/app/domain/oauth.py @@ -22,6 +22,7 @@ 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") @@ -205,6 +206,7 @@ def approve(db, uid, info, code_challenge, granted_scope=None, resource=None): 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)), @@ -255,7 +257,14 @@ def exchange_code(db, cfg, client_id, client_secret, code, redirect_uri, verifie 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 - row = (db.rows("DELETE $r RETURN BEFORE", r=R("oauth_code", auth.sha(code))) or [None])[0] if code else None + 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: @@ -268,7 +277,9 @@ def exchange_code(db, cfg, client_id, client_secret, code, redirect_uri, verifie drop_grant(db, old) gid = db.next_id("oauth_grant") db.run( - ["CREATE $g CONTENT $d", "UPDATE $c SET used = true"], + ["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"], @@ -291,9 +302,13 @@ def refresh(db, cfg, client_id, client_secret, raw): 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") and (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") + 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() diff --git a/fastapi_backend/app/main.py b/fastapi_backend/app/main.py index 1744cf5bc..6f7343a44 100644 --- a/fastapi_backend/app/main.py +++ b/fastapi_backend/app/main.py @@ -14,10 +14,12 @@ 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 @@ -79,6 +81,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]: 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/tests/api/test_oauth.py b/fastapi_backend/tests/api/test_oauth.py index bf4a09f00..a4f3d1579 100644 --- a/fastapi_backend/tests/api/test_oauth.py +++ b/fastapi_backend/tests/api/test_oauth.py @@ -97,6 +97,11 @@ def test_discovery_says_where_everything_is(client, app): far = TestClient(app, base_url="http://127.0.0.1", client=("203.0.113.9", 50000)) meta = far.get("/.well-known/oauth-authorization-server", headers={"x-forwarded-host": "evil.example"}).json() assert meta["issuer"] == "http://localhost:3000" and meta["token_endpoint"] == "http://localhost:3000/api/v1/oauth/token" + # a request without a token is told where to find out how to get one (RFC 9728), on the address it used + r = web.get("/api/v1/auth/me", headers=via) + assert r.status_code == 401 + assert r.headers["www-authenticate"] == 'Bearer resource_metadata="https://lens.example.org/.well-known/oauth-protected-resource"' + assert r.json() == {"detail": "sign in first"} def test_an_app_gets_access_and_acts_with_the_persons_roles(client, db, cfg, folder): @@ -198,8 +203,9 @@ def test_refresh_tokens_rotate_and_a_copied_one_ends_the_grant(client, db): 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 still works - assert renew(first["refresh_token"]).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( @@ -276,12 +282,22 @@ def test_codes_work_once_with_the_right_verifier(client, db): # 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) - assert _tokens(client, app, code, verifier).status_code == 200 - assert err(_tokens(client, app, code, verifier)) == (400, "invalid_grant") # once + 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): 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/lib/api/backend-proxy.ts b/nextjs-frontend/lib/api/backend-proxy.ts index 0a805254c..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,10 +36,9 @@ async function proxy(req: Request): Promise { req.headers.forEach((v, k) => { if (!HOP.has(k)) headers.set(k, v); }); - // The address the browser used, for links the API writes back to this origin (OAuth discovery): what a reverse - // proxy in front reports, else the Host header (the URL Next hands over names the host it listens on). - headers.set("x-forwarded-host", req.headers.get("x-forwarded-host") ?? req.headers.get("host") ?? incoming.host); - headers.set("x-forwarded-proto", req.headers.get("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 25a2eb9b8..7121a5783 100644 --- a/nextjs-frontend/next.config.mjs +++ b/nextjs-frontend/next.config.mjs @@ -2,6 +2,18 @@ const nextConfig = { // Separate build folders let several dev servers run side by side (NEXT_DIST_DIR=.next-a next dev -p 3021). distDir: process.env.NEXT_DIST_DIR || ".next", + // 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;