diff --git a/00-overview/postgres-migration-roadmap.md b/00-overview/postgres-migration-roadmap.md index d612cdc..7675b8c 100644 --- a/00-overview/postgres-migration-roadmap.md +++ b/00-overview/postgres-migration-roadmap.md @@ -492,6 +492,10 @@ | 2026-11-19 | Phase 7: cutover tooling | `cutover-db.sh`, `rollback-cutover.sh`, `30-runbooks/cutover-postgres.md`, systemd `EnvironmentFile` | | 2026-11-19 | Phase 7: rehearsal | Fresh `gnexus_book_cutover`: 30 documents, manifest match, 0 reconciliation differences, off-host dump, API smoke, file rollback verified; rehearsal database dropped | | 2026-11-19 | Phase 7: tests | Full suite: 78 passed, 1 known stale-freshness failure | +| 2026-11-19 | Local gnexus-auth: client | Local OAuth client `gnexus-book`, `all_active_users`, editor role, local redirect URIs, signed webhook; secrets only in `server/.env` | +| 2026-11-19 | Local gnexus-auth: end-to-end | Real login → authorize → callback → session → `/me` with `roles: ["editor"]` and `permissions: ["docs.write", "inventory.write"]`; `/mcp-keys` 200; logout verified | +| 2026-11-19 | Local gnexus-auth: webhook | A `webhook.test` delivery from gnexus-auth reached `POST /webhooks/gnexus-auth` with `200 OK` and was recorded in `webhook_events` | +| 2026-11-19 | Local gnexus-auth: UI | Auth gate rendered in headless Chromium against the live local gnexus-auth | Notes: @@ -517,5 +521,11 @@ untouched and remains the rollback source. - The retained cutover evidence is the migration report under `~/backup/gnexus-book/` and the off-host dump on NetTera8. -- The next step is connecting the local gnexus-auth instance (the same system as - production) and verifying login, callback, webhooks and actor attribution end to end. +- The local gnexus-auth instance is connected and verified end to end, including a + dedicated test user, roles/permissions and a real signed webhook delivery. Credentials + live only in `server/.env` and `~/.config/gnexus-book/`, never in the repository. +- The local client uses the permissive `all_active_users` access mode for testing. + Production must use an owner-registered client with HTTPS URLs and a narrower access + mode; role-specific publish policy is still open. +- The next phase is Phase 8: operations hardening, monitoring, documentation, and + decommissioning the file write path after the production cutover. diff --git a/30-runbooks/local-auth-testing.md b/30-runbooks/local-auth-testing.md new file mode 100644 index 0000000..535894e --- /dev/null +++ b/30-runbooks/local-auth-testing.md @@ -0,0 +1,105 @@ +--- +owner: gmikcon +status: active +last_reviewed: 2026-11-19 +review_interval: 90d +confidence: high +source_of_truth: local-auth-setup +--- + +# Local gnexus-auth testing + +How the local Gnexus Book instance is connected to the local gnexus-auth, which runs +the same code as production. + +## Components + +- gnexus-auth: `http://gnexus-auth.local` (nginx, MariaDB `gnexus_auth`). +- Gnexus Book backend: `http://127.0.0.1:3005`. +- Gnexus Book UI (Vite): `http://127.0.0.1:3006`. +- Gnexus Book MCP: `http://127.0.0.1:8001/mcp-protocol/`. + +## Configuration + +Runtime configuration lives in `server/.env` (`chmod 600`, gitignored). The systemd +units load it through `EnvironmentFile`; the local scripts source it before starting +the service. Do not commit it. + +Required variables: + +```text +GNEXUS_BOOK_STORAGE_BACKEND=db +GNEXUS_BOOK_DATABASE_URL=... +GNEXUS_BOOK_AUTH_CLIENT_ID=... +GNEXUS_BOOK_AUTH_CLIENT_SECRET=... +GNEXUS_BOOK_AUTH_BASE_URL=http://gnexus-auth.local +GNEXUS_BOOK_AUTH_REDIRECT_URI=http://127.0.0.1:3006/auth/callback +GNEXUS_BOOK_AUTH_WEBHOOK_SECRET=... +GNEXUS_BOOK_AUTH_COOKIE_SECURE=false +GNEXUS_BOOK_INTERNAL_KEY_SECRET=... +``` + +Store the same secrets in gnexus-creds for any shared or production deployment. + +## Local OAuth client + +- Slug: `gnexus-book`; access mode: `all_active_users`. +- Default role: `editor` with `docs.write` and `inventory.write`. +- Redirect URIs: `http://127.0.0.1:3006/auth/callback` and + `http://localhost:3006/auth/callback`. +- Local redirect URIs are enabled for this client. +- Webhook URL: `http://127.0.0.1:3005/webhooks/gnexus-auth`; insecure HTTP and private + network access are explicitly enabled for local testing. + +The client is registered through the gnexus-auth admin UI (`/admin/clients`) or an +equivalent local setup procedure. Production must use an owner-registered client, +HTTPS redirect/webhook URLs, and a narrower access mode. + +## Test user + +A dedicated local user exists for end-to-end tests: + +- Login: `gnexus-book-test@local.test`. +- Credentials: `~/.config/gnexus-book/local-auth-test-user.txt` (`chmod 600`, outside + the repository). +- Role: `editor`; permissions: `docs.write`, `inventory.write`. + +No real user account is used for automated checks. + +## Running locally + +```bash +# Backend with database storage and SSO (loads server/.env) +./scripts/dev-server.sh + +# MCP streamable HTTP (loads server/.env) +./scripts/dev-mcp.sh + +# UI +cd ui && npm run dev +``` + +Open `http://127.0.0.1:3006/` and use **Sign in**. The browser goes through +gnexus-auth and returns to `/auth/callback`; Vite proxies `/auth` and `/webhooks` to +the backend. + +## Verification + +- `GET /health` reports `storage: db` and `checks.db.status: ok`. +- Before sign-in, `GET /me` returns `auth_enabled: true` and `user: null`. +- After sign-in, `GET /me` returns the test user with `roles: ["editor"]` and + `permissions: ["docs.write", "inventory.write"]`. +- Protected routes return `401` without a session. +- `/mcp-keys` is available with a session. +- A gnexus-auth `webhook.test` delivery reaches + `POST /webhooks/gnexus-auth` with `200 OK` and appears in `webhook_events`. +- `POST /auth/logout` clears the session and `/me` returns `user: null`. + +## Production differences + +- Register the client in production gnexus-auth and use HTTPS redirect and webhook + URLs. +- Use `specific_users` or groups instead of `all_active_users`. +- Store client and webhook secrets in gnexus-creds; keep only runtime values in + `.env`. +- Configure the webhook endpoint without insecure HTTP/private-network overrides. diff --git a/CLAUDE.md b/CLAUDE.md index efe9e56..341c752 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -69,8 +69,16 @@ ../scripts/rollback-cutover.sh GNEXUS_BOOK_STORAGE_BACKEND=db .venv/bin/python -m uvicorn app.main:app --port 3005 + +# Local stack with database storage and gnexus-auth (loads server/.env) +../scripts/dev-server.sh +../scripts/dev-mcp.sh ``` +`server/.env` is gitignored and holds the local database URL, OAuth client, webhook +secret and internal key secret; systemd loads it through `EnvironmentFile`. Local SSO +details are in `30-runbooks/local-auth-testing.md`. + `GNEXUS_BOOK_STORAGE_BACKEND` defaults to `file`. Dumps go to the off-host NFS via `scripts/backup-db.sh`; `scripts/restore-db.sh` requires `GNEXUS_BOOK_RESTORE_YES=1`. diff --git a/server/README.md b/server/README.md index 60c23df..a41b7de 100644 --- a/server/README.md +++ b/server/README.md @@ -103,9 +103,23 @@ 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. +Current scope: user mirroring, sessions, `/me`, webhook handling, actor attribution, +MCP key management, and key revocation on user block. Role-specific publish policy is +still open. + +### Local gnexus-auth testing + +`server/.env` (gitignored, `chmod 600`) holds the runtime configuration. The local +scripts load it automatically: + +```bash +./scripts/dev-server.sh # backend on 127.0.0.1:3005, database + SSO +./scripts/dev-mcp.sh # MCP streamable HTTP on 127.0.0.1:8001 +``` + +The systemd units load the same file via `EnvironmentFile`. The local client, test +user, verification steps and production differences are documented in +[../30-runbooks/local-auth-testing.md](../30-runbooks/local-auth-testing.md). ## MCP Server