diff --git a/00-overview/postgres-migration-roadmap.md b/00-overview/postgres-migration-roadmap.md index 9d8484e..7f2c099 100644 --- a/00-overview/postgres-migration-roadmap.md +++ b/00-overview/postgres-migration-roadmap.md @@ -476,6 +476,10 @@ | 2026-11-19 | Phase 3: freshness | Database freshness report matches the file backend issue-for-issue | | 2026-11-19 | Phase 3: search | Substring/line-match path at parity; PostgreSQL FTS index deferred to a performance phase | | 2026-11-19 | Phase 3: tests | Full suite: 57 passed, 1 known stale-freshness failure | +| 2026-11-19 | Phase 4: auth schema and sessions | `users` mirror fields, `user_sessions`, `oauth_states`, `webhook_events`; hashed session tokens; 7-day TTL | +| 2026-11-19 | Phase 4: gnexus-auth integration | OAuth 2.0 PKCE login/callback, `/me`, locale override, logout, HMAC-verified and idempotent webhooks; auth disabled when client credentials are absent | +| 2026-11-19 | Phase 4: route guard and actor | Anonymous requests rejected when auth is enabled; actor recorded on changesets, document versions and inventory versions | +| 2026-11-19 | Phase 4: tests | Full suite: 66 passed, 1 known stale-freshness failure | Notes: @@ -487,5 +491,10 @@ index is a later optimization, not a correctness requirement. - The date-dependent freshness test still fails because 25 documents are past their review interval. This is the recorded baseline, not a regression. -- The next phase is Phase 4: gnexus-auth SSO, users, roles, actor attribution, and - audit enforcement. +- Phase 4 is scaffolded without production credentials. Real login needs an OAuth + client registered by the owner in gnexus-auth (`client_id`, `client_secret`, + redirect URI) and its webhook secret, all supplied through `.env`/gnexus-creds. +- Role-specific publish policy and MCP key revocation on user block remain open; the + current rule is "authenticated and not blocked may write". +- The next phase is Phase 5: MCP streamable HTTP, per-user keys, provisioning, and + key revocation on user block. diff --git a/CLAUDE.md b/CLAUDE.md index 9349498..ba9b6bc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -95,6 +95,7 @@ - **`validation.py`** — the full-repo gate used before apply/commit: schemas parse as Draft 2020-12, every inventory file validates against its schema (`SCHEMA_BY_INVENTORY`), Markdown has required frontmatter, ids are unique per inventory file, and a regex scan detects raw secret assignments/private-key blocks. The separate inventory `docs`-link validator (`_validate_inventory_doc_links`) is intentionally disabled; freshness still reports those missing targets. - **`pending_changes.py`** — the write path. A proposal is a JSON file in `90-maintenance/pending-changes/`; `apply()` writes a Markdown doc or patches/creates an inventory item, runs whole-repo validation, and restores the previous file content if validation fails. Only `doc` and `inventory-item` kinds can be applied; full-file inventory replacement is not implemented. - **`git_adapter.py`** — status/diff/commit. Commit requires an explicit file list, rejects absolute/traversal/denied paths, runs validation first, stages only the named files, and creates a local commit only (never pushes). +- **`auth/`** — gnexus-auth integration: OAuth 2.0 PKCE login/callback, hashed browser sessions, user mirror, HMAC webhook handling, a pure-ASGI session guard, and the actor context used by writes. Authentication is disabled unless `GNEXUS_BOOK_AUTH_CLIENT_ID`, `..._CLIENT_SECRET`, `..._BASE_URL`, and `..._REDIRECT_URI` are set; disabled mode is intentional for local development. The guard exempts `/health`, `/me`, `/auth/*`, and `/webhooks/gnexus-auth*`. The `gnexus-gauth` client library is a pinned git dependency. - **`storage/`** — the PostgreSQL layer introduced for the migration. `models.py` defines the schema (documents/versions/blobs, inventory items/versions, changesets, users, audit), `db_repositories.py` implements the read interfaces, `pending_changes_db.py` implements draft/apply changesets transactionally, `documents.py` provides history/version/diff/restore, `validation.py` validates the database, `importer.py` copies the repository into PostgreSQL, `parity.py` compares both backends, and `cli.py` exposes `import`, `parity`, and `counts`. `factory.py` selects docs/inventory/pending repositories from `GNEXUS_BOOK_STORAGE_BACKEND`. Alembic lives in `server/alembic/`. In `db` mode all knowledge writes go through changesets; `commit_changes` is a no-op. Validation, freshness, and relationships use the selected backend. ### MCP server @@ -120,6 +121,6 @@ Tests run from `server/` with `pythonpath = ["."]`. Most tests read the real repository, so they assert on real inventory/docs content; fixture-based tests use `Settings(tmp_path)` and copy schemas from the real repo. -Database tests use `GNEXUS_BOOK_TEST_DATABASE_URL` (default `postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test`) and skip when PostgreSQL is unavailable. `tests/test_db_storage.py` covers read parity, `tests/test_db_changesets.py` covers versioning/changesets/history/diff/restore, and `tests/test_migrations.py` applies the Alembic migration to a temporary database. +Database tests use `GNEXUS_BOOK_TEST_DATABASE_URL` (default `postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test`) and skip when PostgreSQL is unavailable. `tests/test_db_storage.py` covers read parity, `tests/test_db_changesets.py` covers versioning/changesets/history/diff/restore, `tests/test_auth.py` covers login, sessions, `/me`, the route guard and signed webhooks with mocked gnexus-auth HTTP calls, and `tests/test_migrations.py` applies the Alembic migration to a temporary database. `tests/test_docs_repository.py::test_freshness_report_is_clean_for_knowledge_docs` is date-dependent: it fails once documents pass their `review_interval`. When it fails, refresh `last_reviewed` only for docs whose content was actually reviewed, or treat the failure as genuine staleness. diff --git a/server/README.md b/server/README.md index 493155b..a94239d 100644 --- a/server/README.md +++ b/server/README.md @@ -46,6 +46,42 @@ `postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test`) and are skipped when PostgreSQL is unavailable. +## Authentication (gnexus-auth) + +Authentication is disabled unless the gnexus-auth client is configured. When the +following variables are present, the service guards every route except `/health`, +`/me`, `/auth/*`, and `/webhooks/gnexus-auth*`: + +```text +GNEXUS_BOOK_AUTH_CLIENT_ID +GNEXUS_BOOK_AUTH_CLIENT_SECRET +GNEXUS_BOOK_AUTH_BASE_URL +GNEXUS_BOOK_AUTH_REDIRECT_URI +GNEXUS_BOOK_AUTH_WEBHOOK_SECRET +GNEXUS_BOOK_AUTH_SESSION_COOKIE # default gnb_session +GNEXUS_BOOK_AUTH_COOKIE_SECURE # default true for https redirect URIs +GNEXUS_BOOK_AUTH_SESSION_TTL_SECONDS # default 604800 +``` + +Endpoints: + +- `GET /me` — `{auth_enabled, user, locale, locale_effective}`; returns `user: null` + when there is no session. +- `GET /auth/login` — redirects to gnexus-auth with OAuth PKCE. +- `GET /auth/callback` — exchanges the code, mirrors the `sub` user, and sets an + httpOnly session cookie. +- `POST /auth/logout` — revokes the session and clears the cookie. +- `PATCH /me` — stores the per-user locale override (`en`, `uk`, `ru`, or empty). +- `POST /webhooks/gnexus-auth` and `/webhooks/gnexus-auth/` — HMAC-verified + gnexus-auth events, idempotent by event id. + +Sessions are stored as SHA-256 hashes in `user_sessions`. Webhook signatures follow +gnexus-auth's `t=,v1=` scheme over `.`. + +Current Phase 4 scope: user mirroring, sessions, `/me`, webhook handling, and actor +attribution on changesets/versions. Role-specific publish policy and MCP key +revocation on user block arrive with Phase 5. + ## MCP Server The MCP server exposes the same repository, inventory, validation, pending-change, and Git commit logic through MCP tools and resources. @@ -112,6 +148,12 @@ - Swagger UI: `GET /api-docs` - `GET /health` +- `GET /me` +- `GET /auth/login` +- `GET /auth/callback` +- `POST /auth/logout` +- `PATCH /me` +- `POST /webhooks/gnexus-auth` - `GET /docs` - `GET /docs/read?path=...` - `GET /documents/{path}/history` @@ -141,7 +183,9 @@ - `POST /changes` creates pending change records in the file backend or changesets in the database backend. - `POST /changes/{id}/apply` applies `kind=doc` and `kind=inventory-item` changes transactionally after validation. - Database mode publishes on apply; `POST /commit` is only available with the file backend. -- No authentication yet. +- Authentication is gnexus-auth SSO when configured; without client credentials the service runs open for local development. +- Role-specific publish policy is not implemented yet: any authenticated, non-blocked user may write. +- MCP personal keys and key revocation on user block are not implemented yet. - File-backend `POST /commit` creates a local Git commit only. It does not push. - Commit requests must provide an explicit file list. - Validation uses JSON Schema 2020-12 for inventory records in both backends.