potiuk opened a new pull request, #321: URL: https://github.com/apache/incubator-ponymail-foal/pull/321
## Summary Implements #312 — programmatic API access via an `Authorization: Bearer <token>` header, so scripts/automation can authenticate without a user's OAuth credentials and without the short session-cookie lifetime. - Personal API tokens (create / list / revoke) via a new `/api/token` endpoint and a web-UI panel (user menu → **API Tokens**). - Stored **SHA-256-hashed** (raw secret shown once); **opt-in** — `tokens.enabled`, disabled by default. - **Per-action scopes** (`read` / `write` / `admin`): a token's access is the *intersection* of the owner's account permissions and its scopes, so a scope can only restrict, never escalate. - CSRF-hardened management (JSON POST only), **audit-logged** create/revoke, **expiry + background reaper**, and an optional in-memory auth cache (disabled by default). - Invalid/expired/revoked tokens get an explicit **403** rather than a silent anonymous downgrade. Docs included/updated: `API.md` (incl. scope table), `api_client_guide.md`, `configuration.md`, `openapi.yaml`, `AGENTS.md`, `architecture.md`, `admin_guide.md`. ## Commits Two commits, following the repo's generated-file conventions: 1. **Add long-term API tokens…** — source, docs, tests. 2. **Rebuild generated files…** — `build.sh` output (`webui/js/ponymail.js` + HTML `?revision=` bumps) and `update_version.sh` output (`server_version.py`), regenerated from the committed source and kept separate as AGENTS.md / build.sh prescribe. ## Testing - **Manual / runtime e2e** against a live Foal + OpenSearch stack: login, create/list/revoke, the full scope-enforcement matrix (read-only denied compose/mgmt; an admin's read-only token still denied mgmt; scopes can't escalate), the CSRF guard, 403 on invalid/expired/revoked tokens, private-list access via bearer, the reaper, and the optional cache-TTL (delayed-revocation) behavior. - **Visual**: verified the web-UI token panel (create with scope checkboxes, list, revoke). - **End-to-end with the Pony Mail MCP**, which has a counterpart PR adding API-token support — the MCP authenticates to this endpoint with a bearer token end to end. _(Counterpart MCP PR link to follow.)_ - `black`, `mypy`, `pylint` (10/10) and `pytest` unit tests all pass. ## Flexibility This is a sizable change and I'm happy to adapt it to what the maintainers want: - **Split** into smaller PRs (e.g. core bearer auth → scopes → reaper/cache → UI) if that's easier to review and land. - **Drop** any feature you'd rather not carry — the optional cache, the background reaper, per-action scopes, or the audit logging can each be removed independently without touching the core. 🤖 Generated with [Claude Code](https://claude.com/claude-code) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
