From caf5ad3816c8aac8344c9e2bd4a3cc878a8db057 Mon Sep 17 00:00:00 2001 From: fstwn Date: Tue, 20 Oct 2026 14:19:01 +0200 Subject: [PATCH 01/11] feat(auth): access tokens with scopes, expiry, renew and revoke (8.167); docs: Claude connects through OAuth (8.168) --- .zenodo.json | 2 +- CHANGELOG.md | 18 +- README.md | 37 ++ docs/adr/DESIGN_DECISIONS.md | 2 + docs/adr/IMPLEMENTATION_PLAN_0.6.md | 2 +- src/backend/apps/catalog/access_tokens.py | 90 ++++ src/backend/apps/catalog/api/__init__.py | 2 + src/backend/apps/catalog/api/access_tokens.py | 421 +++++++++++++++ src/backend/apps/catalog/api/auth.py | 4 + src/backend/apps/catalog/client_header.py | 9 +- src/backend/apps/catalog/documents.py | 19 +- src/backend/dev.env.example | 2 + src/backend/main_fastapi.py | 5 + src/backend/settings.py | 20 + src/frontend/app/admin/access-tokens/page.tsx | 83 +++ src/frontend/app/settings/page.tsx | 2 + .../components/settings/AccessTokenTable.tsx | 88 ++++ .../settings/AccessTokensSection.tsx | 194 +++++++ .../components/settings/NewTokenNotice.tsx | 45 ++ src/frontend/lib/accessTokens.test.ts | 125 +++++ src/frontend/lib/accessTokens.ts | 74 +++ src/frontend/lib/adminAccess.test.ts | 1 + src/frontend/lib/navigation.test.ts | 6 +- src/frontend/lib/navigation.ts | 2 + tests/api/test_access_tokens.py | 487 ++++++++++++++++++ tests/catalog/test_client_header.py | 15 + uberspaceconfig/deployment/README.md | 3 + .../etc/services.d/fastapi.ini.example | 1 + 28 files changed, 1750 insertions(+), 9 deletions(-) create mode 100644 src/backend/apps/catalog/access_tokens.py create mode 100644 src/backend/apps/catalog/api/access_tokens.py create mode 100644 src/frontend/app/admin/access-tokens/page.tsx create mode 100644 src/frontend/components/settings/AccessTokenTable.tsx create mode 100644 src/frontend/components/settings/AccessTokensSection.tsx create mode 100644 src/frontend/components/settings/NewTokenNotice.tsx create mode 100644 src/frontend/lib/accessTokens.test.ts create mode 100644 src/frontend/lib/accessTokens.ts create mode 100644 tests/api/test_access_tokens.py diff --git a/.zenodo.json b/.zenodo.json index d81d47bd..a04135d9 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -2,7 +2,7 @@ "title": "Catalog of Second Chances (CSC) - Digital Database and Corresponding Interfaces for ReUse of Architectural Components (v0.6.2.1)", "version": "0.6.2.1", "upload_type": "software", - "description": "

The Catalog of Second Chances (CSC) is a prototypical digital component database. It catalogs digital representations of uniquely identifiable architectural components for reuse. Furthermore, it provides corresponding interfaces and tools to leverage them via a backend REST-API, a web-frontend as well as a interface for direct interaction within Rhino Grasshopper.

Changes in v0.6.2.1 (unreleased)

Changed

Server notes

Full history: CHANGELOG.md

", + "description": "

The Catalog of Second Chances (CSC) is a prototypical digital component database. It catalogs digital representations of uniquely identifiable architectural components for reuse. Furthermore, it provides corresponding interfaces and tools to leverage them via a backend REST-API, a web-frontend as well as a interface for direct interaction within Rhino Grasshopper.

Changes in v0.6.2.1 (2026-10-20)

Changed

Server notes

Full history: CHANGELOG.md

", "creators": [ { "name": "Eschenbach, Max Benjamin", diff --git a/CHANGELOG.md b/CHANGELOG.md index 06f74a97..307f945a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,23 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [0.6.2.1] - unreleased +## [0.6.3.0] - unreleased + +### Added + +- **Access tokens** (decision 8.167): admins create personal access tokens in Settings (30 days, + 90 days or one year; shown once, stored only as a hash, at most 10 active), renew and revoke + them; admins see and revoke every token on a new admin page. A token reads the catalog only + where its scope allows; `GET /auth/token-check` tests one. The ground for the MCP layer and the + Grasshopper device sign-in of this release. + +### Server notes + +- `CSC_PAT_ROLES` (optional, default `admin`) names the roles that may create access tokens. +- The new collection `access_tokens` needs the same database rights as the others; its indexes + are created at the start. + +## [0.6.2.1] - 2026-10-20 ### Changed diff --git a/README.md b/README.md index c3e209cb..28d45f1a 100644 --- a/README.md +++ b/README.md @@ -430,6 +430,43 @@ browser wrote itself stands on the left of that chain and is never believed. share a limit (the Uberspace manual does not state which headers its proxy sets or from which address it connects). +## Access tokens + +A personal access token lets a tool other than the web app (for instance an AI +assistant through the MCP layer) read the catalog as its owner, and nothing +more. It is not the JWT of a sign-in: a token only works where its scope says, +and a JWT does not work in place of it. + +- **Who.** Administrators at first. `CSC_PAT_ROLES` (default `admin`, a comma + list of the global roles `admin` and `user`) opens it to more; the role is + checked again on every request, so an account that loses it stops working at + once. Everyone sees and revokes the tokens they hold in Settings, "Access + tokens"; administrators see every token under Admin, "Access tokens", and can + revoke any. +- **Create.** Settings, "Access tokens": a name and a lifetime of 30 days, 90 + days (the default) or 1 year; there is no token without an expiry. The token + (`csc_pat_` and 43 characters) is shown once, with a copy button; copy it + then. The list shows only its first 8 characters, name, scope, created, last + used and expiry. At most 10 active tokens per account. +- **Renew.** Within 14 days of the expiry (and after it) the list offers + "Renew": a new token with the same name is made and shown once, the old one + is revoked. +- **Revoke.** "Revoke" in the list stops the token at once. Revoked and expired + tokens, a lost role, an unverified, disabled or deleted account all stop it + at once: the database is asked on every request, nothing is cached. +- **Try a token.** `curl -H "Authorization: Bearer csc_pat_..." + https:///auth/token-check` answers the owner, the scope and the + expiry; every other answer is the same 401, whatever the reason. This path + and `/mcp` need no `X-CSC-Client` header (the connectors of Claude cannot + send one); every other route still does. +- **Limits and the log.** 120 requests a minute per token (counted per worker, + like the read limits); the last use is written at most once a minute and not + at all while the maintenance flag is set; creating, renewing and revoking are + writes and get the 503 of that flag. The log has one line per use: the first + 8 characters of the token and the route, no personal data. +- **Stored.** Only the SHA-256 of a token is stored (collection + `access_tokens`), so a leaked database holds no usable token. + ## Custom domain (`2ndchances.build`) `2ndchances.build` is the canonical frontend origin; The old address `ddu.uber.space` diff --git a/docs/adr/DESIGN_DECISIONS.md b/docs/adr/DESIGN_DECISIONS.md index f43280cf..e8cf8dc9 100644 --- a/docs/adr/DESIGN_DECISIONS.md +++ b/docs/adr/DESIGN_DECISIONS.md @@ -301,6 +301,8 @@ into one **metadata object**. | 8.164 | **Content-Security-Policy: scripts by nonce, styles inline allowed** (user 2026-10-17; 0.6.2.0 T6, completes 8.144 g). The web app sends one CSP header, built per request in `proxy.ts` (its matcher then covers every page path, auth gated inside the function): `default-src 'self'`; `script-src 'self' 'nonce-' 'strict-dynamic' 'wasm-unsafe-eval'` (wasm for the meshopt decoder drei always sets up; local development adds `'unsafe-eval'` and `ws:` for HMR); `style-src 'self' 'unsafe-inline'`; `img-src 'self' blob: data:` (plus the static host when `NEXT_PUBLIC_STATIC_BASE_URL` is set); `connect-src 'self'`; `font-src 'self'`; `worker-src 'self' blob:`; `media-src 'self' blob:`; `frame-src https://maps.google.com https://www.google.com`; `object-src 'none'`; `base-uri 'none'`; `form-action 'self'`; `frame-ancestors 'none'`. The nonce goes to Next's own scripts (automatic) and to next-themes (`nonce` prop from the request headers). The static `frame-ancestors` CSP of `lib/securityHeaders.ts` is merged into it (one CSP header); `X-Frame-Options` and the other headers of 8.144 g stay. Rollout (user, same day): enforced at once, no Report-Only phase and no report endpoint. Before the release the implementer walks the production build (`next build` + `next start`, not dev) through the main pages in a browser with the console checked for violations (home, Browse, map, component page with mesh, point cloud and proxy overlay, History with the swimlane PNG export, photos, QR scanner, the Google map, sign-in, registration, admin, mail preview, GH interface); a test checks one CSP header, a fresh nonce per request and the directives. Emergency switch: `CSC_CSP_REPORT_ONLY=1` in the frontend environment sends the same policy as `Content-Security-Policy-Report-Only` (restart of the frontend). | Every page already renders per request (`force-dynamic`), the app has no inline script of its own and talks to its own origin only, so a strict script policy costs little; styles stay inline-allowed because sonner, Radix's scroll lock, styled-jsx and the mail preview inject un-nonced `