From 33ccf25f6f0db3ab375fabd94a68773d5fe8f4e2 Mon Sep 17 00:00:00 2001 From: root Date: Thu, 22 Oct 2026 16:04:30 +0000 Subject: [PATCH] Polish before 2.0.0: admin as app user, release tag guard, CI override check - README quick start and docs/INTEGRATION.md run src.admin with `exec --user 10001` so SQLite files in the data volume stay owned by the application user. - docs/INTEGRATION.md: the "Authlib example behind a proxy" section moves into the Mode 1 chapter. - release.yml: trigger only on vX.Y.Z and vX.Y.Z-* tags, and fail early when the tag is not semver instead of pushing an untagged build. - ci.yml: also validate deploy/ with the Docker-proxy override. Closes the four optional low findings of the final Part C inspection. Written by Claude; inspected by a fresh Codex session (APPROVED, no findings). Verification: 169 tests pass, ruff and actionlint clean, override config valid; admin commands as UID 10001 verified on a locally built 2.0.0 image (every file in /app/data owned by 10001). Co-Authored-By: Claude Opus 5.5 --- .github/workflows/ci.yml | 4 +++- .github/workflows/release.yml | 11 +++++++++- README.md | 11 +++++----- docs/INTEGRATION.md | 38 +++++++++++++++++------------------ 4 files changed, 38 insertions(+), 26 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e30d2e0..0fc9c98 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -63,7 +63,9 @@ jobs: run: docker compose -f docker/docker-compose.yml config --quiet - name: Validate release compose file - run: docker compose -f deploy/docker-compose.yml config --quiet + run: | + docker compose -f deploy/docker-compose.yml config --quiet + docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.docker-proxy.yml config --quiet - name: Build images run: docker compose -f docker/docker-compose.yml build diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ac18fb4..3592df7 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -2,7 +2,8 @@ name: Release image on: push: - tags: ['v*.*.*'] + # Final releases (v2.0.0) and prereleases (v2.1.0-rc.1); prereleases never move latest. + tags: ['v[0-9]+.[0-9]+.[0-9]+', 'v[0-9]+.[0-9]+.[0-9]+-*'] permissions: {} @@ -41,6 +42,14 @@ jobs: org.opencontainers.image.description=Telegram authentication with forward auth and OpenID Connect org.opencontainers.image.licenses=Apache-2.0 org.opencontainers.image.version=${{ steps.image.outputs.version }} + - name: Require a semver tag + env: + TAGS: ${{ steps.meta.outputs.tags }} + run: | + if [ -z "$TAGS" ]; then + echo "::error::${GITHUB_REF_NAME} is not a semver tag (vMAJOR.MINOR.PATCH[-PRERELEASE])" + exit 1 + fi - uses: docker/build-push-action@v6 with: context: . diff --git a/README.md b/README.md index 27b6d19..e538d69 100644 --- a/README.md +++ b/README.md @@ -38,23 +38,24 @@ For a pre-release walkthrough, build it locally first: 4. Invite yourself (works with both open and closed registration): ```bash - docker compose -f deploy/docker-compose.yml exec api python -m src.admin user invite alice + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin user invite alice ``` - The hosted `/login` page signs in existing users; it has no registration control. + Admin commands run as the application user (`--user 10001`) so that SQLite files in the + data volume stay owned by it. The hosted `/login` page signs in existing users; it has no registration control. Open the printed link and press Start in Telegram. Replace `alice` consistently with your chosen username in these commands. 5. Register and authorize the first app: ```bash - docker compose -f deploy/docker-compose.yml exec api python -m src.admin app add myapp --name "My App" - docker compose -f deploy/docker-compose.yml exec api python -m src.admin app allow myapp alice + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app add myapp --name "My App" + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app allow myapp alice ``` For a sibling app, register its actual origin too: ```bash - docker compose -f deploy/docker-compose.yml exec api python -m src.admin app origin add myapp https://app.example.com + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app origin add myapp https://app.example.com ``` 6. Paste the nginx, Traefik or Caddy protection snippet from diff --git a/docs/INTEGRATION.md b/docs/INTEGRATION.md index ba9ddea..9320ff1 100644 --- a/docs/INTEGRATION.md +++ b/docs/INTEGRATION.md @@ -20,17 +20,17 @@ root. Developers using `docker/` substitute `docker/docker-compose.yml` for that 1. Configure `PUBLIC_URL` to the externally visible TeleLogin base URL, without a trailing slash. Set up your bot and API as described in the README. Register a user via `POST /register` and follow the returned Telegram link, or invite one with - `docker compose -f deploy/docker-compose.yml exec api python -m src.admin user invite alice`. + `docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin user invite alice`. With `REGISTRATION_MODE=closed`, only CLI invitations create users. 2. Register your app on the server: ```sh - docker compose -f deploy/docker-compose.yml exec api python -m src.admin app add myapp --name 'My App' - docker compose -f deploy/docker-compose.yml exec api python -m src.admin app allow myapp alice + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app add myapp --name 'My App' + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app allow myapp alice ``` Default policy is `allowlist`; each username must already exist and be linked to Telegram. To allow every registered, linked user instead: ```sh - docker compose -f deploy/docker-compose.yml exec api python -m src.admin app policy myapp all + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app policy myapp all ``` 3. Choose a deployment shape: @@ -41,7 +41,7 @@ root. Developers using `docker/` substitute `docker/docker-compose.yml` for that In the sibling shape, restart API and bot with the updated settings, then run: ```sh - docker compose -f deploy/docker-compose.yml exec api python -m src.admin app origin add myapp https://app.example.com + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app origin add myapp https://app.example.com ``` The origin must receive the configured cookie. Origins have no path, query or fragment. HTTPS is required except localhost/127.0.0.1 development. Cookie domains must be a non-public parent @@ -184,8 +184,8 @@ preserves header-removal-before-auth ordering, then `copy_headers` supplies the ## Operator CLI -Run `docker compose -f deploy/docker-compose.yml exec api python -m src.admin --help`. -Prefix the subcommands below with `docker compose -f deploy/docker-compose.yml exec api python -m src.admin`. +Run `docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin --help`. +Prefix the subcommands below with `docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin`. Shell access is admin access. `gen-secrets` needs no `.env` or database and prints random `SECRET_KEY` and `INTERNAL_API_KEY` assignments. Never share them. @@ -212,8 +212,8 @@ The operator trusts every registered app; there is no consent screen. 1. Register a confidential client and its exact callback URL: ```sh - docker compose -f deploy/docker-compose.yml exec api python -m src.admin app add myapp --name "My App" --redirect-uri https://app.example.com/callback - docker compose -f deploy/docker-compose.yml exec api python -m src.admin app allow myapp alice + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app add myapp --name "My App" --redirect-uri https://app.example.com/callback + docker compose -f deploy/docker-compose.yml exec --user 10001 api python -m src.admin app allow myapp alice ``` Save the printed client secret: it is shown once and only its SHA-256 hash is stored. @@ -254,6 +254,16 @@ The operator trusts every registered app; there is no consent screen. ) ``` +### Running the Authlib example behind a proxy + +Set `APP_ORIGIN` to the app's external origin (`scheme://host[:port]`, no path or +trailing slash), for example `https://app.example.com`. Logout compares the browser +Origin against this value; when unset it uses the origin part of `request.base_url`. +Behind a trusted reverse proxy, start uvicorn with `--proxy-headers +--forwarded-allow-ips ` so callback URLs use the external +scheme. Configure the proxy to preserve the external Host and set forwarded headers. +Never trust forwarded headers from arbitrary public callers. + The stable UUID `sub` identifies the user. `profile` adds `preferred_username` and `name`. ID tokens are signed with RS256 and a public key from `/jwks.json`; access tokens are opaque, last 10 minutes by default, and work only at `/userinfo`. Raw API HS256 tokens and OIDC tokens @@ -281,13 +291,3 @@ The existing `/register`, `/auth/*`, `/internal/*` and JavaScript client retain See the [API documentation and JS client](../README.md). Raw API clients own their login page, number-matching polling, token storage/rotation and logout. Browser SSO cookies cannot be used as API refresh tokens, and API tokens cannot authorize forward-auth requests. - -### Running the Authlib example behind a proxy - -Set `APP_ORIGIN` to the app's external origin (`scheme://host[:port]`, no path or -trailing slash), for example `https://app.example.com`. Logout compares the browser -Origin against this value; when unset it uses the origin part of `request.base_url`. -Behind a trusted reverse proxy, start uvicorn with `--proxy-headers ---forwarded-allow-ips ` so callback URLs use the external -scheme. Configure the proxy to preserve the external Host and set forwarded headers. -Never trust forwarded headers from arbitrary public callers.