diff --git a/.gitignore b/.gitignore index 0bb07da..21d5c54 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,8 @@ .venv/ server/.venv/ +.env +.env.* +!.env.example __pycache__/ *.py[cod] .pytest_cache/ diff --git a/00-overview/postgres-migration-roadmap.md b/00-overview/postgres-migration-roadmap.md new file mode 100644 index 0000000..67c3070 --- /dev/null +++ b/00-overview/postgres-migration-roadmap.md @@ -0,0 +1,557 @@ +--- +owner: gmikcon +status: draft +last_reviewed: 2026-11-19 +review_interval: 30d +confidence: medium +source_of_truth: analysis-2026-11-19 +--- + +# PostgreSQL migration roadmap + +Execution plan for [ADR-0002](../50-decisions/ADR-0002-postgres-storage-and-versioning.md): +move Gnexus Book from file + Git storage to PostgreSQL with built-in versioning, +handbook-compliant authentication and MCP, and a later one-time migration of the +existing knowledge base. + +Platform rules are not repeated here. Read the +[gnexus-handbook](https://git.gnexus.space/root/gnexus-handbook/raw/master/README.md) +and the sections linked from the ADR before starting a phase. + +## 1. Goal and success criteria + +The migration is complete when: + +1. PostgreSQL is the system of record for documents, inventory, versions, users, + changesets, and audit data. +2. Every current capability listed in the ADR coverage matrix works against the + database with the same observable contract. +3. Every applied write is an immutable version grouped into an atomic changeset, + with author, actor, timestamp, summary, and reason. +4. Users authenticate through gnexus-auth; permissions are enforced; the actor of + every write is recorded. +5. MCP is served over streamable HTTP with per-user keys and provisioning. +6. The UI keeps its current capabilities and gains auth, history/diff, MCP keys, and + en/uk/ru localization. +7. Database dumps go to a separate host and have been restored at least once. +8. The old file write path is removed; the Git repository remains as a read-only + archive. + +## 2. Scope + +### In scope + +- PostgreSQL schema and migrations. +- Application-level versioning: immutable versions, changesets, diff, rollback. +- Documents, inventory, relationships, validation, freshness, search. +- gnexus-auth SSO, user mirror, roles, actor attribution, audit. +- MCP streamable HTTP, per-user keys, key provisioning, key-management UI. +- UI parity plus auth gate, navigation, i18n, history/diff. +- One-time import of the existing Markdown/YAML knowledge base. +- Backups, health, monitoring, deployment, and service documentation. + +### Out of scope + +- Branches, merges, rebases, or a general-purpose distributed VCS. +- Markdown/JSONL export from the database (owner decision; dumps only). +- Visual topology map, embedding search, generated inventory index. +- Editing inventory/docs directly from the UI beyond the existing proposal flow. +- Public exposure decision; the service stays LAN-only until separately decided. + +## 3. Constraints and principles + +- **No big bang.** The file backend stays working until the database backend passes + parity tests and the owner approves cutover. +- **Dual-run before cutover.** The same read queries must be run against both backends + and compared. +- **Safety-first.** Backup and rollback plan before every risky phase; destructive + actions are announced first. +- **Handbook compliance is not a later phase.** Schema and interfaces must leave room + for SSO, per-user keys, actor fields, i18n, and off-host backups from the start. +- **The database is a single point of failure.** Off-host dumps and restore drills are + part of Phase 1, not a cleanup task. +- **Agent contracts matter.** Existing MCP tool names remain usable during a + transition period unless the owner chooses otherwise. + +## 4. Target architecture + +```text +Browser (cookie session) AI agent (Bearer mcp_* key) + | | + +----------------+-----------------+ + v + FastAPI / ASGI + +----------------+-----------------+ + | | + REST /api/* MCP /mcp-protocol/ + | | + +------------ service layer --------+ + | + repositories / unit of work + | + PostgreSQL + | + +----------------+-----------------+ + | | | + pg_dump cron gnexus-auth hard-panel / Synapse + -> separate host (SSO, webhooks) (health, alerts) +``` + +Implementation rules: + +- Routers and MCP tools call the same service functions, with the same validation and + error semantics. +- Repositories are split into interfaces with file-backed and database-backed + implementations until cutover. +- All writes go through a changeset service. No repository exposes an unversioned + write. +- Validation is a service used by apply/publish and by the read-only report endpoints. +- Search, relationships, and freshness are database queries, not filesystem scans. + +## 5. Workstreams + +| Stream | Covers | Main phases | +|---|---|---| +| A. Storage and schema | PostgreSQL, migrations, repositories, JSONB inventory | 1, 3 | +| B. Versioning and change management | Versions, changesets, diff, rollback, audit | 2 | +| C. Validation, search, relationships | Schemas, secret scan, FTS, freshness, graph | 3 | +| D. Identity and access | gnexus-auth SSO, users, roles, actor | 4 | +| E. MCP | Streamable HTTP, keys, provisioning, tool parity | 5 | +| F. UI | Auth gate, navigation, i18n, history/diff, MCP keys | 6 | +| G. Migration and cutover | Importer, dual-run, reconciliation, freeze | 7 | +| H. Operations and documentation | Backups, health, monitoring, docs, decommission | 1, 8 | + +## 6. Decision gates + +Resolve these before the phase that depends on them. On 2026-11-19 the owner +instructed implementation to proceed, so the recommended defaults below are adopted as +implementation defaults. They can still be overridden before the dependent phase. + +| ID | Decision | Recommended default | Needed by | +|---|---|---|---| +| D1 | Import Git history or current state only? | Import the current state as one import changeset; optionally replay Git history later | Phase 7 | +| D2 | Keep old MCP tool names? | New names primary, old names as deprecated aliases for one transition period | Phase 5 | +| D3 | May agents publish without review? | Publish content changes; require owner review for access, security, network exposure, backup, and critical-service changes | Phase 4 | +| D4 | Document identity | UUID primary key + mutable slug with a redirect table; keep `path` in the API as an alias | Phase 1 | +| D5 | What is "raw inventory"? | Canonical YAML serialized from JSONB, explicitly marked as generated | Phase 3 | +| D6 | Service exposure | LAN-only first; decide on a `*.gnexus.space` subdomain and public MCP later | Phase 6 | +| D7 | Delete/rename scope | Rename with redirects and soft delete in v1; hard delete out of scope | Phase 2 | + +## 7. Roadmap phases + +Effort is relative: S (days), M (1–2 weeks), L (several weeks). These are planning +sizes, not commitments. + +### Phase 0 — Baseline, backup, decisions (S) + +Goal: start from a known, recoverable state. + +Tasks: + +- Copy today's backup archive and Git bundle to a separate host or NAS; verify the + copy and perform a restore test there. +- Resolve decision gates D1–D7 or explicitly defer each one. +- Record the test baseline: current suite result and the known date-dependent + freshness failure. +- Decide how to handle that test: review documents whose content is actually verified, + or relax the assertion to ignore expected `stale-document` warnings. Do not fake + `last_reviewed`. +- Choose the PostgreSQL deployment topology for development and production + (containers or native service), and where dumps go. +- Confirm the first database version and migration tool (recommended: SQLAlchemy 2.0 + with Alembic and psycopg). + +Acceptance: + +- Backup exists off-host and has been restored there. +- Decisions D1–D7 are recorded in this document or the ADR. +- The team knows which tests are expected to fail and why. + +Rollback: none needed; this phase only adds safety. + +### Phase 1 — Database foundation and read mirror (M) + +Goal: serve every read from PostgreSQL while the file backend remains canonical for +writes. + +Deliverables: + +- PostgreSQL service for development and production; `.env` configuration; DB + credentials from the platform secret process. +- SQLAlchemy models and the first Alembic migration for: + `documents`, `doc_versions`, `blobs`, `inventory_types`, `schemas`, + `inventory_items`, `inventory_item_versions`, `changesets`, `change_items`, + `validation_runs`, `audit_log`, plus reserved `users`/actor columns. +- Repository interfaces and two implementations: existing file-backed and new + database-backed. +- Importer v0: current Markdown/YAML/schemas → database. +- Read paths (`/docs`, `/docs/read`, `/search`, `/inventory`, `/relationships`, + `/validate`, `/health/freshness`) switchable by configuration. +- Parity test harness that runs the same queries against both backends. +- `pg_dump` job to a separate host, retention policy, and a restore script. + +Acceptance: + +- Every read endpoint returns equivalent results from both backends on the current + corpus. +- Import is repeatable and produces the same checksums. +- A dump from the new database has been restored on the separate host. +- No write path has been switched yet. + +Rollback: change the configuration back to the file backend; the database can be +dropped and re-imported. + +### Phase 2 — Versioned documents and changesets (M) + +Goal: replace the document write path and Git commit semantics. + +Deliverables: + +- Service layer with document reads and writes, validation, and changeset handling. +- Draft → apply/publish flow in one transaction; failure leaves no partial state. +- Immutable versions with parent pointers, author, actor, timestamps, summary, reason. +- Diff between versions and against the current version. +- Rollback as a new version pointing at old content. +- Audit entries for every applied changeset. +- API compatibility: keep `POST /changes`, `GET /changes`, `GET /changes/{id}`, + `POST /changes/{id}/apply`; add explicit changeset/publish endpoints. +- MCP compatibility: `propose_doc_change`, `apply_pending_change`, `update_doc` keep + working; `commit_changes` maps to publish or becomes a deprecated alias (D2). + +Acceptance: + +- Document create/update through the proposal flow works against the database. +- Validation failure rolls the transaction back and leaves the previous version + current. +- Concurrent writes do not lose updates; conflicting edits are rejected or serialized. +- History, diff, and rollback are covered by tests. +- The file backend is no longer used for document writes in the database mode. + +Rollback: keep the file write path behind a feature flag until Phase 7. + +### Phase 3 — Inventory, relationships, search, freshness (M) + +Goal: reach full functional parity for inventory and derived views. + +Deliverables: + +- Inventory read/write services over JSONB; per-type schemas stored in `schemas`. +- Unique `(type, item_id)` among live items; immutable item IDs. +- Patch/update and create semantics matching today's behavior. +- Schema validation, duplicate detection, and the existing secret scan applied to + candidate versions. +- Relationship graph computed from inventory data, including unresolved references. +- Search: PostgreSQL FTS plus a substring/line-match path that preserves the current + response shape. +- Freshness queries: required metadata, staleness by interval, missing `docs` targets. +- Importer v1 for inventory and schemas. + +Acceptance: + +- The ADR coverage matrix is satisfied for docs and inventory. +- `validate_repository` is clean on the imported database. +- Relationships match the file backend exactly on the current corpus. +- Search returns the same matching paths and line content for the parity fixture set. + +Rollback: database mode remains read-only for inventory writes until parity is signed +off. + +### Phase 4 — Identity, access, audit actor (M) + +Goal: make the service genuinely multi-user and handbook-compliant. + +Deliverables: + +- gnexus-auth OAuth 2.0 PKCE client; `/auth/login`, `/auth/callback`, `/auth/logout`, + `GET /me`. +- Cookie session tables and PKCE state storage (or the Synapse Bearer variant, if + chosen). +- Local user mirror keyed by `sub`; profile is the source of truth. +- Webhooks with HMAC verification: profile update, global logout, session revocation, + user blocked/archived/deleted, role/permission changes. +- Roles and permissions; policy for read, propose, publish, and administration (D3). +- Actor fields on writes: `actor_kind`, `actor_name`, `via`; `X-Actor: user` for REST + and `is_user` for MCP write tools. +- Locale preference storage and effective-locale resolution. + +Acceptance: + +- Unauthenticated API calls are rejected; `/health` stays public. +- A user without publish permission cannot publish. +- A blocked user loses sessions; webhook handlers are tested. +- Every write records the correct actor independently of the key owner. +- No custom password storage or login page exists. + +Rollback: authentication can be disabled in development (auth-off pattern), but the +production database must not be exposed without it. + +### Phase 5 — MCP compliance and key management (M) + +Goal: make agents first-class, per-user consumers of the service. + +Deliverables: + +- Streamable HTTP MCP endpoint at `/mcp-protocol/` (trailing slash preserved). +- Legacy SSE adapter only if needed for old clients; stdio kept for tests and local + development only. +- ASGI bearer guard: hash lookup, uniform `401`, `WWW-Authenticate`, `last_used_at`. +- `mcp_tokens` storage with hash, hint, consumer, role/scopes snapshot, revoke. +- Per-user key management UI/API; one active key per (`user_id`, `consumer`). +- `/internal/keys` provisioning endpoints with service-to-service auth, allowlist, + rate limiting, and audit; not exposed through nginx. +- All existing tools and resources exposed over HTTP; mutating tools accept `is_user`; + tool errors returned as data. +- Tool names: new names primary, old names as aliases (D2). +- Rate limits for sensitive operations. + +Acceptance: + +- A personal key authenticates an MCP request; a revoked or blocked key gets `401`. +- Reissue returns plaintext once and revokes the old key; replayed create returns `409`. +- Provisioning is idempotent and audited. +- Tool catalog and resource behavior match the tool contract tests. +- `/internal` is unreachable from outside the allowed network. + +Rollback: keep the old MCP entry point available read-only during transition; revoke +new keys if necessary. + +### Phase 6 — UI parity and platform conventions (M) + +Goal: the UI covers the current functionality and follows the platform shell. + +Deliverables: + +- Auth gate with splash, `/me`, denied/ready states, and explicit login click. +- Drawer navigation; `GnPageHeader` on every page; kit components only. +- i18n module with `en`, `uk`, `ru`, account locale as default, per-service override. +- Documents: list, search, metadata, body, history, diff. +- Changesets: draft list, review, apply/publish, validation results. +- Inventory: types, records, JSON detail, raw view with the generated-format notice. +- Validation and freshness reports, including issue details. +- MCP keys page. +- Optional: Markdown rendering, traffic-route view, relationship graph. + +Acceptance: + +- All current UI capabilities are present. +- Login/logout, locale switch, history/diff, and key management work end-to-end. +- No visual styles are copied into the service; changes go to the UI kit. +- Accessibility and phone-width behavior are checked. + +Rollback: the UI can keep using the old endpoints until the new ones are proven; no +data is at risk. + +### Phase 7 — Migration, dual-run, cutover (L) + +Goal: move the existing knowledge base into the new system and make it canonical. + +Deliverables: + +- Importer v1 with validation, idempotency, and a dry-run mode. +- Optional Git history replay (D1): one changeset per commit, authors and timestamps + preserved, deleted documents represented as soft-deleted versions. +- Reconciliation report: document count, inventory count, version count, checksums, + validation and freshness parity. +- Full read parity run over the real corpus. +- Cutover runbook: announce, freeze writes, final import, switch configuration, + verify, unfreeze. +- Rollback runbook: switch back to the file backend and restore from the pre-cutover + dump. + +Acceptance: + +- The importer produces a database whose read results match the file backend for every + endpoint. +- Validation is clean; freshness differences are explained. +- Cutover and rollback have been rehearsed on a copy. +- The owner signs off. + +Rollback: pre-cutover dump + file backend still present and readable. + +### Phase 8 — Operations, documentation, decommission (M) + +Goal: operate the new system sustainably and remove the old path. + +Deliverables: + +- Automated off-host dumps, retention, alerting on failures, and a scheduled restore + drill; restore procedure in the service documentation. +- Health endpoint per the handbook contract: public, cheap, `status`, `checks.db`, + service/version/timestamp, no topology or personal data. +- hard-panel probe and Synapse alert route. +- systemd units and nginx configuration for the database-backed service and MCP + endpoint. +- Service page update in gnexus-book: access, infrastructure path, deployment, + backups, monitoring, MCP. +- Remove the file write path and unused Git adapter code. +- Archive the original repository and note it in the service page. + +Acceptance: + +- A restore drill has succeeded within the agreed retention window. +- Monitoring reports the service and alerts on failure. +- Documentation matches the running system. +- Legacy file-write code is gone; tests pass against the database only. + +Rollback: retain the final Git archive and the last pre-decommission dump. + +## 8. Milestones + +| Milestone | Meaning | +|---|---| +| M0 | Off-host verified backup and decisions D1–D7 recorded | +| M1 | All reads served from PostgreSQL with parity tests | +| M2 | Document writes, history, diff, rollback work in the database | +| M3 | Inventory, relationships, search, validation, freshness at parity | +| M4 | SSO, roles, actor attribution, audit enforced | +| M5 | MCP over streamable HTTP with per-user keys and provisioning | +| M6 | UI parity plus auth, i18n, history/diff, key management | +| M7 | Existing knowledge base migrated; cutover rehearsed and signed off | +| M8 | Operations, documentation, and decommission complete | + +## 9. Test strategy + +- **Unit tests** for versioning, changeset application, rollback, validation, and + relationship computation. +- **Integration tests** against a disposable PostgreSQL instance (containers or a + dedicated test database); every migration runs from zero in CI. +- **Parity harness**: file backend and database backend run the same read requests; + results are normalized and compared. +- **Contract tests** for REST and MCP: tool names, input schemas, error codes, and + resource URIs. +- **Concurrency tests**: parallel applies, conflicting edits, unique key constraints. +- **Security tests** from the handbook's key-provisioning checklist: creation, + reissue, revocation, blocked user, role snapshot, no plaintext storage, uniform 401. +- **Backup tests**: dump, off-host copy, restore, and checksum verification. +- **Performance smoke tests**: search and document reads within an agreed budget for + the current corpus; `/health` under 500 ms. +- **Migration tests**: importer idempotency and checksum stability. + +## 10. Risks and mitigations + +| Risk | Impact | Mitigation | +|---|---|---| +| Database loss | Loss of the knowledge base | Off-host dumps from Phase 1, retention, restore drills | +| Versioning scope creep | Delays, bugs | No branches/merges; only versions and changesets | +| Import drift | Silent data corruption | Checksums, dry runs, parity harness, pre-cutover dump | +| Broken agent contracts | Agents fail after release | Keep old MCP names as aliases; contract tests | +| Auth/key implementation bugs | Security incident | Use gnexus-auth client library; follow handbook tests; no fallbacks | +| Loss of filesystem workflows | Harder ad-hoc search/editing | Keep a read-only Git archive; provide search and history in the UI | +| Performance regressions | Slow UI/agents | Indexes from the start; FTS; measure current corpus in Phase 3 | +| Operational overload | Missed backups or alerts | Automate from Phase 1; monitor the backup job itself | + +## 11. Definition of done + +- The ADR coverage matrix is fully checked off. +- All tests pass against PostgreSQL; no test depends on the file backend for writes. +- SSO, roles, actor attribution, and audit are enforced. +- MCP follows the handbook transport, key, provisioning, and actor rules. +- UI follows the platform shell and supports en/uk/ru. +- Off-host backups and a restore drill are documented and verified. +- Health, monitoring, and alerts are live. +- The service page in gnexus-book is current. +- The old file write path is removed and the Git repository is archived read-only. + +## 12. Immediate next steps + +1. Copy the 2026-11-19 backup to a separate host and restore-test it there. +2. Resolve D1–D7 or mark them explicitly deferred. +3. Start Phase 1: local PostgreSQL, SQLAlchemy models, first Alembic migration, + repository interfaces, importer v0, and parity harness. + +## 13. Implementation status + +| Date | Item | Status | +|---|---|---| +| 2026-11-19 | Off-host backup of the knowledge base | Copied to `~/NetTera8/service/backups/gnexus-book/2026-11-19_181859`; Git bundle, archive, and SHA256 verified on the NFS host | +| 2026-11-19 | Decision gates D1–D7 | Adopted as implementation defaults | +| 2026-11-19 | Phase 1: PostgreSQL foundation | Dev cluster on `127.0.0.1:5433`; SQLAlchemy models; Alembic initial migration; database-backed read repositories; importer v0 | +| 2026-11-19 | Phase 1: import and parity | 29 documents, 84 inventory items, 12 inventory types, 13 schemas imported; parity check reports 0 differences | +| 2026-11-19 | Phase 1: backups | `scripts/backup-db.sh` produced a custom-format dump on the off-host NFS; `scripts/restore-db.sh` restored it into a temporary database with matching counts | +| 2026-11-19 | Phase 2: versioned writes | Database-backed draft/apply changesets; immutable document and inventory versions; transactional validation with rollback; audit entries | +| 2026-11-19 | Phase 2: history, diff, restore | API and MCP expose `document_history`, `document_version`, `document_diff`, and `restore_document_version`; restore creates a new version | +| 2026-11-19 | Phase 2: validation | `GET /validate` and the MCP validation tool validate the database in `db` mode | +| 2026-11-19 | Phase 2: tests | Full suite: 56 passed, 1 known stale-freshness failure | +| 2026-11-19 | Phase 3: inventory and relationships | Database read/write for inventory, schema validation from stored schemas, unique live item IDs, relationship graph over database records | +| 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 | +| 2026-11-19 | Phase 5: streamable HTTP MCP | Guarded `/mcp-protocol/` endpoint via `app.mcp_http`; stdio remains for tests/local development | +| 2026-11-19 | Phase 5: personal keys | `mcp_tokens` with hash + hint, one active key per (`user_id`, `consumer`), session key API, `/internal/keys` provisioning, rate limits | +| 2026-11-19 | Phase 5: actor and revocation | Mutating tools accept `is_user`; REST accepts `X-Actor`; blocked users lose all keys; role changes mark keys stale | +| 2026-11-19 | Phase 5: tests | Full suite: 75 passed, 1 known stale-freshness failure | +| 2026-11-19 | Phase 6: shell and auth gate | Drawer navigation, `GnPageHeader` on every page, gnexus-auth gate, settings, logout | +| 2026-11-19 | Phase 6: pages and i18n | Docs search/history/diff/restore, inventory JSON/raw, changesets/apply, status reports, MCP keys page, en/uk/ru | +| 2026-11-19 | Phase 6: verification | Production build plus headless Chromium smoke in file mode, database mode and auth-gate mode; no browser console errors | +| 2026-11-19 | Phase 7: importer v1 | Source revision and content-manifest digest, post-import validation, database manifest verification, drift detection | +| 2026-11-19 | Phase 7: reconciliation | File/DB comparison now covers documents, search, inventory, relationships, validation and freshness | +| 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 | Owner-provided local client `gnexus-book-local`, `all_active_users`, local redirect URIs, editor role assigned to the test user, signed webhook; previous test client disabled; secrets only in `server/.env` | +| 2026-11-19 | Local gnexus-auth: end-to-end | Real login → authorize → callback → session → `/me` with `roles: ["editor"]` and empty client permissions; `/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 | +| 2026-11-19 | Review fixes: OAuth | Login CSRF closed with a short-lived state cookie; `return_to` validated and used after callback | +| 2026-11-19 | Review fixes: MCP/internal | FastMCP allowed hosts configurable for nginx; `/internal/keys` denied in nginx and rate-limited before secret checks; read-only keys cannot mint keys or call `commit_changes` | +| 2026-11-19 | Review fixes: data/audit | Secret scan covers every document version; actor user IDs stored in changesets and audit; concurrent changeset apply serialized | +| 2026-11-19 | Review fixes: config/runtime | `GNEXUS_BOOK_REPO_ROOT` honored by Settings; webhook database work moved off the event loop; stale README limitation removed | +| 2026-11-19 | Review fixes: tests | Full suite: 88 passed, 1 known stale-freshness failure; file/DB parity 0 | +| 2026-11-19 | Phase 8: backups and drills | Daily off-host backup timer, retention, checksum and failure alerts; restore-drill script and optional monthly timer | +| 2026-11-19 | Phase 8: health/monitoring | Healthcheck script, public `/health` contract, Synapse alert plumbing; hard-panel registration and Synapse source remain owner actions | +| 2026-11-19 | Phase 8: deploy/docs | `deploy.sh` applies migrations and refreshes units; operations and decommission runbooks; service page updated | +| 2026-11-19 | Phase 8: decommission | Blocked on production cutover and owner sign-off; file backend retained for rollback | +| 2026-11-20 | Data ownership | `documents.owner_user_id` and `inventory_items.owner_user_id`; `assign-owner`/`ownership` CLI; current 33 documents and 84 inventory items assigned to the first user (`sub=1`, superadmin); historical import authorship preserved | +| 2026-11-20 | Rollout state | Local database/auth rollout verified; production deployment target not available on the development machine and remains pending | + +Notes: + +- The default backend remains `file`. Set `GNEXUS_BOOK_STORAGE_BACKEND=db` to use + PostgreSQL for reads and writes. +- In database mode, applying a changeset publishes it; `commit_changes` is a no-op and + `POST /commit` is blocked. +- Search keeps the current substring semantics for exact response parity. A full-text + 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. +- 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 remains open; the current rule is "authenticated and + not blocked may write". MCP keys carry `read`/`write` scopes. +- The Vue UI now covers the current functionality, the auth gate, i18n and the MCP + keys page. Real gnexus-auth credentials are still required to exercise live login. +- Phase 7 tooling and the cutover rehearsal are complete. The actual production flip + is a deployment action: set `GNEXUS_BOOK_STORAGE_BACKEND=db` and the database URL in + `server/.env`, restart the backend and MCP units, then run the post-cutover checks in + [cutover-postgres.md](../30-runbooks/cutover-postgres.md). The Git checkout is + 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 local gnexus-auth instance is connected and verified end to end through the + owner-provided `gnexus-book-local` client, including a dedicated test user, the + `editor` role 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, a narrower access + mode and defined client permissions; role-specific publish policy is still open. +- A full review on 2026-11-19 found 12 issues; all are fixed and covered by regression + tests. Production deployment must set `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` to include the + public MCP hostname and `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` to include its HTTPS origin, + because FastMCP rejects unknown Host headers with `421`. +- Phase 8 operations are implemented locally: scheduled backups, restore drill, + healthcheck and Synapse alert plumbing, deploy migrations and runbooks. The actual + hard-panel probe and Synapse source/alert route still require owner credentials. +- Phase 8 decommission is not executed. The file backend, Git adapter and original + repository remain until the production cutover has run for the agreed stability + window and the owner signs off + [decommission-file-backend.md](../30-runbooks/decommission-file-backend.md). +- Current data ownership is assigned locally to the first user (`sub=1`, superadmin): + 33 documents and 84 inventory items, 0 unowned. Production assignment should use + `GNEXUS_BOOK_OWNER_JSON` during cutover or the `assign-owner` CLI afterwards. +- Production rollout is pending a deployment target: the development machine has no + `/home/ubuntu/gnexus-book`, `/var/www/gnexus-book`, or running Gnexus Book services. diff --git a/10-systems/applications/gnexus-book.md b/10-systems/applications/gnexus-book.md index c0b523c..8458887 100644 --- a/10-systems/applications/gnexus-book.md +++ b/10-systems/applications/gnexus-book.md @@ -1,7 +1,7 @@ --- owner: gmikcon status: active -last_reviewed: 2026-10-09 +last_reviewed: 2026-11-20 review_interval: 30d confidence: high source_of_truth: ssh-host-verified @@ -9,55 +9,114 @@ # Gnexus Book -Gnexus Book is the canonical infrastructure knowledge base and maintenance API for the personal digital and server infrastructure. +Gnexus Book is the canonical infrastructure knowledge base and maintenance API for the +personal digital and server infrastructure. -## Deployment +## Access -- Runs as KVM VM `gnbook` (192.168.1.170) on hypervisor `hp-proliant-dl380-g6` (192.168.1.130). -- SSH: `ubuntu` on 192.168.1.170 (credentials in gnexus-creds, secret `gnauth-gnbook-ssh`). +- UI and REST: gnexus-auth SSO when authentication is configured; otherwise the + local-development installation runs open. +- Agents: personal `mcp_*` keys over streamable HTTP at `/mcp-protocol/`. +- Service-to-service key provisioning: `/internal/keys`, protected by a service secret, + blocked in nginx. +- Secrets are references only; no raw credentials are documented here. + +## Deployment target + +- Runs as KVM VM `gnbook` (192.168.1.170) on hypervisor + `hp-proliant-dl380-g6` (192.168.1.130). +- SSH: `ubuntu` on 192.168.1.170; credentials live in gnexus-creds as + `gnauth-gnbook-ssh`. - Repository path: `/home/ubuntu/gnexus-book` (branch `master`). -- Source of truth: Markdown, YAML inventory, JSON Schema, and Git history. +- Current pre-cutover runtime: backend `http://192.168.1.170:8000/`, MCP SSE on + `:8001/sse`, UI `http://192.168.1.170/` via nginx, file-backed storage. +- Target runtime after the PostgreSQL cutover: MCP streamable HTTP at + `/mcp-protocol/`, PostgreSQL as the canonical store, SSO enforced when configured. +- Git remains the code repository and rollback source until the file backend is + decommissioned. -## Runtime Components +## Storage and ownership + +- PostgreSQL database `gnexus_book` is the target canonical store, with immutable + document and inventory versions grouped into changesets. +- Documents and inventory items carry `owner_user_id`. Current data is assigned to the + first admin user (`sub=1`, superadmin); historical import authorship remains + `system`/`importer`. +- The file backend (Markdown/YAML + Git) remains readable for rollback until the + production cutover is accepted and the decommission runbook is executed. + +## Runtime components - Backend: FastAPI under `server/`. -- Agent interface: MCP server under `server/app/mcp_server.py`. -- UI: Vue/Vite under `ui/`. -- UI dependency: `gnexus-ui-kit`. +- MCP: `server/app/mcp_http.py`, streamable HTTP at `/mcp-protocol/`. +- UI: Vue/Vite under `ui/`, using `gnexus-ui-kit`. +- Auth: gnexus-auth SSO plus per-user service keys. ## Endpoints -- REST API: `http://192.168.1.170:8000/` (uvicorn, openapi at `/openapi.json`). -- MCP (SSE): `http://192.168.1.170:8001/sse`. -- UI (LAN): `http://192.168.1.170:80/` (nginx serves the built SPA). -- Services run as user-level systemd units under `user@1000.service`: `gnexus-book-backend.service` (uvicorn :8000) and `gnexus-book-mcp.service` (MCP server). +- REST API on gnbook: `http://192.168.1.170:8000/` (uvicorn). +- UI on gnbook: `http://192.168.1.170/` (nginx serves the built SPA and proxies + `/api/`, `/auth/`, `/webhooks/gnexus-auth`, `/mcp-protocol/`). +- MCP on gnbook: `http://192.168.1.170:8001/mcp-protocol/`. +- Local development: backend `127.0.0.1:3005`, UI `127.0.0.1:3006`, MCP + `127.0.0.1:8001/mcp-protocol/`. +- systemd user units under `user@1000.service`: backend, frontend, MCP, daily backup, + optional monthly restore drill. -## Backups (set up 2026-10-09 by rei, owner-requested) +## Backups and recovery -- **Script**: `/home/ubuntu/gnexus-book-backup.sh` (700, owner ubuntu) on gnbook. -- **What**: full snapshot of the whole repo directory `/home/ubuntu/gnexus-book` as `tar.gz` (includes `.git` history, modified `40-inventory/*.yml`, and all untracked `90-maintenance/pending-changes/*.json` — 271 pending files are NOT in git, so a git-only backup would lose them) + `git bundle create --all` as a restorable history insurance. -- **Schedule**: ubuntu crontab, daily 03:10 UTC (06:10 Europe/Kyiv), log: `/opt/backups/gnexus-book/backup.log` + cron.log. -- **Retention**: 10 days (`find -mtime +10 -delete` for both `gnexus-book-*.tar.gz` and `gnexus-book-*.bundle`). -- **Sanity checks**: tar must be non-empty and listable (contains README.md); bundle must pass `git bundle verify` (complete history). Any failure → exit 1, logged. -- **Typical size**: tar.gz ~34.5 MB, bundle ~615 KB. Disk on gnbook: 15G total, 2.2G free — retention is mandatory, do not raise without checking disk. -- **Verified**: manual run 2026-10-09 09:45 UTC, EXIT=0, gnexus-book-20261009-094532.tar.gz 34564532 bytes + bundle 614785 bytes, bundle verify OK ("complete history"). -- **Restore sketch**: `tar xzf gnexus-book-.tar.gz -C /home/ubuntu` restores the full repo including pending changes; or `git clone gnexus-book-.bundle restored` for history-only restore (working-tree modifications and untracked pending JSONs are NOT in the bundle — use the tar.gz for full restore). -- **Caveat**: `master` is ahead of `origin/master` by 185 commits (origin is stale) — local backups are currently the only copy of recent history. Consider pushing to GitBucket (git.gnexus.space) as an off-host copy. +Legacy file-level backup (set up 2026-10-09): -## Maintenance Model +- Script `/home/ubuntu/gnexus-book-backup.sh` on gnbook; full repo `tar.gz` including + `.git`, modified inventory, and untracked pending-change JSON files, plus a + `git bundle --all`. +- Daily 03:10 UTC via ubuntu crontab; 10-day retention; tar and bundle sanity checks. +- Typical size: tar ~34.5 MB, bundle ~615 KB. The VM has about 2 GB free; retention + is mandatory. +- `master` is ahead of `origin/master` by 309 commits, so local backups are currently + the only copy of recent history. +- Restore: extract the tar for the full repository including pending changes; a bundle + clone restores history only. -Agents should prefer structured inventory changes, validation, pending changes, and local commits through the maintenance API. +PostgreSQL backup and recovery: -Pending-change queue lives in `90-maintenance/pending-changes/` (untracked JSON files; 11 older ones are git-tracked). Repository-wide validation scans every pending JSON, so a single invalid pending file blocks all applies and commits. +- Daily off-host `pg_dump` through `gnexus-book-backup.timer`; retention is configured + by `GNEXUS_BOOK_BACKUP_KEEP`. +- Restore procedure and periodic drill: [../../30-runbooks/postgres-operations.md](../../30-runbooks/postgres-operations.md). +- Backup failures and failed health probes alert through Gnexus Synapse when a `syn_*` + source key is configured. +- Keep the legacy file backup until the decommission is complete. -Poisoned-pending protection (since 2026-09-24, commit c77bcb1): +## Legacy file pending-changes protection -- Create (`propose_doc_change`, `propose_inventory_item_change`, `update_doc`): payloads with secret patterns or unsafe doc targets (outside repo root) are rejected BEFORE any file is written — a rejected request leaves no pending file behind. -- Apply: on validation failure the target file is rolled back AND the change's own pending JSON is removed (full rollback, both doc and inventory-item paths). -- `delete_pending_change` (MCP) / `DELETE /changes/{id}` (REST): deletes pending or corrupt records; applied records are refused (409). -- `list_pending_changes` tolerates corrupt JSON files and reports them with status `corrupt`; corrupt records can be deleted but not applied. -- `update_doc` cleans up its own pending JSON automatically if apply or commit fails. +The file backend has poisoned-pending protection (commit `c77bcb1`, 2026-09-24): -For agent-facing MCP usage rules, see [../../90-maintenance/agent-mcp-usage.md](../../90-maintenance/agent-mcp-usage.md). +- create rejects secrets and unsafe doc targets before writing any pending file; +- failed apply rolls back the target and removes the change's own pending JSON; +- `delete_pending_change` / `DELETE /changes/{id}` deletes pending or corrupt records; +- corrupt pending JSON is listed with status `corrupt`, can be deleted, cannot be + applied; +- `update_doc` cleans up its pending JSON if apply or commit fails. -No raw credentials are documented here. +In database mode the equivalent unit is a draft changeset; deletion is allowed only +while it is still a draft. + +## Monitoring + +- `GET /health` follows the platform contract (`status`, `checks.db`, service, + version, timestamp); it is public and contains no personal data. +- hard-panel probes the same endpoint; alerts are routed through Synapse. +- Local check: `scripts/healthcheck.sh`. + +## Maintenance model + +Agents should prefer structured inventory changes, validation, draft changesets and +apply/publish through the maintenance API or MCP. For MCP rules see +[../../90-maintenance/agent-mcp-usage.md](../../90-maintenance/agent-mcp-usage.md). + +Deployment and cutover: + +- [../../30-runbooks/cutover-postgres.md](../../30-runbooks/cutover-postgres.md) +- [../../30-runbooks/postgres-operations.md](../../30-runbooks/postgres-operations.md) +- [../../30-runbooks/decommission-file-backend.md](../../30-runbooks/decommission-file-backend.md) +- [../../30-runbooks/local-auth-testing.md](../../30-runbooks/local-auth-testing.md) diff --git a/30-runbooks/cutover-postgres.md b/30-runbooks/cutover-postgres.md new file mode 100644 index 0000000..4f86b8f --- /dev/null +++ b/30-runbooks/cutover-postgres.md @@ -0,0 +1,106 @@ +--- +owner: gmikcon +status: draft +last_reviewed: 2026-11-19 +review_interval: 90d +confidence: high +source_of_truth: migration-runbook +--- + +# PostgreSQL cutover runbook + +Move Gnexus Book from the file backend to PostgreSQL. The Git checkout is never +modified by this procedure; it remains the rollback source until the cutover is +accepted. + +## Preconditions + +- The pre-cutover backup has been copied off-host and restored at least once. +- `validate_repository` is clean on the file backend. +- The target PostgreSQL database exists and is reachable. +- The target is either empty or the operator explicitly passes `--replace`. +- The owner has chosen a maintenance window and confirmed the cutover. +- Real gnexus-auth credentials are configured before exposing the service outside + the LAN; database cutover and authentication cutover can be separate steps. + +## Rehearsal + +Always rehearse on a disposable database first: + +```bash +createdb gnexus_book_cutover +GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://USER@HOST:PORT/gnexus_book_cutover \ + ./scripts/cutover-db.sh --replace +``` + +The script runs the importer, validates the imported database, reconciles file and +database reads (documents, search, inventory, relationships, validation, freshness), +and writes a migration report. It must exit `0`. + +## Cutover + +1. Announce the maintenance window and the rollback plan. +2. Freeze writes to the file backend (stop the backend service or put it in + maintenance mode). +3. Run the cutover against the target database: + + ```bash + GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://USER@HOST:PORT/gnexus_book \ + ./scripts/cutover-db.sh --replace + ``` + +4. Assign imported data to the first admin (recommended). Either set + `GNEXUS_BOOK_OWNER_JSON=/path/to/owner.json` before step 3 (then + `cutover-db.sh` assigns it after import), or run after import: + + ```bash + cd server + GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://... \ + .venv/bin/python -m app.storage.cli assign-owner \ + --user-json /path/to/owner.json + .venv/bin/python -m app.storage.cli ownership + ``` + + The owner JSON contains `sub`, `email`, `system_role`, `status` and `profile` + (`display_name`, `locale`, `timezone`, avatar URL). + +5. Set the service environment: + + ```text + GNEXUS_BOOK_STORAGE_BACKEND=db + GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://... + ``` + +6. Restart `gnexus-book-backend` and `gnexus-book-mcp`. +7. Run the post-cutover checks below. +8. Unfreeze writes and announce completion. + +## Post-cutover checks + +- `GET /health` reports `storage: db` and `checks.db.status: ok`. +- `GET /docs`, `/search`, `/inventory`, `/relationships`, `/validate`, + `/health/freshness` return the expected data. +- `GET /documents//history` returns imported version 1. +- A test changeset can be proposed and applied, with validation passing. +- The UI loads documents, history, inventory and status. +- MCP over `/mcp-protocol/` works from the public hostname (no `421 Invalid Host + header`); `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` includes that host and + `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` includes its HTTPS origin. +- A fresh off-host dump exists and its checksum verifies. + +## Rollback + +The file backend remains intact. To roll back: + +1. Set `GNEXUS_BOOK_STORAGE_BACKEND=file`. +2. Restart `gnexus-book-backend` and `gnexus-book-mcp`. +3. Run `scripts/rollback-cutover.sh` to verify file validation and document reads. +4. If the database must be restored separately, use `scripts/restore-db.sh` with the + pre-cutover dump and `GNEXUS_BOOK_RESTORE_YES=1`. + +## After acceptance + +- Keep the pre-cutover dump and the Git archive for the agreed retention period. +- Remove the file write path only after the database backend has run without incident. +- Record the cutover in gnexus-book and update the service page with backup and + restore instructions. diff --git a/30-runbooks/decommission-file-backend.md b/30-runbooks/decommission-file-backend.md new file mode 100644 index 0000000..eadefe2 --- /dev/null +++ b/30-runbooks/decommission-file-backend.md @@ -0,0 +1,57 @@ +--- +owner: gmikcon +status: draft +last_reviewed: 2026-11-19 +review_interval: 90d +confidence: high +source_of_truth: migration-runbook +--- + +# Decommission the file backend + +Remove the file write path and Git adapter after the production cutover is accepted. +**Not executed yet.** The file backend remains available for rollback and for tests +until the prerequisites below are met. + +## Prerequisites + +- Production has run on `GNEXUS_BOOK_STORAGE_BACKEND=db` for an agreed stability + window with no unresolved data incidents. +- The pre-cutover dump and a fresh post-cutover dump have both passed restore drills. +- `validate_repository` and `validate_database` are clean. +- The parity suite reports zero differences. +- The owner has signed off the decommission in writing. + +## Steps + +1. Archive the original Git repository: + - create a `git bundle` of all refs and a worktree archive; + - copy both off-host and verify SHA-256 and a restore. +2. Keep the last pre-decommission PostgreSQL dump off-host with the agreed retention. +3. Update defaults so tests and development no longer depend on the file backend. +4. Remove the file write path: + - `DocsRepository`, `InventoryRepository` write paths where no longer needed; + - `GitAdapter` commit path and `/commit` routing; + - file-specific pending changes (`90-maintenance/pending-changes/*.json`). +5. Retarget the test suite to the database backend and remove file-parity fixtures + that no longer have a reference implementation. +6. Remove unused configuration (`GNEXUS_BOOK_STORAGE_BACKEND=file` branches) and + dependencies. +7. Update the service page, README, CLAUDE.md and this runbook. +8. Run the full test suite, validation, parity checks that still make sense, and a + restore drill. + +## Rollback + +Until the Git archive and the pre-decommission dump are retired: + +- restore the service from the last dump if the database is damaged; +- restore the file backend from the Git archive if the database path must be + abandoned entirely. + +After both artifacts are retired, rollback is no longer possible. + +## Status + +Blocked on the production cutover and owner sign-off. No file-backend code has been +removed. diff --git a/30-runbooks/local-auth-testing.md b/30-runbooks/local-auth-testing.md new file mode 100644 index 0000000..5e076e7 --- /dev/null +++ b/30-runbooks/local-auth-testing.md @@ -0,0 +1,114 @@ +--- +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-local` (owner-provided local client); access mode: + `all_active_users`. +- Default role: `user`; the test user is explicitly assigned the `editor` client role. +- The client currently defines roles `editor`, `user`, `docs.write` and + `inventory.write`, but no client permissions. Gnexus Book mirrors the roles snapshot + and does not depend on client permissions for authorization yet. +- 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 earlier `gnexus-book` test client is disabled and its secrets are revoked. The +active local client is the owner-provided `gnexus-book-local`. Production must use an +owner-registered client, HTTPS redirect/webhook URLs, a narrower access mode and +properly defined permissions. + +## 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` on the `gnexus-book-local` client; client permissions are currently + empty, so `/me` reports `roles: ["editor"]` and `permissions: []`. + +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 the + client's current permissions (empty until permissions are defined). +- 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. +- Set `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` to the public MCP hostname and + `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` to its HTTPS origin, otherwise FastMCP rejects + public requests with `421 Invalid Host header`. diff --git a/30-runbooks/postgres-operations.md b/30-runbooks/postgres-operations.md new file mode 100644 index 0000000..848fa52 --- /dev/null +++ b/30-runbooks/postgres-operations.md @@ -0,0 +1,115 @@ +--- +owner: gmikcon +status: active +last_reviewed: 2026-11-19 +review_interval: 90d +confidence: high +source_of_truth: repository +--- + +# PostgreSQL operations + +Backups, restore drills, health checks and migrations for the database-backed +Gnexus Book. + +## Backups + +- Unit: `systemd/gnexus-book-backup.service`, scheduled daily by + `gnexus-book-backup.timer` (`Persistent=true`, randomized delay up to 15 minutes). +- Script: `scripts/backup-db.sh`. + - custom-format `pg_dump` to `GNEXUS_BOOK_BACKUP_DIR` (off-host by default); + - `pg_restore --list` sanity check and SHA-256 checksum; + - keeps `GNEXUS_BOOK_BACKUP_KEEP` dumps (default 14); + - refuses to run if the off-host mount is unavailable and no explicit directory + is configured; + - on failure, sends a Synapse alert when `SYNAPSE_URL` and `SYNAPSE_API_KEY` are + configured. +- Manual run: + + ```bash + set -a; . server/.env; set +a + ./scripts/backup-db.sh + ``` + +A backup that has never been restored does not count. Run the restore drill below. + +## Restore drill + +```bash +set -a; . server/.env; set +a +./scripts/restore-drill.sh # latest dump +./scripts/restore-drill.sh /path/to.dump # specific dump +``` + +The script creates a temporary database, restores the dump, runs database validation +and count checks, prints the result and drops the temporary database. It requires a +database role with `CREATEDB`. + +`gnexus-book-restore-drill.timer` is installed but not enabled by default. Enable it +after the first successful manual drill: + +```bash +systemctl --user enable --now gnexus-book-restore-drill.timer +``` + +The monthly timer uses the same script and alerts through Synapse on failure. + +## Health and monitoring + +- `GET /health` is public, cheap and returns `status`, `service`, `version`, `storage`, + `timestamp` and `checks.db`. It exposes no users, secrets or topology. +- Monitor URL for hard-panel: `GNEXUS_BOOK_HEALTH_URL` (default + `http://127.0.0.1:8000/health`). +- Local probe: + + ```bash + ./scripts/healthcheck.sh + ``` + + It fails on a non-`ok` status or a failed `checks.db`, and sends a Synapse alert when + configured. +- Register the probe in hard-panel and create the alert route in Synapse. The book + service does not own notification channels; Synapse routing decides recipients. + +## Data ownership + +Imported documents and inventory can be assigned to the first admin user: + +```bash +set -a; . server/.env; set +a +cd server +.venv/bin/python -m app.storage.cli assign-owner --user-json /path/to/owner.json +.venv/bin/python -m app.storage.cli ownership +``` + +The owner JSON contains `sub`, `email`, `system_role`, `status` and `profile` +(display name, locale, timezone, avatar URL). The command creates or updates the local +user mirror, assigns only rows with no owner by default, and writes an +`ownership.assigned` audit record. `--all` transfers every document and inventory item +to the new owner. + +Ownership is separate from historical authorship: imported versions and the import +changeset retain their `system`/`importer` authorship, while `owner_user_id` records +who the data belongs to. + +## Migrations and deploys + +`scripts/deploy.sh` sources `server/.env`; when +`GNEXUS_BOOK_STORAGE_BACKEND=db`, it runs `alembic upgrade head` before restarting the +backend and MCP services. It also refreshes the systemd user units. + +## Secrets + +- Runtime values live in `server/.env` (`chmod 600`, gitignored) and in gnexus-creds. +- The Synapse source key (`SYNAPSE_API_KEY`) is a `syn_*` key, never a user key. +- Never commit database URLs, OAuth client secrets, webhook secrets or API keys. + +## Quick checks + +```bash +systemctl --user status gnexus-book-backend.service gnexus-book-mcp.service +systemctl --user list-timers 'gnexus-book-*' +./scripts/healthcheck.sh +psql -h 127.0.0.1 -p 5433 -U gmikcon -d gnexus_book -c \ + "select count(*) from documents;" +``` diff --git a/40-inventory/hosts.yml b/40-inventory/hosts.yml index 8578708..08f23e4 100644 --- a/40-inventory/hosts.yml +++ b/40-inventory/hosts.yml @@ -208,7 +208,7 @@ - 22 - 80 - id: hp-proliant-dl380-g6 - docs: 10-systems/hardware/hp-proliant-dl380-g6.md + docs: ../10-systems/hardware/hp-proliant-dl380-g6.md environment: home ip_address: 192.168.1.130 last_reviewed: '2026-05-09' @@ -218,7 +218,7 @@ type: physical user: bserv - id: tgbots - docs: 10-systems/hosts/tgbots.md + docs: ../10-systems/hosts/tgbots.md environment: production ip_address: 192.168.1.178 last_reviewed: '2026-06-05' @@ -964,7 +964,7 @@ lan: - 192.168.1.129 cpu_model: AMD Ryzen 5 3600 6-Core - docs: ../10-systems/hosts/gmikcon-pc.md + docs: ../10-systems/workstations/gmikcon-pc.md environment: home gpu: NVIDIA GeForce RTX 3090 24GB (driver 615.78.08) last_reviewed: '2026-11-08' diff --git a/50-decisions/ADR-0002-postgres-storage-and-versioning.md b/50-decisions/ADR-0002-postgres-storage-and-versioning.md new file mode 100644 index 0000000..a838523 --- /dev/null +++ b/50-decisions/ADR-0002-postgres-storage-and-versioning.md @@ -0,0 +1,295 @@ +--- +owner: gmikcon +status: draft +last_reviewed: 2026-11-19 +review_interval: 30d +confidence: medium +source_of_truth: analysis-2026-11-19 +--- + +# ADR-0002: PostgreSQL storage with built-in versioning + +## Status + +Draft, proposed on 2026-11-19. Not implemented and not accepted. + +## Context + +Gnexus Book currently keeps its knowledge base as Markdown and YAML inside a Git +checkout. The FastAPI server reads those files, applies proposed changes, validates +the whole repository, and creates local Git commits. The UI and MCP server are thin +layers over the same file-backed repositories. + +Current characteristics: + +- effectively single-user: no authentication, no actor attribution, no per-user data; +- Git is both the storage format and the version-control mechanism; +- every write is a filesystem mutation followed by a whole-repository validation; +- inventory items are YAML records validated by JSON Schema; +- pending changes are JSON files under `90-maintenance/pending-changes/`; +- the MCP server exposes 17 tools and 9 resources over stdio or SSE; +- the Vue UI has four read-oriented tabs and two write paths (apply change, commit). + +Owner direction (2026-11-19): + +1. Back up the current knowledge base before changing anything. +2. Move primary storage to a database. +3. Build version control into the service instead of relying on Git. +4. Keep the existing knowledge base as-is until the new system is tested, then migrate it. + +Platform-wide rules in [gnexus-handbook](https://git.gnexus.space/root/gnexus-handbook/raw/master/README.md) +also apply. They are not repeated here; the relevant sections are linked below. + +## Decisions + +### 1. PostgreSQL is the primary store + +PostgreSQL becomes the system of record for documents, inventory, versions, users, +changesets, and audit data. Git stops being the write path. + +Reasons: multi-user concurrency and transactions, relational integrity, full-text +search, JSONB for the flexible inventory records, mature backup/restore tooling. + +### 2. Versioning is application-level, not a Git reimplementation + +The service stores immutable document and inventory versions grouped into changesets. +It does **not** implement branches, merges, packfiles, remotes, or a general-purpose +distributed VCS. The current functionality does not require them. + +Required semantics: + +- every applied change creates a new immutable version; +- a changeset groups one or more versions and is applied atomically; +- author, actor, timestamp, summary, and reason are recorded; +- diff is computed between two versions on demand; +- rollback restores content by creating a new version, never by rewriting history; +- a failed validation aborts the transaction and leaves no partial state. + +### 3. Identity and access follow gnexus-handbook + +- User authentication is delegated to gnexus-auth (OAuth 2.0 PKCE). The service does + not own a user database or a login page; it mirrors the `sub` principal and profile. +- Browser sessions follow the cookie-session pattern (or the Synapse Bearer variant) + described in `10-platform/auth.md`. +- `user.*`, `global_logout`, `session.revoked`, and role/permission webhooks are + required, with HMAC verification. +- Locale preference is stored per user and defaults to the gnexus-auth account locale. + +### 4. MCP follows gnexus-handbook + +- The service is its own MCP server over **streamable HTTP** at `/mcp-protocol/` + (trailing slash significant). SSE is a legacy fallback only; stdio is not the + production transport. +- Agents authenticate with per-user `mcp_*` keys, not gnexus-auth access tokens. +- Keys are stored as SHA-256 hash plus tail hint; one active key per + (`user_id`, `consumer`); revocation is `revoked_at`, never deletion. +- The UI exposes an "MCP keys" page. Internal `/internal/keys` provisioning endpoints + are required (not published through nginx, service-to-service secret + allowlist). +- The guard is a pure ASGI class, returns a uniform `401`, and updates `last_used_at`. +- Mutating tools accept `is_user`; REST accepts `X-Actor: user`; audit records + `actor_kind`, `actor_name`, and `via`. +- Tool implementations share the service layer with REST routes, including validation + and error codes; tool errors are returned as data. + +### 5. Backups + +The database is dumped on a schedule to a **separate host**, with a documented restore +procedure and periodic restore drills. A dump that has never been restored does not +count as a backup. This follows `20-deployment/backups.md`. + +There is no Markdown/JSONL export from the database in the first version (owner +decision). The dumps are the only safety net, so retention, off-host storage, and +restore verification are mandatory. + +### 6. Existing files remain canonical until cutover + +The current repository stays the canonical source until the new backend passes its +tests and a migration has been verified. The importer is a later task and must be +repeatable. + +## Draft data model + +```text +users -- mirror of gnexus-auth principals + id, sub (unique), email, display_name, profile jsonb, locale, + created_at, updated_at, blocked_at + +user_sessions -- cookie-session pattern, if used + id, user_id, created_at, expires_at + +oauth_states -- PKCE state + +documents + id, slug (unique), title, created_at, deleted_at + +doc_versions + id, document_id, version_no, parent_version_id, content_hash, + raw text, body text, frontmatter jsonb, + author_user_id, actor_kind, actor_name, via, changeset_id, created_at + unique (document_id, version_no) + +blobs + hash pk, content text -- content-addressed deduplication + +inventory_types + name pk, schema_id + +schemas + id, name, version, body jsonb, created_at + +inventory_items + id, type, item_id, data jsonb, current_version_id, deleted_at + unique (type, item_id) among live rows + +inventory_item_versions + id, inventory_item_id, version_no, data jsonb, + author_user_id, changeset_id, created_at + +changesets + id, author_user_id, summary, reason, + status (draft | applied | rejected), created_at, applied_at, validation jsonb + +change_items + id, changeset_id, kind (doc | inventory-item), target, payload jsonb, status + +validation_runs + id, changeset_id, status, issues jsonb, created_at + +mcp_tokens + id, user_id, consumer, name, role, scopes jsonb, + token_hash (unique), token_hint, created_at, last_used_at, revoked_at + partial unique (user_id, consumer) where revoked_at is null + +user_prefs + user_id, locale + +audit_log + id, actor_user_id, actor_kind, actor_name, via, + action, entity_type, entity_id, before jsonb, after jsonb, created_at +``` + +Search is a `tsvector` index on document versions plus a trigram/substring path to +preserve the current "find a line containing the query" behavior. Relationships are +computed from `inventory_items.data` as they are today; materialized edges are an +optimization, not a v1 requirement. + +## Functional coverage + +The new system must close the current functionality before the migration. This table +is the acceptance checklist. + +| Capability | Current implementation | New implementation | +|---|---|---| +| List documents | Recursive `*.md` scan, title from first H1 or file stem, frontmatter dict | Query current document versions | +| Read document | `path` → `{path, frontmatter, body, raw}` | Lookup by slug/id; same response shape | +| Search | Case-insensitive substring, up to 5 matching lines per document | FTS plus substring/line-match path; keep response shape | +| Create/update document | Pending change → write file → validate → rollback on failure | Draft changeset → apply transaction → validate | +| Path safety | Reject escapes, non-`.md`, denied directories | Slug/route validation; no filesystem paths | +| Inventory types | `*.yml` files | `inventory_types` rows | +| Inventory read | raw YAML, parsed list, item by `id` | JSONB records; raw view is a defined serialization | +| Inventory create/update | `patch` merge or `create` append, immutable `id` | Change item applied in a transaction | +| JSON Schema validation | Draft 2020-12, per-type mapping | Same schemas stored in `schemas` | +| Unique inventory IDs | Per-file scan | Unique constraint per type among live items | +| Secret scanning | Regex over Markdown/YAML/JSON/dotenv | Same scan on every candidate version | +| Freshness | Frontmatter presence, stale by interval, missing `docs` targets | SQL queries over versions and inventory | +| Relationship graph | Nodes `/`, edges from known fields, unresolved refs | Same computation over inventory data; optional materialized edges | +| Pending changes | JSON files, `pending/applied/rejected`, apply + rollback | `changesets` + `change_items`, transactional apply | +| Git status/diff/commit | Working tree, explicit file list, local commit | Draft changesets, version diff, publish/apply changeset | +| MCP | 17 tools, 9 resources, stdio/SSE, static environment | Same domain tools over HTTP with per-user keys | +| UI | Four tabs, metrics, apply/commit forms | Same views plus history/diff, auth gate, MCP keys, i18n | +| Health | `{"status": "ok", "repo_root": ...}` | Handbook contract: no auth, cheap, `status` plus optional `checks.db` | +| Deployment | systemd user units, nginx, scripts | Postgres service, migrations, systemd, nginx | +| Tests | 38 tests, real-repo fixtures | Parameterized against DB fixtures; keep behavior contracts | + +Deliberately absent today and still absent unless separately requested: document +delete/rename, full-file inventory replacement, reject/approval workflow, generated +inventory index, visual topology, embedding search. + +## Handbook compliance gaps + +| Area | Handbook requirement | Current state | Action | +|---|---|---|---| +| Auth | gnexus-auth SSO, mirrored `sub` | None | Add PKCE client, session, webhooks | +| MCP transport | Streamable HTTP `/mcp-protocol/` | stdio/SSE | Add HTTP endpoint; keep stdio for dev/tests only | +| MCP keys | Per-user `mcp_*`, hash + hint, revoke | None | Add `mcp_tokens`, guard, UI page | +| Key provisioning | `/internal/keys`, service secret, allowlist | None | Add later, before external consumers | +| Actor | `is_user` / `X-Actor`, audit fields | None | Add to write paths and audit | +| UI | Kit, auth gate, drawer nav, `GnPageHeader` | Kit only | Add gate, nav, history views | +| i18n | en/uk/ru, account locale | English only | Add i18n module and dictionaries | +| Health | No auth, cheap, status contract | Exposes repo path | Remove topology, add DB check | +| Backups | Separate host, verified restore | Same disk, verified once | Add cron dump, off-host copy, restore drill | +| Secrets | gnexus-creds, `.env`, references only | Scanner in validation | Keep scanner; align docs | +| Monitoring | hard-panel + Synapse alerts | None | Add when deployed | +| Notifications | Synapse envelopes | None | Add only if the service emits alerts | +| Docs | Service page in gnexus-book | Page exists | Keep current | +| Git commits | No co-authorship lines | No agent commits yet | Follow `10-platform/git.md` | + +## API and MCP compatibility + +Read contracts can be kept almost unchanged. Write contracts need an explicit +decision because the working-tree model disappears: + +- `propose_*` → create a draft changeset/change item; +- `apply_pending_change` → apply the changeset transactionally; +- `git_status` → list draft changesets and pending items; +- `git_diff` → diff a draft against the current version; +- `commit_changes` → publish/apply a changeset (or become a deprecated alias). + +The recommendation is to introduce the new names and keep the old tools as aliases for +one transition period, so existing agents do not break. The alternative is a clean +rename with updated MCP instructions and tests. + +## Migration plan + +Phases, acceptance criteria, dependencies, and decision gates are in +[../00-overview/postgres-migration-roadmap.md](../00-overview/postgres-migration-roadmap.md). + +1. Accept this ADR and resolve the open questions below. +2. Add PostgreSQL, migrations, and a shared service layer; keep the file repositories + as a development/test backend behind the same interfaces. +3. Implement versioned documents and inventory, changesets, validation, audit. +4. Implement SSO, user mirroring, MCP keys, provisioning, and actor tracking. +5. Update the UI: auth gate, navigation, history/diff, MCP keys page, i18n. +6. Write the importer: current Markdown/YAML → documents/inventory; optionally replay + Git history as changesets. +7. Dual-run and compare read results; fix discrepancies. +8. Cut over writes, freeze the file write path, document backups and restore. +9. Decommission the Git write path and archive the original repository. + +## Risks + +- The database becomes a single point of failure; dumps without off-host copies and + restore drills are not sufficient. +- Versioning scope can creep into a VCS rewrite; branches and merges stay out of v1. +- Migration can silently change data (YAML formatting, frontmatter types, references). +- Auth and MCP key handling add security-critical code that must not be improvised. +- Losing filesystem access removes grep, IDE search, and ad-hoc scripting workflows. + +## Open questions + +1. Import the 34 Git commits as history, or import only the current state? +2. Keep old MCP tool names as aliases, or rename and update consumers? +3. May agents publish changesets directly, or do access/security/backup changes require + owner review? +4. Document identity: keep mutable `path` as the public key, or switch to UUID + slug + with redirects? +5. What should "raw inventory" return once comments and formatting no longer exist? +6. Will the service stay LAN-only, or get a `*.gnexus.space` subdomain and public MCP + endpoint? +7. Are delete and rename in scope for the first database version? + +## References + +- [gnexus-handbook README](https://git.gnexus.space/root/gnexus-handbook/raw/master/README.md) +- [Auth](https://git.gnexus.space/root/gnexus-handbook/raw/master/10-platform/auth.md) +- [MCP](https://git.gnexus.space/root/gnexus-handbook/raw/master/10-platform/mcp.md) +- [Key provisioning](https://git.gnexus.space/root/gnexus-handbook/raw/master/10-platform/key-provisioning.md) +- [Secrets](https://git.gnexus.space/root/gnexus-handbook/raw/master/10-platform/secrets.md) +- [UI](https://git.gnexus.space/root/gnexus-handbook/raw/master/10-platform/ui.md) +- [i18n](https://git.gnexus.space/root/gnexus-handbook/raw/master/10-platform/i18n.md) +- [Health](https://git.gnexus.space/root/gnexus-handbook/raw/master/10-platform/health.md) +- [Git](https://git.gnexus.space/root/gnexus-handbook/raw/master/10-platform/git.md) +- [Backups](https://git.gnexus.space/root/gnexus-handbook/raw/master/20-deployment/backups.md) +- Current implementation: `server/app/main.py`, `server/app/mcp_server.py`, + `server/app/pending_changes.py`, `server/app/validation.py`, `server/app/freshness.py`, + `server/app/relationships.py`, `ui/src/main.js` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f313263 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,157 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## What this repository is + +Gnexus Book is a Git-backed personal infrastructure knowledge base plus the tooling that operates on it: a FastAPI backend, an MCP server for AI agents, and a Vue UI. The repository root **is** the data store — Markdown docs (numbered directories), YAML inventory in `40-inventory/`, JSON Schemas in `schemas/`, and an audit/pending-change area in `90-maintenance/pending-changes/`. + +Two consumers must keep working: + +- humans reading Markdown/YAML from Git; +- AI agents calling the MCP tools, which must not bypass validation or Git safety checks. + +## Platform handbook (mandatory) + +Rules for the whole Gnexus ecosystem live in `~/Projects/gnexus-handbook` (https://git.gnexus.space/root/gnexus-handbook), not here. Before changing authentication, MCP/keys, UI, secrets, backups, health, deployment, or documentation policy, read the handbook README and the relevant section. Link to the handbook instead of copying its rules. + +Notable for this repository: + +- Commit messages follow `10-platform/git.md`; it overrides Claude Code's default attribution (no co-authorship lines). +- This file-backed prototype predates several handbook conventions (SSO, per-user MCP keys, streamable-HTTP MCP, off-host verified backups). `50-decisions/ADR-0002-postgres-storage-and-versioning.md` tracks the gaps and the planned move to PostgreSQL. + +## Common commands + +### Server + +```bash +cd server +python3 -m venv .venv && . .venv/bin/activate # or: uv venv --python 3.11 +pip install -e ".[dev]" + +# Run all tests +.venv/bin/python -m pytest -q + +# Run a single test +.venv/bin/python -m pytest tests/test_api.py::test_health_endpoint -q + +# Dev API (README uses 8080; the Vite proxy expects 3005) +.venv/bin/python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 3005 + +# MCP server (stdio by default) +.venv/bin/python -m app.mcp_server +``` + +MCP environment: `GNEXUS_BOOK_REPO_ROOT` (defaults to the repo root derived from `server/app/config.py`) and `GNEXUS_BOOK_MCP_TRANSPORT` (`stdio` | `sse` | `streamable-http`). Production agents use streamable HTTP at `/mcp-protocol/` with a personal `mcp_*` key: + +```bash +cd server +GNEXUS_BOOK_MCP_HOST=0.0.0.0 GNEXUS_BOOK_MCP_PORT=8001 .venv/bin/python -m app.mcp_http +``` + +Keys are managed through `/mcp-keys` (session) and `/internal/keys` (service secret, blocked by nginx); `mcp_tokens` stores only a SHA-256 hash and a tail hint, never plaintext. Behind nginx, set `GNEXUS_BOOK_MCP_ALLOWED_HOSTS`/`_ORIGINS` to the public hostname and origin or FastMCP returns `421`. + +### PostgreSQL read backend (Phase 1) + +```bash +# From the repo root: local dev cluster on 127.0.0.1:5433 +./scripts/dev-db.sh start + +cd server +export GNEXUS_BOOK_DATABASE_URL="$(../scripts/dev-db.sh url)" +.venv/bin/alembic upgrade head +.venv/bin/python -m app.storage.cli import --replace +.venv/bin/python -m app.storage.cli parity # exits 1 on a file/DB difference +.venv/bin/python -m app.storage.cli migrate --replace --manifest /tmp/report.json +.venv/bin/python -m app.storage.cli assign-owner --user-json /tmp/owner.json +.venv/bin/python -m app.storage.cli ownership + +# Rehearsed/real cutover and rollback verification +../scripts/cutover-db.sh --replace +../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 + +# Operations +../scripts/backup-db.sh +../scripts/restore-drill.sh +GNEXUS_BOOK_HEALTH_URL=http://127.0.0.1:3005/health ../scripts/healthcheck.sh +``` + +`gnexus-book-backup.timer` runs the off-host dump daily; the restore-drill timer is +installed but disabled until a manual drill passes. Synapse alerts use +`SYNAPSE_URL`/`SYNAPSE_API_KEY`. See `30-runbooks/postgres-operations.md`. + +`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`. + +### UI + +```bash +cd ui +npm install +npm run dev # port 3006, proxies /api -> http://127.0.0.1:3005 +npm run build # outputs dist/ +``` + +`gnexus-ui-kit` is a local `file:../../gnexus-ui-kit` dependency (sibling of the repo root), built from `https://git.gnexus.space/root/gnexus-ui-kit`. `ui/vite.config.js` dedupes Vue, resolves Vue's ESM bundler build, and serves the kit's fonts from `node_modules/gnexus-ui-kit/dist/assets/fonts`. + +### Deploy (VPS) + +```bash +./scripts/install.sh # uv + Python 3.11, nvm/Node, clone/build ui-kit, venv, UI build, systemd user units +./scripts/deploy.sh # git pull, rebuild kit + UI, sync UI dist to /var/www/gnexus-book, restart backend, reload nginx +``` + +`systemd/*.service` hardcodes `/home/ubuntu/gnexus-book` paths — adjust them if the deployment user differs. Nginx (`nginx/gnexus-book.conf`) serves `ui/dist` on port 80, proxies `/api/` to the backend on 8000 and `/mcp/` to the MCP server on 8001. + +## Backend architecture + +`server/app/main.py` is the FastAPI composition root. Every route depends on a repository class constructed from `app/config.py:Settings`; `Settings()` defaults `repo_root` to `server/../..`, and tests pass `Settings(tmp_path)` to build isolated fake repositories. + +The domain layer is split by responsibility: + +- **`docs_repository.py` + `markdown.py`** — list/read/search Markdown under the repo root, skipping `.git`, `.venv`, `node_modules`, etc. The frontmatter parser is deliberately simple: only a flat `key: value` block between the first `---` fences is parsed. Nested YAML or typed values in frontmatter are not supported. +- **`inventory.py`** — reads `40-inventory/.yml`; each file is a YAML list and items are looked up by `id`. +- **`relationships.py`** — builds a graph whose node ids are `/` and whose edges come from known cross-record fields (`host`, `hypervisor_host`, `runs_services`, `points_to`, `destination`, `related_*`, etc.). References to unknown ids are returned in `unresolved_references` rather than failing the request. +- **`freshness.py`** — checks required frontmatter fields and staleness (`last_reviewed` + `review_interval`, e.g. `90d`), and reports inventory `docs:` targets that do not exist. +- **`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, personal MCP key management (`mcp_keys.py`, `mcp_routes.py`), the MCP bearer guard (`mcp_guard.py`), 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 + +`server/app/mcp_server.py` exposes the same domain functions (not HTTP) as 17 MCP tools plus `gnexus-book://*` resources. The long tool descriptions and `MCP_INSTRUCTIONS`/`AGENT_USAGE_GUIDE` strings are covered by tests in `tests/test_mcp_server.py`; update the tests when changing that guidance. `GET /mcp/info` reflects the registered tools and instructions. + +The MCP guidance tells external agents never to edit repository files directly and to use propose → apply → validate → commit. That rule is for MCP clients; normal development in this checkout edits files directly, but still run validation before committing. + +## Documentation and data conventions + +- Every knowledge document needs frontmatter with `owner`, `status`, `last_reviewed`, `review_interval`, `confidence`, `source_of_truth`. Validation skips `README.md` and `server/**`; other Markdown (including `ui/README.md`) is checked. +- Inventory files are YAML sequences beginning with `---`. Item ids must be unique within a file. Adding a new inventory type requires both `40-inventory/.yml` and an entry in `validation.SCHEMA_BY_INVENTORY`. +- Never store raw passwords, tokens, private keys, recovery codes, or session cookies. Describe where a secret lives using reference values such as `unknown`, `redacted`, `password manager`, `vault`, or `ref:...`. +- Some inventory schemas require a `docs` link. When creating such an item, create the Markdown document first (the MCP inventory-creation guidance codifies this). +- Update `last_reviewed` only after the information was actually verified. +- `60-generated/inventory-index.md` is still a placeholder; no generator exists yet. + +## UI architecture + +The frontend is a single Vue 3 app in `ui/src/main.js` (no router). It uses a drawer shell with pages: docs (search, history, diff, proposals), inventory (JSON/raw), changes (apply), status, MCP keys, and settings. `ui/src/i18n/` holds flat en/uk/ru dictionaries; navigation labels must be `computed` because `t()` reads the reactive locale. The auth gate calls `/api/me`; sign-in redirects through `/api/auth/login`, and gnexus-auth returns to `/auth/callback` (Vite proxies `/auth` and `/webhooks`, nginx proxies them in production). All data goes through `/api`. Avoid copying UI-kit styles locally; prefer upstream changes in the kit. + +## Testing notes + +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, `tests/test_auth.py` covers login, sessions, `/me`, the route guard and signed webhooks with mocked gnexus-auth HTTP calls, `tests/test_mcp_keys.py` covers internal provisioning, the user key API, the MCP bearer guard, rate limits, actor selection and key revocation on user block, 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/README.md b/README.md index 86da251..55f93e9 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ - [Project implementation notes](00-overview/project-implementation-notes.md) - [MVP implementation plan](00-overview/mvp-implementation-plan.md) +- [PostgreSQL migration roadmap](00-overview/postgres-migration-roadmap.md) +- [ADR-0002: PostgreSQL storage and versioning](50-decisions/ADR-0002-postgres-storage-and-versioning.md) ## Foundation @@ -29,7 +31,8 @@ - **Backend** (FastAPI): `systemctl --user status gnexus-book-backend.service` — listens on `0.0.0.0:8000` - **Frontend** (nginx): served on port `80` from `/var/www/gnexus-book` -- **MCP Server** (SSE): `systemctl --user status gnexus-book-mcp.service` — listens on `0.0.0.0:8001`, endpoint `/sse` +- **MCP Server** (streamable HTTP): `systemctl --user status gnexus-book-mcp.service` — listens on `0.0.0.0:8001`, endpoint `/mcp-protocol/` +- **Database**: PostgreSQL; daily off-host backups run through `gnexus-book-backup.timer` ([operations](30-runbooks/postgres-operations.md)) ### Update / redeploy diff --git a/nginx/gnexus-book.conf b/nginx/gnexus-book.conf index a263ee8..74a0876 100644 --- a/nginx/gnexus-book.conf +++ b/nginx/gnexus-book.conf @@ -9,6 +9,12 @@ try_files $uri $uri/ /index.html; } + # Service-to-service key provisioning must never be reachable from outside. + location = /internal { return 404; } + location /internal/ { return 404; } + location = /api/internal { return 404; } + location /api/internal/ { return 404; } + location /api/ { proxy_pass http://127.0.0.1:8000/; proxy_http_version 1.1; @@ -18,6 +24,25 @@ proxy_set_header X-Forwarded-Proto $scheme; } + # gnexus-auth redirects the browser to this service, not through /api/. + location /auth/ { + proxy_pass http://127.0.0.1:8000; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + + location /webhooks/gnexus-auth { + proxy_pass http://127.0.0.1:8000; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + location /api-docs { proxy_pass http://127.0.0.1:8000/api-docs; proxy_http_version 1.1; @@ -36,8 +61,30 @@ proxy_set_header X-Forwarded-Proto $scheme; } + location /mcp-protocol/ { + proxy_pass http://127.0.0.1:8001; + proxy_http_version 1.1; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_buffering off; + proxy_cache off; + proxy_read_timeout 86400; + } + + location = /mcp-protocol { + return 308 /mcp-protocol/; + } + + location = /mcp { + return 308 /mcp-protocol/; + } + + # Historical alias kept for clients that used /mcp/. location /mcp/ { - proxy_pass http://127.0.0.1:8001/; + rewrite ^/mcp/(.*)$ /mcp-protocol/$1 break; + proxy_pass http://127.0.0.1:8001; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; diff --git a/scripts/backup-db.sh b/scripts/backup-db.sh new file mode 100755 index 0000000..7323928 --- /dev/null +++ b/scripts/backup-db.sh @@ -0,0 +1,50 @@ +#!/bin/bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" + +on_exit() { + status=$? + trap - EXIT + if [ "$status" -ne 0 ] && [ -n "${SYNAPSE_URL:-}" ] && [ -n "${SYNAPSE_API_KEY:-}" ]; then + "$SCRIPT_DIR/notify-synapse.sh" \ + "Gnexus Book backup failed" \ + "backup.failed" \ + "backup-db.sh exited with $status on $(hostname)" \ + "high" >/dev/null 2>&1 || true + fi + exit "$status" +} +trap on_exit EXIT + +DB_URL="${GNEXUS_BOOK_DATABASE_URL:-}" +if [ -z "$DB_URL" ]; then + echo "GNEXUS_BOOK_DATABASE_URL is required" >&2 + exit 2 +fi + +DEST="${GNEXUS_BOOK_BACKUP_DIR:-$HOME/NetTera8/service/backups/gnexus-book/db}" +KEEP="${GNEXUS_BOOK_BACKUP_KEEP:-14}" + +if [ -z "${GNEXUS_BOOK_BACKUP_DIR:-}" ] && ! mountpoint -q "$HOME/NetTera8"; then + echo "Off-host mount $HOME/NetTera8 is not available; set GNEXUS_BOOK_BACKUP_DIR explicitly" >&2 + exit 2 +fi + +mkdir -p "$DEST" +STAMP="$(date +%Y-%m-%d_%H%M%S)" +OUT="$DEST/gnexus_book_$STAMP.dump" +PG_URL="${DB_URL/postgresql+psycopg/postgresql}" + +pg_dump --format=custom --no-owner --no-acl --file "$OUT" "$PG_URL" +pg_restore --list "$OUT" > "$OUT.list" +sha256sum "$OUT" > "$OUT.sha256" + +mapfile -t dumps < <(ls -1t "$DEST"/gnexus_book_*.dump 2>/dev/null || true) +if [ "${#dumps[@]}" -gt "$KEEP" ]; then + for old in "${dumps[@]:$KEEP}"; do + rm -f "$old" "$old.list" "$old.sha256" + done +fi + +echo "$OUT" diff --git a/scripts/cutover-db.sh b/scripts/cutover-db.sh new file mode 100755 index 0000000..1082056 --- /dev/null +++ b/scripts/cutover-db.sh @@ -0,0 +1,51 @@ +#!/bin/bash +set -euo pipefail + +cd "$(dirname "$0")/.." +REPO_ROOT="$(pwd)" +SERVER_DIR="$REPO_ROOT/server" + +if [ -z "${GNEXUS_BOOK_DATABASE_URL:-}" ]; then + echo "GNEXUS_BOOK_DATABASE_URL is required" >&2 + exit 2 +fi +export GNEXUS_BOOK_DATABASE_URL + +REPLACE_FLAG="${1:-}" +if [ -n "$REPLACE_FLAG" ] && [ "$REPLACE_FLAG" != "--replace" ]; then + echo "Usage: $0 [--replace]" >&2 + echo " --replace clears the target database before importing" >&2 + exit 2 +fi + +REPORT="${GNEXUS_BOOK_MIGRATION_REPORT:-$HOME/backup/gnexus-book/migration-report-$(date +%Y-%m-%d_%H%M%S).json}" + +cd "$SERVER_DIR" +.venv/bin/alembic upgrade head + +ARGS=(.venv/bin/python -m app.storage.cli migrate --manifest "$REPORT") +if [ "$REPLACE_FLAG" = "--replace" ]; then + ARGS+=(--replace) +fi + +"${ARGS[@]}" + +if [ -n "${GNEXUS_BOOK_OWNER_JSON:-}" ]; then + echo "==> Assigning current data to the owner from $GNEXUS_BOOK_OWNER_JSON" + (cd "$SERVER_DIR" && .venv/bin/python -m app.storage.cli assign-owner \ + --user-json "$GNEXUS_BOOK_OWNER_JSON") +fi + +"$REPO_ROOT/scripts/backup-db.sh" + +echo +echo "Migration verified. Report: $REPORT" +echo "Database dumps are on the configured off-host backup target." +echo +echo "To activate database mode, set on the service:" +echo " GNEXUS_BOOK_STORAGE_BACKEND=db" +echo " GNEXUS_BOOK_DATABASE_URL=$GNEXUS_BOOK_DATABASE_URL" +echo "and restart gnexus-book-backend and gnexus-book-mcp." +echo +echo "Rollback: set GNEXUS_BOOK_STORAGE_BACKEND=file and restart." +echo "The Git checkout is untouched by this script." diff --git a/scripts/deploy.sh b/scripts/deploy.sh index abdd658..498cc02 100755 --- a/scripts/deploy.sh +++ b/scripts/deploy.sh @@ -9,6 +9,13 @@ # shellcheck source=/dev/null [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" +if [ -f "$REPO_ROOT/server/.env" ]; then + set -a + # shellcheck disable=SC1091 + . "$REPO_ROOT/server/.env" + set +a +fi + echo "==> Updating source..." git pull @@ -27,16 +34,32 @@ cd "$REPO_ROOT/server" uv pip install -e ".[dev]" +if [ "${GNEXUS_BOOK_STORAGE_BACKEND:-file}" = "db" ]; then + if [ -z "${GNEXUS_BOOK_DATABASE_URL:-}" ]; then + echo "GNEXUS_BOOK_DATABASE_URL is required for the db backend" >&2 + exit 2 + fi + echo "==> Applying database migrations..." + GNEXUS_BOOK_DATABASE_URL="$GNEXUS_BOOK_DATABASE_URL" .venv/bin/alembic upgrade head +fi + echo "==> Syncing dist to /var/www..." sudo cp -r "$REPO_ROOT/ui/dist/"* /var/www/gnexus-book/ sudo chown -R www-data:www-data /var/www/gnexus-book -echo "==> Restarting services..." +echo "==> Refreshing systemd units..." +cp "$REPO_ROOT"/systemd/*.service "$HOME/.config/systemd/user/" 2>/dev/null || true +cp "$REPO_ROOT"/systemd/*.timer "$HOME/.config/systemd/user/" 2>/dev/null || true systemctl --user daemon-reload + +echo "==> Restarting services..." systemctl --user restart gnexus-book-backend.service +systemctl --user restart gnexus-book-mcp.service +systemctl --user restart gnexus-book-frontend.service || true echo "==> Reloading nginx..." sudo nginx -t && sudo systemctl reload nginx echo "==> Deploy complete." systemctl --user status gnexus-book-backend.service --no-pager +systemctl --user status gnexus-book-mcp.service --no-pager diff --git a/scripts/dev-db.sh b/scripts/dev-db.sh new file mode 100755 index 0000000..d5f8d4c --- /dev/null +++ b/scripts/dev-db.sh @@ -0,0 +1,70 @@ +#!/bin/bash +set -euo pipefail + +BASE_DIR="${GNEXUS_BOOK_PGDATA_ROOT:-$HOME/.local/share/gnexus-book}" +PGDATA="$BASE_DIR/pgdata" +RUNDIR="$BASE_DIR/run" +LOG="$BASE_DIR/postgres.log" +PORT="${GNEXUS_BOOK_PGPORT:-5433}" +DB_USER="${GNEXUS_BOOK_PGUSER:-$(id -un)}" + +database_url() { + printf 'postgresql+psycopg://%s@127.0.0.1:%s/gnexus_book\n' "$DB_USER" "$PORT" +} + +init_cluster() { + mkdir -p "$BASE_DIR" "$RUNDIR" + if [ ! -s "$PGDATA/PG_VERSION" ]; then + initdb -D "$PGDATA" -U "$DB_USER" --auth-local=trust --auth-host=trust >/dev/null + fi +} + +start_cluster() { + init_cluster + if pg_ctl -D "$PGDATA" status >/dev/null 2>&1; then + echo "PostgreSQL already running on port $PORT" + else + pg_ctl -D "$PGDATA" -l "$LOG" \ + -o "-p $PORT -k $RUNDIR -c listen_addresses=127.0.0.1" start >/dev/null + for _ in $(seq 1 40); do + pg_isready -h 127.0.0.1 -p "$PORT" -U "$DB_USER" >/dev/null 2>&1 && break + sleep 0.25 + done + fi + + for db in gnexus_book gnexus_book_test; do + if ! psql -h 127.0.0.1 -p "$PORT" -U "$DB_USER" -d postgres -Atc \ + "select 1 from pg_database where datname='$db'" | grep -q 1; then + createdb -h 127.0.0.1 -p "$PORT" -U "$DB_USER" "$db" + fi + done + + echo "PostgreSQL is ready: $(database_url)" +} + +stop_cluster() { + pg_ctl -D "$PGDATA" stop -m fast +} + +case "${1:-status}" in + init) + init_cluster + echo "Initialized $PGDATA" + ;; + start) + start_cluster + ;; + stop) + stop_cluster + ;; + status) + pg_ctl -D "$PGDATA" status + ;; + url) + database_url + ;; + *) + echo "Usage: $0 {init|start|stop|status|url}" >&2 + exit 2 + ;; +esac diff --git a/scripts/dev-mcp.sh b/scripts/dev-mcp.sh new file mode 100755 index 0000000..70d7e3a --- /dev/null +++ b/scripts/dev-mcp.sh @@ -0,0 +1,15 @@ +#!/bin/bash +set -euo pipefail + +cd "$(dirname "$0")/../server" +if [ ! -f .env ]; then + echo "server/.env is required; copy server/.env.example and fill it in" >&2 + exit 2 +fi + +set -a +# shellcheck disable=SC1091 +. ./.env +set +a + +exec .venv/bin/python -m app.mcp_http "$@" diff --git a/scripts/dev-server.sh b/scripts/dev-server.sh new file mode 100755 index 0000000..38284ec --- /dev/null +++ b/scripts/dev-server.sh @@ -0,0 +1,15 @@ +#!/bin/bash +set -euo pipefail + +cd "$(dirname "$0")/../server" +if [ ! -f .env ]; then + echo "server/.env is required; copy server/.env.example and fill it in" >&2 + exit 2 +fi + +set -a +# shellcheck disable=SC1091 +. ./.env +set +a + +exec .venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 3005 "$@" diff --git a/scripts/healthcheck.sh b/scripts/healthcheck.sh new file mode 100755 index 0000000..ba419ae --- /dev/null +++ b/scripts/healthcheck.sh @@ -0,0 +1,43 @@ +#!/bin/bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +URL="${GNEXUS_BOOK_HEALTH_URL:-http://127.0.0.1:8000/health}" + +notify() { + if [ -n "${SYNAPSE_URL:-}" ] && [ -n "${SYNAPSE_API_KEY:-}" ]; then + "$SCRIPT_DIR/notify-synapse.sh" \ + "Gnexus Book health check failed" \ + "health.failed" \ + "$1" \ + "high" >/dev/null 2>&1 || true + fi +} + +if ! RESPONSE="$(curl -fsS --max-time 5 "$URL")"; then + MESSAGE="Health request failed: $URL on $(hostname)" + echo "$MESSAGE" >&2 + notify "$MESSAGE" + exit 1 +fi + +if ! python3 -c ' +import json +import sys + +ok = {"ok", "healthy", "pass", "passing", "up"} +data = json.load(sys.stdin) +status = str(data.get("status", "")).lower() +if status not in ok: + sys.exit(1) +db = (data.get("checks") or {}).get("db") +if db and str(db.get("status", "")).lower() not in ok: + sys.exit(1) +' <<<"$RESPONSE"; then + MESSAGE="Health response is not ok: $RESPONSE" + echo "$MESSAGE" >&2 + notify "$MESSAGE" + exit 1 +fi + +echo "ok" diff --git a/scripts/install.sh b/scripts/install.sh index 409ca39..8292e26 100755 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -42,18 +42,28 @@ echo "==> Installing systemd user units..." mkdir -p "$HOME/.config/systemd/user" -cp "$REPO_ROOT/systemd/gnexus-book-backend.service" "$HOME/.config/systemd/user/" -cp "$REPO_ROOT/systemd/gnexus-book-frontend.service" "$HOME/.config/systemd/user/" +cp "$REPO_ROOT"/systemd/*.service "$HOME/.config/systemd/user/" +cp "$REPO_ROOT"/systemd/*.timer "$HOME/.config/systemd/user/" + +if [ ! -f "$REPO_ROOT/server/.env" ]; then + echo "WARNING: server/.env is missing; backend, MCP and backups may fail until it is configured." >&2 +fi echo "==> Enabling lingering for boot autostart..." loginctl enable-linger "$(whoami)" systemctl --user daemon-reload -systemctl --user enable gnexus-book-backend.service gnexus-book-frontend.service +systemctl --user enable gnexus-book-backend.service gnexus-book-frontend.service \ + gnexus-book-mcp.service gnexus-book-backup.timer systemctl --user start gnexus-book-backend.service sleep 3 -systemctl --user start gnexus-book-frontend.service +systemctl --user start gnexus-book-frontend.service gnexus-book-mcp.service gnexus-book-backup.timer + +echo "==> Restore-drill timer is installed but not enabled; enable it after a manual drill:" +echo " systemctl --user enable --now gnexus-book-restore-drill.timer" echo "==> Done. Services:" systemctl --user status gnexus-book-backend.service --no-pager systemctl --user status gnexus-book-frontend.service --no-pager +systemctl --user status gnexus-book-mcp.service --no-pager +systemctl --user status gnexus-book-backup.timer --no-pager diff --git a/scripts/notify-synapse.sh b/scripts/notify-synapse.sh new file mode 100755 index 0000000..de1b79a --- /dev/null +++ b/scripts/notify-synapse.sh @@ -0,0 +1,40 @@ +#!/bin/bash +set -euo pipefail + +: "${SYNAPSE_URL:?SYNAPSE_URL is required}" +: "${SYNAPSE_API_KEY:?SYNAPSE_API_KEY is required}" + +SOURCE="${SYNAPSE_DEFAULT_SOURCE:-gnexus-book}" +SUBJECT="${1:-Gnexus Book alert}" +ACTION="${2:-alert}" +TEXT="${3:-}" +PRIORITY="${4:-high}" +ENDPOINT="${SYNAPSE_URL%/}/api/v1/events" + +BODY="$(python3 - "$SOURCE" "$SUBJECT" "$ACTION" "$TEXT" "$PRIORITY" <<'PY' +import json +import sys + +source, subject, action, text, priority = sys.argv[1:6] +print( + json.dumps( + { + "source": source, + "subject": subject, + "action": action, + "priority": priority, + "payload": {"service": "gnexus-book", "text": text}, + "dedup_key": f"gnexus-book:{action}:{subject}", + "ttl_seconds": 3600, + }, + ensure_ascii=False, + ) +) +PY +)" + +curl -fsS --max-time 10 \ + -X POST "$ENDPOINT" \ + -H "Authorization: Bearer $SYNAPSE_API_KEY" \ + -H "Content-Type: application/json" \ + --data-binary "$BODY" >/dev/null diff --git a/scripts/restore-db.sh b/scripts/restore-db.sh new file mode 100755 index 0000000..cfafa76 --- /dev/null +++ b/scripts/restore-db.sh @@ -0,0 +1,25 @@ +#!/bin/bash +set -euo pipefail + +if [ $# -ne 2 ]; then + echo "Usage: $0 DUMP TARGET_DATABASE_URL" >&2 + echo "Set GNEXUS_BOOK_RESTORE_YES=1 to confirm; target data will be replaced." >&2 + exit 2 +fi + +DUMP="$1" +TARGET_URL="$2" + +if [ "${GNEXUS_BOOK_RESTORE_YES:-}" != "1" ]; then + echo "Refusing to restore without GNEXUS_BOOK_RESTORE_YES=1" >&2 + exit 2 +fi + +if [ ! -f "$DUMP" ]; then + echo "Dump not found: $DUMP" >&2 + exit 2 +fi + +TARGET_PG="${TARGET_URL/postgresql+psycopg/postgresql}" +pg_restore --clean --if-exists --no-owner --no-acl --dbname "$TARGET_PG" "$DUMP" +echo "Restored $DUMP" diff --git a/scripts/restore-drill.sh b/scripts/restore-drill.sh new file mode 100755 index 0000000..30b9f2d --- /dev/null +++ b/scripts/restore-drill.sh @@ -0,0 +1,93 @@ +#!/bin/bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +DB_URL="${GNEXUS_BOOK_DATABASE_URL:-}" +if [ -z "$DB_URL" ]; then + echo "GNEXUS_BOOK_DATABASE_URL is required" >&2 + exit 2 +fi + +DEST="${GNEXUS_BOOK_BACKUP_DIR:-$HOME/NetTera8/service/backups/gnexus-book/db}" +DUMP="${1:-}" +if [ -z "$DUMP" ]; then + DUMP="$(ls -1t "$DEST"/gnexus_book_*.dump 2>/dev/null | head -1 || true)" +fi +if [ -z "$DUMP" ] || [ ! -f "$DUMP" ]; then + echo "Dump not found; pass a dump path or set GNEXUS_BOOK_BACKUP_DIR" >&2 + exit 2 +fi + +read -r MAINT_PG_URL TEMP_PG_URL TEMP_APP_URL TEMP_DB <<<"$( + DB_URL="$DB_URL" "$REPO_ROOT/server/.venv/bin/python" - <<'PY' +import os +from datetime import datetime +from sqlalchemy.engine.url import make_url + +url = make_url(os.environ["DB_URL"]) +name = "gnexus_book_restore_" + datetime.now().strftime("%Y%m%d_%H%M%S") + "_" + str(os.getpid()) +maintenance = url.set(database="postgres") +temp = url.set(database=name) + + +def pg(value): + return value.render_as_string(hide_password=False).replace( + "postgresql+psycopg", "postgresql" + ) + + +print(pg(maintenance), pg(temp), temp.render_as_string(hide_password=False), name) +PY +)" + +CREATED=0 +cleanup() { + status=$? + trap - EXIT + if [ "$CREATED" = "1" ]; then + psql "$MAINT_PG_URL" -v ON_ERROR_STOP=1 \ + -c "DROP DATABASE IF EXISTS \"$TEMP_DB\" WITH (FORCE)" >/dev/null 2>&1 || true + fi + if [ "$status" -ne 0 ] && [ -n "${SYNAPSE_URL:-}" ] && [ -n "${SYNAPSE_API_KEY:-}" ]; then + "$SCRIPT_DIR/notify-synapse.sh" \ + "Gnexus Book restore drill failed" \ + "restore.failed" \ + "restore-drill.sh exited with $status for $(basename "$DUMP") on $(hostname)" \ + "high" >/dev/null 2>&1 || true + fi + exit "$status" +} +trap cleanup EXIT + +pg_restore --list "$DUMP" >/dev/null +psql "$MAINT_PG_URL" -v ON_ERROR_STOP=1 -c "CREATE DATABASE \"$TEMP_DB\"" >/dev/null +CREATED=1 +pg_restore --no-owner --no-acl --dbname "$TEMP_PG_URL" "$DUMP" + +cd "$REPO_ROOT/server" +GNEXUS_BOOK_STORAGE_BACKEND=db \ +GNEXUS_BOOK_DATABASE_URL="$TEMP_APP_URL" \ +.venv/bin/python - <<'PY' +import os +import sys + +from app.storage.db import Database +from app.storage.importer import database_counts +from app.storage.validation import validate_database + +database = Database(os.environ["GNEXUS_BOOK_DATABASE_URL"]) +counts = database_counts(database) +validation = validate_database(database) +print( + "documents={documents} inventory_items={inventory_items} validation={validation}".format( + documents=counts["documents"], + inventory_items=counts["inventory_items"], + validation=validation["status"], + ) +) +if counts["documents"] == 0 or validation["status"] != "ok": + sys.exit(1) +PY + +echo "restore drill ok: $(basename "$DUMP")" diff --git a/scripts/rollback-cutover.sh b/scripts/rollback-cutover.sh new file mode 100755 index 0000000..8cf1c2e --- /dev/null +++ b/scripts/rollback-cutover.sh @@ -0,0 +1,26 @@ +#!/bin/bash +set -euo pipefail + +cd "$(dirname "$0")/.." +SERVER_DIR="$(pwd)/server" + +cd "$SERVER_DIR" +GNEXUS_BOOK_STORAGE_BACKEND=file .venv/bin/python - <<'PY' +from app.config import Settings +from app.docs_repository import DocsRepository +from app.validation import validate_repository + +settings = Settings(storage_backend="file") +report = validate_repository(settings) +documents = DocsRepository(settings).list_docs() +print(f"file validation: {report['status']} ({report['issue_count']} issues)") +print(f"documents readable: {len(documents)}") +raise SystemExit(0 if report["status"] == "ok" else 1) +PY + +echo +echo "The file backend is readable and validated." +echo "Set GNEXUS_BOOK_STORAGE_BACKEND=file on the service and restart" +echo "gnexus-book-backend and gnexus-book-mcp to roll back." +echo "If the database itself must be restored, use scripts/restore-db.sh" +echo "with the pre-cutover dump and GNEXUS_BOOK_RESTORE_YES=1." diff --git a/server/.env.example b/server/.env.example new file mode 100644 index 0000000..9cb6c6c --- /dev/null +++ b/server/.env.example @@ -0,0 +1,47 @@ +# Storage backend: file (default) or db. +# The systemd units load this file via EnvironmentFile; switch to db after cutover. +GNEXUS_BOOK_STORAGE_BACKEND=file +# PostgreSQL URL used when the backend is db +GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book +# Repository root for the file backend and the importer +# GNEXUS_BOOK_REPO_ROOT=/path/to/gnexus-book +# MCP transport for development: stdio, sse, or streamable-http +# GNEXUS_BOOK_MCP_TRANSPORT=stdio +# GNEXUS_BOOK_MCP_HOST=0.0.0.0 +# GNEXUS_BOOK_MCP_PORT=8001 +# Break-glass only; never a fallback for personal keys +# GNEXUS_BOOK_MCP_TOKEN= +# GNEXUS_BOOK_MCP_KEY_RATE_LIMIT=30 +# GNEXUS_BOOK_MCP_REQUEST_RATE_LIMIT=300 +# Comma-separated Host values accepted by FastMCP. Add the public hostname +# when the MCP endpoint is served behind nginx (e.g. book.gnexus.space). +# GNEXUS_BOOK_MCP_ALLOWED_HOSTS=127.0.0.1:*,localhost:*,[::1]:*,book.gnexus.space +# Browser-based MCP clients also need their public HTTPS origin. +# GNEXUS_BOOK_MCP_ALLOWED_ORIGINS=http://127.0.0.1:*,http://localhost:*,http://[::1]:*,https://book.gnexus.space +# Internal key-provisioning API (not exposed through nginx) +# GNEXUS_BOOK_INTERNAL_KEY_SECRET= +# GNEXUS_BOOK_INTERNAL_ALLOWLIST=127.0.0.1,::1 +# GNEXUS_BOOK_INTERNAL_RATE_LIMIT=60 + +# Owner JSON used by cutover-db.sh to assign imported data to the first admin. +# GNEXUS_BOOK_OWNER_JSON=/path/to/owner.json + +# Operations: off-host backups, health probes and Synapse alerts. +# GNEXUS_BOOK_BACKUP_DIR=/mnt/backups/gnexus-book/db +# GNEXUS_BOOK_BACKUP_KEEP=14 +# GNEXUS_BOOK_HEALTH_URL=http://127.0.0.1:8000/health +# SYNAPSE_URL=https://synapse.gnexus.space +# SYNAPSE_API_KEY= +# SYNAPSE_DEFAULT_SOURCE=gnexus-book + +# gnexus-auth SSO. Leave the client id empty to run with authentication disabled. +# GNEXUS_BOOK_AUTH_CLIENT_ID= +# GNEXUS_BOOK_AUTH_CLIENT_SECRET= +# GNEXUS_BOOK_AUTH_BASE_URL=https://auth.gnexus.space +# GNEXUS_BOOK_AUTH_REDIRECT_URI=https://book.gnexus.space/auth/callback +# GNEXUS_BOOK_AUTH_WEBHOOK_SECRET= +# GNEXUS_BOOK_AUTH_SESSION_COOKIE=gnb_session +# GNEXUS_BOOK_AUTH_STATE_COOKIE=gnb_oauth_state +# GNEXUS_BOOK_AUTH_COOKIE_SECURE=true +# GNEXUS_BOOK_AUTH_SESSION_TTL_SECONDS=604800 +# GNEXUS_BOOK_AUTH_SCOPES=openid email profile roles permissions diff --git a/server/.venv b/server/.venv new file mode 120000 index 0000000..4d2a602 --- /dev/null +++ b/server/.venv @@ -0,0 +1 @@ +/home/gmikcon/Projects/gnexus-book/server/.venv \ No newline at end of file diff --git a/server/README.md b/server/README.md index 2c18f5c..6614069 100644 --- a/server/README.md +++ b/server/README.md @@ -14,23 +14,194 @@ uvicorn app.main:app --reload --host 127.0.0.1 --port 8080 ``` +## PostgreSQL storage + +The read path can be served from PostgreSQL instead of files: + +```bash +# From the repository root: start a local development cluster on 127.0.0.1:5433 +./scripts/dev-db.sh start + +cd server +export GNEXUS_BOOK_DATABASE_URL="$(../scripts/dev-db.sh url)" +.venv/bin/alembic upgrade head +.venv/bin/python -m app.storage.cli import --replace +.venv/bin/python -m app.storage.cli parity + +GNEXUS_BOOK_STORAGE_BACKEND=db .venv/bin/python -m uvicorn app.main:app --port 3005 +``` + +- The default backend is `file`; set `GNEXUS_BOOK_STORAGE_BACKEND=db` to use PostgreSQL. +- `import --replace` re-imports the current repository; `parity` compares file and + database read results and exits non-zero on a difference. +- `scripts/backup-db.sh` writes a custom-format dump to the off-host NFS by default; + `scripts/restore-db.sh` requires `GNEXUS_BOOK_RESTORE_YES=1` before replacing data. +- Documents and inventory are read and written through PostgreSQL. Every write creates + immutable versions grouped into a changeset; applying a changeset publishes it. + History, version reads, diff, and restore are available in database mode. +- Validation and freshness use the database when the backend is `db`. +- In database mode `POST /commit` is blocked: applying a changeset is the publish step. + `commit_changes` in MCP is a documented no-op. +- Database tests use `GNEXUS_BOOK_TEST_DATABASE_URL` (default + `postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test`) and are skipped when + PostgreSQL is unavailable. + +### Migration and cutover + +`python -m app.storage.cli migrate --replace --manifest /tmp/report.json` imports the +file repository, validates the database, verifies the content manifest, and reconciles +documents, search, inventory, relationships, validation and freshness. It exits +non-zero on any discrepancy. + +`python -m app.storage.cli assign-owner --user-json /path/to/owner.json` creates or +updates the owner mirror, assigns unowned documents and inventory items, and writes an +`ownership.assigned` audit entry. `ownership` prints owned/unowned counts. Historical +import authorship is preserved; ownership is stored separately in +`documents.owner_user_id` and `inventory_items.owner_user_id`. + +For a rehearsed or real cutover use the scripts: + +```bash +# Rehearsal / cutover against a target database +GNEXUS_BOOK_DATABASE_URL=postgresql+psycopg://USER@HOST:PORT/gnexus_book \ + ./scripts/cutover-db.sh --replace + +# Verify that the file backend is still readable for rollback +./scripts/rollback-cutover.sh +``` + +`cutover-db.sh` applies migrations, imports, verifies, reconciles and writes an +off-host dump. It does not switch the running service: set +`GNEXUS_BOOK_STORAGE_BACKEND=db` (and the database URL) in `server/.env`, then restart +the backend and MCP units. The systemd units load `server/.env` through +`EnvironmentFile`, and the Git checkout remains untouched as the rollback source. +See `../30-runbooks/cutover-postgres.md` for the full procedure. + +### Operations + +- `scripts/backup-db.sh` writes an off-host custom dump, verifies it, applies + retention and alerts through Synapse on failure when `SYNAPSE_URL` / + `SYNAPSE_API_KEY` are configured. +- `gnexus-book-backup.timer` runs the backup daily; the monthly + `gnexus-book-restore-drill.timer` is installed but disabled until a manual drill + succeeds. +- `scripts/restore-drill.sh [dump]` restores into a temporary database, validates it + and drops it. +- `scripts/healthcheck.sh` probes `GNEXUS_BOOK_HEALTH_URL` (default + `http://127.0.0.1:8000/health`) and checks `status` and `checks.db`. +- `scripts/notify-synapse.sh` sends a Synapse event envelope; it is used by the backup, + restore-drill and healthcheck failure paths. +- `deploy.sh` sources `server/.env`, runs `alembic upgrade head` when the `db` backend + is active, refreshes systemd units and restarts backend, MCP and frontend. + +Full procedure: `../30-runbooks/postgres-operations.md`. + +## 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_STATE_COOKIE # default gnb_oauth_state +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`. OAuth state is bound to a +short-lived HttpOnly cookie (`GNEXUS_BOOK_AUTH_STATE_COOKIE`, default +`gnb_oauth_state`); the callback rejects a missing or mismatched state cookie. Webhook +signatures follow gnexus-auth's `t=,v1=` scheme over +`.`. The `/internal/keys` provisioning API is blocked in nginx and +rate-limited before service-secret validation. + +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 The MCP server exposes the same repository, inventory, validation, pending-change, and Git commit logic through MCP tools and resources. It should be treated by AI agents as infrastructure memory. Agents should consult it proactively for infrastructure-specific work rather than waiting for the user to explicitly ask them to "look in the knowledge base". -Run over stdio: +Production agents use **streamable HTTP** at `/mcp-protocol/` with a personal +`mcp_*` key: ```bash cd server -.venv/bin/python -m app.mcp_server +GNEXUS_BOOK_MCP_HOST=0.0.0.0 GNEXUS_BOOK_MCP_PORT=8001 .venv/bin/python -m app.mcp_http ``` -Optional environment: +`python -m app.mcp_server` still runs stdio for local development and tests; SSE is a +legacy fallback only. `GNEXUS_BOOK_MCP_TRANSPORT=streamable-http` delegates to the same +guarded HTTP app. + +Environment: - `GNEXUS_BOOK_REPO_ROOT=/path/to/gnexus-book` - `GNEXUS_BOOK_MCP_TRANSPORT=stdio|sse|streamable-http` +- `GNEXUS_BOOK_MCP_HOST`, `GNEXUS_BOOK_MCP_PORT` +- `GNEXUS_BOOK_MCP_ALLOWED_HOSTS` — Host values accepted by FastMCP; include the public host behind nginx +- `GNEXUS_BOOK_MCP_ALLOWED_ORIGINS` — allowed Origin values for browser-based clients; include the public HTTPS origin +- `GNEXUS_BOOK_MCP_TOKEN` — optional static break-glass token, never a fallback for personal keys +- `GNEXUS_BOOK_MCP_REQUEST_RATE_LIMIT` — per-key requests per minute (default 300) +- `GNEXUS_BOOK_INTERNAL_KEY_SECRET`, `GNEXUS_BOOK_INTERNAL_ALLOWLIST` — provisioning API protection + +### Personal keys and provisioning + +- `mcp_tokens` stores only a SHA-256 hash and a tail hint; one active key per + (`user_id`, `consumer`), revocation is `revoked_at`. +- Mutating tools accept `is_user`; it changes `actor_kind` from `agent` to `user` while + keeping the key label and `via=mcp`. +- A read-only (`scopes` without `write`) key receives `{"error": 403, ...}` as data. + +Session-protected key management: + +- `GET /mcp-keys` (admins may pass `?all=true`) +- `POST /mcp-keys` — plaintext returned once +- `POST /mcp-keys/{key_id}/rotate` +- `DELETE /mcp-keys/{key_id}` + +Service-to-service provisioning (not exposed through nginx; requires +`X-Service-Key`/Bearer service secret and allowlisted source): + +- `POST /internal/keys` +- `GET /internal/keys?user_id=&consumer=` +- `POST /internal/keys/{key_id}/rotate` +- `DELETE /internal/keys/{key_id}` Core tools: @@ -45,11 +216,15 @@ - `check_freshness()` - `git_status()` - `git_diff(files?)` -- `propose_doc_change(path, content, summary, reason?)` -- `propose_inventory_item_change(inventory_type, item_id, patch, summary, reason?, mode?)` -- `apply_pending_change(change_id)` -- `commit_changes(summary, files, details?)` -- `update_doc(path, content, summary, reason?)` +- `propose_doc_change(path, content, summary, reason?, is_user?)` +- `propose_inventory_item_change(inventory_type, item_id, patch, summary, reason?, mode?, is_user?)` +- `apply_pending_change(change_id, is_user?)` +- `commit_changes(summary, files, details?, is_user?)` +- `update_doc(path, content, summary, reason?, is_user?)` +- `document_history(path)` +- `document_version(path, version_no)` +- `document_diff(path, from_version?, to_version?)` +- `restore_document_version(path, version_no, summary?, is_user?)` Agent usage policy: @@ -76,8 +251,26 @@ - Swagger UI: `GET /api-docs` - `GET /health` +- `GET /me` +- `GET /auth/login` +- `GET /auth/callback` +- `POST /auth/logout` +- `GET /mcp-keys` +- `POST /mcp-keys` +- `POST /mcp-keys/{key_id}/rotate` +- `DELETE /mcp-keys/{key_id}` +- `POST /internal/keys` +- `GET /internal/keys` +- `POST /internal/keys/{key_id}/rotate` +- `DELETE /internal/keys/{key_id}` +- `PATCH /me` +- `POST /webhooks/gnexus-auth` - `GET /docs` - `GET /docs/read?path=...` +- `GET /documents/{path}/history` +- `GET /documents/{path}/versions/{version_no}` +- `GET /documents/{path}/diff?from=&to=` +- `POST /documents/{path}/restore/{version_no}?summary=...` - `GET /search?q=...` - `GET /inventory` - `GET /inventory/{type}` @@ -98,12 +291,17 @@ ## Current Limitations -- `POST /changes` can create pending change records under `90-maintenance/pending-changes/`. -- `POST /changes/{id}/apply` can apply `kind=doc` and `kind=inventory-item` changes after validation. -- No authentication yet. -- `POST /commit` creates a local Git commit only. It does not push. +- `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. +- 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. +- Key scopes are currently `read` and `write`; finer-grained scopes are not implemented. +- 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 files. +- Validation uses JSON Schema 2020-12 for inventory records in both backends. +- Search keeps a substring/line-match path for exact response parity; a PostgreSQL + full-text index is deferred to a performance phase. ## Validation diff --git a/server/alembic.ini b/server/alembic.ini new file mode 100644 index 0000000..5d18e1b --- /dev/null +++ b/server/alembic.ini @@ -0,0 +1,39 @@ +[alembic] +script_location = alembic +prepend_sys_path = . +path_separator = os +sqlalchemy.url = + +[loggers] +keys = root,sqlalchemy,alembic + +[handlers] +keys = console + +[formatters] +keys = generic + +[logger_root] +level = WARNING +handlers = console +qualname = + +[logger_sqlalchemy] +level = WARNING +handlers = +qualname = sqlalchemy.engine + +[logger_alembic] +level = INFO +handlers = +qualname = alembic + +[handler_console] +class = StreamHandler +args = (sys.stderr,) +level = NOTSET +formatter = generic + +[formatter_generic] +format = %(levelname)-5.5s [%(name)s] %(message)s +datefmt = %H:%M:%S diff --git a/server/alembic/env.py b/server/alembic/env.py new file mode 100644 index 0000000..38dc45a --- /dev/null +++ b/server/alembic/env.py @@ -0,0 +1,61 @@ +from __future__ import annotations + +import os +from logging.config import fileConfig + +from alembic import context +from sqlalchemy import engine_from_config, pool + +from app.storage.models import Base + +config = context.config + +if config.config_file_name is not None: + fileConfig(config.config_file_name) + +target_metadata = Base.metadata + + +def _database_url() -> str: + url = os.environ.get("GNEXUS_BOOK_DATABASE_URL") or config.get_main_option("sqlalchemy.url") + if not url: + raise RuntimeError( + "Set GNEXUS_BOOK_DATABASE_URL or sqlalchemy.url before running Alembic" + ) + return url + + +def run_migrations_offline() -> None: + context.configure( + url=_database_url(), + target_metadata=target_metadata, + literal_binds=True, + dialect_opts={"paramstyle": "named"}, + compare_type=True, + ) + with context.begin_transaction(): + context.run_migrations() + + +def run_migrations_online() -> None: + configuration = config.get_section(config.config_ini_section, {}) + configuration["sqlalchemy.url"] = _database_url() + connectable = engine_from_config( + configuration, + prefix="sqlalchemy.", + poolclass=pool.NullPool, + ) + with connectable.connect() as connection: + context.configure( + connection=connection, + target_metadata=target_metadata, + compare_type=True, + ) + with context.begin_transaction(): + context.run_migrations() + + +if context.is_offline_mode(): + run_migrations_offline() +else: + run_migrations_online() diff --git a/server/alembic/script.py.mako b/server/alembic/script.py.mako new file mode 100644 index 0000000..ee746cf --- /dev/null +++ b/server/alembic/script.py.mako @@ -0,0 +1,28 @@ +"""${message} + +Revision ID: ${up_revision} +Revises: ${down_revision | comma,n} +Create Date: ${create_date} + +""" +from __future__ import annotations + +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa +${imports if imports else ""} + +# revision identifiers, used by Alembic. +revision: str = ${repr(up_revision)} +down_revision: Union[str, None] = ${repr(down_revision)} +branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)} +depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)} + + +def upgrade() -> None: + ${upgrades if upgrades else "pass"} + + +def downgrade() -> None: + ${downgrades if downgrades else "pass"} diff --git a/server/alembic/versions/9d8e9f47a7b0_mcp_personal_keys.py b/server/alembic/versions/9d8e9f47a7b0_mcp_personal_keys.py new file mode 100644 index 0000000..a84289b --- /dev/null +++ b/server/alembic/versions/9d8e9f47a7b0_mcp_personal_keys.py @@ -0,0 +1,52 @@ +"""mcp personal keys + +Revision ID: 9d8e9f47a7b0 +Revises: d95b33da4bfb +Create Date: 2026-11-19 18:55:22.343761 + +""" +from __future__ import annotations + +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa +from sqlalchemy.dialects import postgresql + +# revision identifiers, used by Alembic. +revision: str = '9d8e9f47a7b0' +down_revision: Union[str, None] = 'd95b33da4bfb' +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.create_table('mcp_tokens', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('user_id', sa.UUID(), nullable=False), + sa.Column('consumer', sa.Text(), nullable=False), + sa.Column('name', sa.Text(), nullable=False), + sa.Column('role', sa.Text(), nullable=True), + sa.Column('scopes', postgresql.JSONB(astext_type=sa.Text()), server_default=sa.text("'[]'::jsonb"), nullable=False), + sa.Column('token_hash', sa.Text(), nullable=False), + sa.Column('token_hint', sa.Text(), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('last_used_at', sa.DateTime(timezone=True), nullable=True), + sa.Column('revoked_at', sa.DateTime(timezone=True), nullable=True), + sa.Column('stale_at', sa.DateTime(timezone=True), nullable=True), + sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'), + sa.PrimaryKeyConstraint('id'), + sa.UniqueConstraint('token_hash') + ) + op.create_index('ix_mcp_tokens_user_id', 'mcp_tokens', ['user_id'], unique=False) + op.create_index('uq_mcp_tokens_user_consumer_active', 'mcp_tokens', ['user_id', 'consumer'], unique=True, postgresql_where=sa.text('revoked_at IS NULL')) + # ### end Alembic commands ### + + +def downgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.drop_index('uq_mcp_tokens_user_consumer_active', table_name='mcp_tokens', postgresql_where=sa.text('revoked_at IS NULL')) + op.drop_index('ix_mcp_tokens_user_id', table_name='mcp_tokens') + op.drop_table('mcp_tokens') + # ### end Alembic commands ### diff --git a/server/alembic/versions/ac5f4cd0d7bd_initial_schema.py b/server/alembic/versions/ac5f4cd0d7bd_initial_schema.py new file mode 100644 index 0000000..e459a52 --- /dev/null +++ b/server/alembic/versions/ac5f4cd0d7bd_initial_schema.py @@ -0,0 +1,190 @@ +"""initial schema + +Revision ID: ac5f4cd0d7bd +Revises: +Create Date: 2026-11-19 18:39:59.501658 + +""" +from __future__ import annotations + +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa +from sqlalchemy.dialects import postgresql + +# revision identifiers, used by Alembic. +revision: str = 'ac5f4cd0d7bd' +down_revision: Union[str, None] = None +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.create_table('blobs', + sa.Column('hash', sa.Text(), nullable=False), + sa.Column('content', sa.Text(), nullable=False), + sa.Column('size', sa.Integer(), nullable=False), + sa.PrimaryKeyConstraint('hash') + ) + op.create_table('documents', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('slug', sa.Text(), nullable=False), + sa.Column('title', sa.Text(), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('deleted_at', sa.DateTime(timezone=True), nullable=True), + sa.PrimaryKeyConstraint('id'), + sa.UniqueConstraint('slug') + ) + op.create_table('schemas', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('name', sa.Text(), nullable=False), + sa.Column('version', sa.Integer(), nullable=False), + sa.Column('body', postgresql.JSONB(astext_type=sa.Text()), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.PrimaryKeyConstraint('id'), + sa.UniqueConstraint('name', 'version', name='uq_schemas_name_version') + ) + op.create_table('users', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('sub', sa.Text(), nullable=False), + sa.Column('email', sa.Text(), nullable=True), + sa.Column('display_name', sa.Text(), nullable=True), + sa.Column('profile', postgresql.JSONB(astext_type=sa.Text()), nullable=False), + sa.Column('locale', sa.Text(), nullable=True), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('blocked_at', sa.DateTime(timezone=True), nullable=True), + sa.PrimaryKeyConstraint('id'), + sa.UniqueConstraint('sub') + ) + op.create_table('audit_log', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('actor_user_id', sa.UUID(), nullable=True), + sa.Column('actor_kind', sa.Text(), nullable=False), + sa.Column('actor_name', sa.Text(), nullable=True), + sa.Column('via', sa.Text(), nullable=False), + sa.Column('action', sa.Text(), nullable=False), + sa.Column('entity_type', sa.Text(), nullable=False), + sa.Column('entity_id', sa.Text(), nullable=False), + sa.Column('before', postgresql.JSONB(astext_type=sa.Text()), nullable=True), + sa.Column('after', postgresql.JSONB(astext_type=sa.Text()), nullable=True), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.ForeignKeyConstraint(['actor_user_id'], ['users.id'], ), + sa.PrimaryKeyConstraint('id') + ) + op.create_index('ix_audit_log_created_at', 'audit_log', ['created_at'], unique=False) + op.create_table('changesets', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('author_user_id', sa.UUID(), nullable=True), + sa.Column('summary', sa.Text(), nullable=False), + sa.Column('reason', sa.Text(), nullable=False), + sa.Column('status', sa.Text(), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('applied_at', sa.DateTime(timezone=True), nullable=True), + sa.Column('validation', postgresql.JSONB(astext_type=sa.Text()), nullable=True), + sa.CheckConstraint("status IN ('draft', 'applied', 'rejected')", name='ck_changesets_status'), + sa.ForeignKeyConstraint(['author_user_id'], ['users.id'], ), + sa.PrimaryKeyConstraint('id') + ) + op.create_table('inventory_types', + sa.Column('name', sa.Text(), nullable=False), + sa.Column('schema_id', sa.UUID(), nullable=True), + sa.ForeignKeyConstraint(['schema_id'], ['schemas.id'], ), + sa.PrimaryKeyConstraint('name') + ) + op.create_table('change_items', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('changeset_id', sa.UUID(), nullable=False), + sa.Column('kind', sa.Text(), nullable=False), + sa.Column('target', sa.Text(), nullable=False), + sa.Column('payload', postgresql.JSONB(astext_type=sa.Text()), nullable=False), + sa.Column('status', sa.Text(), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.CheckConstraint("kind IN ('doc', 'inventory', 'inventory-item')", name='ck_change_items_kind'), + sa.CheckConstraint("status IN ('draft', 'applied', 'rejected')", name='ck_change_items_status'), + sa.ForeignKeyConstraint(['changeset_id'], ['changesets.id'], ondelete='CASCADE'), + sa.PrimaryKeyConstraint('id') + ) + op.create_table('doc_versions', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('document_id', sa.UUID(), nullable=False), + sa.Column('version_no', sa.Integer(), nullable=False), + sa.Column('parent_version_id', sa.UUID(), nullable=True), + sa.Column('content_hash', sa.Text(), nullable=False), + sa.Column('raw', sa.Text(), nullable=False), + sa.Column('body', sa.Text(), nullable=False), + sa.Column('frontmatter', postgresql.JSONB(astext_type=sa.Text()), nullable=False), + sa.Column('author_user_id', sa.UUID(), nullable=True), + sa.Column('actor_kind', sa.Text(), nullable=False), + sa.Column('actor_name', sa.Text(), nullable=True), + sa.Column('via', sa.Text(), nullable=False), + sa.Column('changeset_id', sa.UUID(), nullable=True), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.ForeignKeyConstraint(['author_user_id'], ['users.id'], ), + sa.ForeignKeyConstraint(['changeset_id'], ['changesets.id'], ), + sa.ForeignKeyConstraint(['document_id'], ['documents.id'], ondelete='CASCADE'), + sa.ForeignKeyConstraint(['parent_version_id'], ['doc_versions.id'], ), + sa.PrimaryKeyConstraint('id'), + sa.UniqueConstraint('document_id', 'version_no', name='uq_doc_versions_document_version') + ) + op.create_index('ix_doc_versions_content_hash', 'doc_versions', ['content_hash'], unique=False) + op.create_table('inventory_items', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('type', sa.Text(), nullable=False), + sa.Column('item_id', sa.Text(), nullable=False), + sa.Column('position', sa.Integer(), nullable=False), + sa.Column('data', postgresql.JSONB(astext_type=sa.Text()), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('deleted_at', sa.DateTime(timezone=True), nullable=True), + sa.ForeignKeyConstraint(['type'], ['inventory_types.name'], ), + sa.PrimaryKeyConstraint('id') + ) + op.create_index('ix_inventory_items_type_position', 'inventory_items', ['type', 'position'], unique=False) + op.create_index('uq_inventory_items_type_item_live', 'inventory_items', ['type', 'item_id'], unique=True, postgresql_where=sa.text('deleted_at IS NULL')) + op.create_table('validation_runs', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('changeset_id', sa.UUID(), nullable=True), + sa.Column('status', sa.Text(), nullable=False), + sa.Column('issues', postgresql.JSONB(astext_type=sa.Text()), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.ForeignKeyConstraint(['changeset_id'], ['changesets.id'], ), + sa.PrimaryKeyConstraint('id') + ) + op.create_table('inventory_item_versions', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('inventory_item_id', sa.UUID(), nullable=False), + sa.Column('version_no', sa.Integer(), nullable=False), + sa.Column('data', postgresql.JSONB(astext_type=sa.Text()), nullable=False), + sa.Column('author_user_id', sa.UUID(), nullable=True), + sa.Column('changeset_id', sa.UUID(), nullable=True), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.ForeignKeyConstraint(['author_user_id'], ['users.id'], ), + sa.ForeignKeyConstraint(['changeset_id'], ['changesets.id'], ), + sa.ForeignKeyConstraint(['inventory_item_id'], ['inventory_items.id'], ondelete='CASCADE'), + sa.PrimaryKeyConstraint('id'), + sa.UniqueConstraint('inventory_item_id', 'version_no', name='uq_inventory_item_versions_item_version') + ) + # ### end Alembic commands ### + + +def downgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.drop_table('inventory_item_versions') + op.drop_table('validation_runs') + op.drop_index('uq_inventory_items_type_item_live', table_name='inventory_items', postgresql_where=sa.text('deleted_at IS NULL')) + op.drop_index('ix_inventory_items_type_position', table_name='inventory_items') + op.drop_table('inventory_items') + op.drop_index('ix_doc_versions_content_hash', table_name='doc_versions') + op.drop_table('doc_versions') + op.drop_table('change_items') + op.drop_table('inventory_types') + op.drop_table('changesets') + op.drop_index('ix_audit_log_created_at', table_name='audit_log') + op.drop_table('audit_log') + op.drop_table('users') + op.drop_table('schemas') + op.drop_table('documents') + op.drop_table('blobs') + # ### end Alembic commands ### diff --git a/server/alembic/versions/b59666c46655_data_ownership.py b/server/alembic/versions/b59666c46655_data_ownership.py new file mode 100644 index 0000000..dbffbb6 --- /dev/null +++ b/server/alembic/versions/b59666c46655_data_ownership.py @@ -0,0 +1,60 @@ +"""data ownership + +Revision ID: b59666c46655 +Revises: 9d8e9f47a7b0 +Create Date: 2026-11-20 15:54:42.093475 + +""" +from __future__ import annotations + +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa + + +# revision identifiers, used by Alembic. +revision: str = 'b59666c46655' +down_revision: Union[str, None] = '9d8e9f47a7b0' +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + op.add_column('documents', sa.Column('owner_user_id', sa.UUID(), nullable=True)) + op.create_index(op.f('ix_documents_owner_user_id'), 'documents', ['owner_user_id'], unique=False) + op.create_foreign_key( + 'fk_documents_owner_user_id_users', + 'documents', + 'users', + ['owner_user_id'], + ['id'], + ondelete='SET NULL', + ) + op.add_column('inventory_items', sa.Column('owner_user_id', sa.UUID(), nullable=True)) + op.create_index(op.f('ix_inventory_items_owner_user_id'), 'inventory_items', ['owner_user_id'], unique=False) + op.create_foreign_key( + 'fk_inventory_items_owner_user_id_users', + 'inventory_items', + 'users', + ['owner_user_id'], + ['id'], + ondelete='SET NULL', + ) + + +def downgrade() -> None: + op.drop_constraint( + 'fk_inventory_items_owner_user_id_users', + 'inventory_items', + type_='foreignkey', + ) + op.drop_index(op.f('ix_inventory_items_owner_user_id'), table_name='inventory_items') + op.drop_column('inventory_items', 'owner_user_id') + op.drop_constraint( + 'fk_documents_owner_user_id_users', + 'documents', + type_='foreignkey', + ) + op.drop_index(op.f('ix_documents_owner_user_id'), table_name='documents') + op.drop_column('documents', 'owner_user_id') diff --git a/server/alembic/versions/d95b33da4bfb_auth_sessions_and_actor_fields.py b/server/alembic/versions/d95b33da4bfb_auth_sessions_and_actor_fields.py new file mode 100644 index 0000000..5175485 --- /dev/null +++ b/server/alembic/versions/d95b33da4bfb_auth_sessions_and_actor_fields.py @@ -0,0 +1,84 @@ +"""auth sessions and actor fields + +Revision ID: d95b33da4bfb +Revises: ac5f4cd0d7bd +Create Date: 2026-11-19 18:50:55.263043 + +""" +from __future__ import annotations + +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa +from sqlalchemy.dialects import postgresql + +# revision identifiers, used by Alembic. +revision: str = 'd95b33da4bfb' +down_revision: Union[str, None] = 'ac5f4cd0d7bd' +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.create_table('oauth_states', + sa.Column('state_hash', sa.Text(), nullable=False), + sa.Column('code_verifier', sa.Text(), nullable=True), + sa.Column('return_to', sa.Text(), nullable=True), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('expires_at', sa.DateTime(timezone=True), nullable=False), + sa.PrimaryKeyConstraint('state_hash') + ) + op.create_table('webhook_events', + sa.Column('id', sa.Text(), nullable=False), + sa.Column('event_type', sa.Text(), nullable=False), + sa.Column('received_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('payload', postgresql.JSONB(astext_type=sa.Text()), nullable=False), + sa.PrimaryKeyConstraint('id') + ) + op.create_table('user_sessions', + sa.Column('id', sa.UUID(), nullable=False), + sa.Column('user_id', sa.UUID(), nullable=False), + sa.Column('token_hash', sa.Text(), nullable=False), + sa.Column('created_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('expires_at', sa.DateTime(timezone=True), nullable=False), + sa.Column('last_used_at', sa.DateTime(timezone=True), nullable=True), + sa.Column('revoked_at', sa.DateTime(timezone=True), nullable=True), + sa.Column('user_agent', sa.Text(), nullable=True), + sa.Column('ip_address', sa.Text(), nullable=True), + sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'), + sa.PrimaryKeyConstraint('id'), + sa.UniqueConstraint('token_hash') + ) + op.create_index('ix_user_sessions_user_id', 'user_sessions', ['user_id'], unique=False) + op.add_column('changesets', sa.Column('actor_kind', sa.Text(), server_default=sa.text("'system'"), nullable=False)) + op.add_column('changesets', sa.Column('actor_name', sa.Text(), nullable=True)) + op.add_column('changesets', sa.Column('via', sa.Text(), server_default=sa.text("'import'"), nullable=False)) + op.add_column('inventory_item_versions', sa.Column('actor_kind', sa.Text(), server_default=sa.text("'system'"), nullable=False)) + op.add_column('inventory_item_versions', sa.Column('actor_name', sa.Text(), nullable=True)) + op.add_column('inventory_item_versions', sa.Column('via', sa.Text(), server_default=sa.text("'import'"), nullable=False)) + op.add_column('users', sa.Column('system_role', sa.Text(), nullable=True)) + op.add_column('users', sa.Column('status', sa.Text(), nullable=True)) + op.add_column('users', sa.Column('client_roles', postgresql.JSONB(astext_type=sa.Text()), server_default=sa.text("'[]'::jsonb"), nullable=False)) + op.add_column('users', sa.Column('permissions', postgresql.JSONB(astext_type=sa.Text()), server_default=sa.text("'[]'::jsonb"), nullable=False)) + # ### end Alembic commands ### + + +def downgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.drop_column('users', 'permissions') + op.drop_column('users', 'client_roles') + op.drop_column('users', 'status') + op.drop_column('users', 'system_role') + op.drop_column('inventory_item_versions', 'via') + op.drop_column('inventory_item_versions', 'actor_name') + op.drop_column('inventory_item_versions', 'actor_kind') + op.drop_column('changesets', 'via') + op.drop_column('changesets', 'actor_name') + op.drop_column('changesets', 'actor_kind') + op.drop_index('ix_user_sessions_user_id', table_name='user_sessions') + op.drop_table('user_sessions') + op.drop_table('webhook_events') + op.drop_table('oauth_states') + # ### end Alembic commands ### diff --git a/server/app/auth/__init__.py b/server/app/auth/__init__.py new file mode 100644 index 0000000..2493b71 --- /dev/null +++ b/server/app/auth/__init__.py @@ -0,0 +1 @@ +"""gnexus-auth integration for Gnexus Book.""" diff --git a/server/app/auth/actor.py b/server/app/auth/actor.py new file mode 100644 index 0000000..6aafc76 --- /dev/null +++ b/server/app/auth/actor.py @@ -0,0 +1,24 @@ +from __future__ import annotations + +from dataclasses import dataclass +from typing import Any +from uuid import UUID + + +@dataclass(frozen=True) +class Actor: + kind: str = "agent" + name: str | None = None + via: str = "api" + user_id: UUID | None = None + + +def actor_for_current_user(user: Any | None, via: str = "ui") -> Actor: + if user is None: + return Actor(kind="agent", via=via) + return Actor( + kind="user", + name=user.display_name or user.email or user.sub, + via=via, + user_id=user.id, + ) diff --git a/server/app/auth/context.py b/server/app/auth/context.py new file mode 100644 index 0000000..7481409 --- /dev/null +++ b/server/app/auth/context.py @@ -0,0 +1,10 @@ +from __future__ import annotations + +from contextvars import ContextVar + +from .actor import Actor + +current_actor: ContextVar[Actor | None] = ContextVar("gnexus_book_actor", default=None) +current_mcp_scopes: ContextVar[tuple[str, ...] | None] = ContextVar( + "gnexus_book_mcp_scopes", default=None +) diff --git a/server/app/auth/deps.py b/server/app/auth/deps.py new file mode 100644 index 0000000..67056ce --- /dev/null +++ b/server/app/auth/deps.py @@ -0,0 +1,36 @@ +from __future__ import annotations + +from fastapi import Depends, HTTPException, Request + +from ..config import Settings, get_settings +from .sessions import CurrentUser + + +def get_current_user(request: Request) -> CurrentUser | None: + return getattr(request.state, "user", None) + + +def require_editor( + request: Request, settings: Settings = Depends(get_settings) +) -> CurrentUser | None: + """Allow writes for authenticated, non-blocked users. + + Role-specific policy (owner review for access/security changes) is a later + refinement; the middleware already rejects anonymous requests when auth is on. + """ + if not settings.auth_enabled: + return None + user = get_current_user(request) + if user is None: + raise HTTPException(status_code=401, detail="Not authenticated") + if user.is_blocked: + raise HTTPException(status_code=403, detail="User is blocked") + + scopes = getattr(request.state, "mcp_scopes", None) + if ( + scopes is not None + and request.method in {"POST", "PATCH", "PUT", "DELETE"} + and "write" not in scopes + ): + raise HTTPException(status_code=403, detail="write scope required") + return user diff --git a/server/app/auth/mcp_guard.py b/server/app/auth/mcp_guard.py new file mode 100644 index 0000000..2391f6a --- /dev/null +++ b/server/app/auth/mcp_guard.py @@ -0,0 +1,136 @@ +from __future__ import annotations + +import hmac +from dataclasses import replace +from typing import Callable + +from starlette.concurrency import run_in_threadpool +from starlette.responses import JSONResponse +from starlette.types import ASGIApp, Receive, Scope, Send + +from ..config import Settings +from ..storage.db import Database +from .actor import Actor +from .context import current_actor, current_mcp_scopes +from .mcp_keys import resolve_mcp_token +from .rate_limit import limiter_for + + +class McpTokenGuard: + """Bearer-key guard for the MCP streamable HTTP endpoint. + + Personal keys are resolved from `mcp_tokens`; the optional static token is a + break-glass mechanism only and never acts as a fallback for user requests. + """ + + def __init__( + self, app: ASGIApp, settings_provider: Callable[[], Settings] + ) -> None: + self.app = app + self._settings_provider = settings_provider + self._database: Database | None = None + + def _db(self, settings: Settings) -> Database: + if self._database is None: + self._database = Database.from_settings(settings) + return self._database + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if scope["type"] != "http": + await self.app(scope, receive, send) + return + + settings = self._settings_provider() + headers = { + key.decode("latin-1").lower(): value.decode("latin-1") + for key, value in scope.get("headers", []) + } + token = _bearer_token(headers.get("authorization", "")) + + if not token: + await _unauthorized(scope, receive, send) + return + + user = None + key = None + if settings.mcp_static_token and hmac.compare_digest( + token, settings.mcp_static_token + ): + actor = Actor(kind="system", name="break-glass", via="mcp") + scopes: tuple[str, ...] = ("read", "write") + else: + try: + resolved = await run_in_threadpool( + resolve_mcp_token, self._db(settings), token + ) + except Exception: + response = JSONResponse( + {"error": 503, "detail": "Authentication storage is unavailable"}, + status_code=503, + ) + await response(scope, receive, send) + return + if resolved is None: + await _unauthorized(scope, receive, send) + return + user, key = resolved + scopes = tuple(key.scopes or []) + actor = Actor( + kind="agent", + name=key.name, + via="mcp", + user_id=user.id, + ) + + limit_key = str(key.id) if key is not None else "break-glass" + if not limiter_for(settings.mcp_request_rate_limit).allow(limit_key): + response = JSONResponse( + {"error": 429, "detail": "rate limit exceeded"}, + status_code=429, + ) + await response(scope, receive, send) + return + + state = scope.setdefault("state", {}) + state["user"] = user + state["mcp_token"] = key + state["mcp_scopes"] = scopes + + actor_token = current_actor.set(actor) + scopes_token = current_mcp_scopes.set(scopes) + try: + await self.app(scope, receive, send) + finally: + current_actor.reset(actor_token) + current_mcp_scopes.reset(scopes_token) + + +def mcp_actor(is_user: bool = False) -> Actor: + base = current_actor.get() or Actor(kind="agent", via="mcp") + return replace(base, kind="user" if is_user else "agent") + + +def mcp_write_denied() -> dict[str, object] | None: + scopes = current_mcp_scopes.get() + if scopes is not None and "write" not in scopes: + return {"error": 403, "detail": "write scope required"} + return None + + +def _bearer_token(header: str) -> str | None: + if not header: + return None + parts = header.split(None, 1) + if len(parts) != 2 or parts[0].lower() != "bearer": + return None + token = parts[1].strip() + return token or None + + +async def _unauthorized(scope: Scope, receive: Receive, send: Send) -> None: + response = JSONResponse( + {"error": 401, "detail": "Unauthorized"}, + status_code=401, + headers={"WWW-Authenticate": "Bearer"}, + ) + await response(scope, receive, send) diff --git a/server/app/auth/mcp_keys.py b/server/app/auth/mcp_keys.py new file mode 100644 index 0000000..9d98d26 --- /dev/null +++ b/server/app/auth/mcp_keys.py @@ -0,0 +1,284 @@ +from __future__ import annotations + +import hashlib +import re +import secrets +from datetime import datetime +from typing import Any +from uuid import UUID + +from sqlalchemy import select, update + +from ..storage.db import Database +from ..storage.models import AuditLog, McpToken, User, utcnow +from .actor import Actor +from .sessions import CurrentUser, to_current_user + +CONSUMER_RE = re.compile(r"^[a-z0-9._-]{1,32}$") +KEY_PREFIX = "mcp_" +DEFAULT_SCOPES = ["read", "write"] + + +class KeyExistsError(ValueError): + def __init__(self, key_id: str, token_hint: str) -> None: + super().__init__("Key already exists for this user and consumer") + self.key_id = key_id + self.token_hint = token_hint + + +class KeyNotFoundError(ValueError): + pass + + +def _hash(token: str) -> str: + return hashlib.sha256(token.encode("utf-8")).hexdigest() + + +def _new_token() -> tuple[str, str, str]: + token = KEY_PREFIX + secrets.token_urlsafe(32) + return token, _hash(token), token[-6:] + + +def _iso(value: datetime | None) -> str | None: + if value is None: + return None + return value.isoformat().replace("+00:00", "Z") + + +def validate_consumer(consumer: str) -> str: + if not isinstance(consumer, str) or not CONSUMER_RE.match(consumer): + raise ValueError("consumer must match ^[a-z0-9._-]{1,32}$") + return consumer + + +def serialize_key(row: McpToken, user_sub: str | None = None) -> dict[str, Any]: + return { + "key_id": str(row.id), + "user_id": user_sub or str(row.user_id), + "consumer": row.consumer, + "name": row.name, + "role": row.role, + "scopes": list(row.scopes or []), + "token_hint": row.token_hint, + "created_at": _iso(row.created_at), + "last_used_at": _iso(row.last_used_at), + "revoked_at": _iso(row.revoked_at), + "stale_at": _iso(row.stale_at), + } + + +def create_key( + database: Database, + user: CurrentUser, + consumer: str, + name: str, + reissue: bool = False, + actor: Actor | None = None, +) -> tuple[dict[str, Any], str]: + validate_consumer(consumer) + clean_name = (name or f"{consumer} key").strip() + if not clean_name or len(clean_name) > 120: + raise ValueError("name must be 1..120 characters") + + actor = actor or Actor( + kind="user", + name=user.display_name or user.email or user.sub, + via="api", + user_id=user.id, + ) + now = utcnow() + + with database.session() as session: + with session.begin(): + active = session.scalars( + select(McpToken) + .where( + McpToken.user_id == user.id, + McpToken.consumer == consumer, + McpToken.revoked_at.is_(None), + ) + .with_for_update() + ).first() + if active is not None: + if not reissue: + raise KeyExistsError(str(active.id), active.token_hint) + active.revoked_at = now + active.stale_at = None + + token, token_hash, hint = _new_token() + row = McpToken( + user_id=user.id, + consumer=consumer, + name=clean_name, + role=user.system_role or "user", + scopes=list(DEFAULT_SCOPES), + token_hash=token_hash, + token_hint=hint, + created_at=now, + ) + session.add(row) + session.flush() + _audit(session, actor, "mcp_key.issue", row) + return serialize_key(row, user.sub), token + + +def list_keys( + database: Database, + user_id: UUID | None = None, + consumer: str | None = None, +) -> list[dict[str, Any]]: + with database.session() as session: + query = select(McpToken).order_by(McpToken.created_at.desc()) + if user_id is not None: + query = query.where(McpToken.user_id == user_id) + if consumer: + query = query.where(McpToken.consumer == consumer) + rows = session.scalars(query).all() + user_ids = {row.user_id for row in rows} + subs = { + identifier: sub + for identifier, sub in session.execute( + select(User.id, User.sub).where(User.id.in_(user_ids)) + ).all() + } + return [serialize_key(row, subs.get(row.user_id)) for row in rows] + + +def revoke_key( + database: Database, + key_id: str, + owner_user_id: UUID | None = None, + actor: Actor | None = None, +) -> dict[str, Any]: + actor = actor or Actor(kind="service", name="key-management", via="api") + with database.session() as session: + with session.begin(): + row = _load_key(session, key_id) + if owner_user_id is not None and row.user_id != owner_user_id: + raise KeyNotFoundError("Key not found") + if row.revoked_at is None: + row.revoked_at = utcnow() + _audit(session, actor, "mcp_key.revoke", row) + user = session.get(User, row.user_id) + return serialize_key(row, user.sub if user else None) + + +def rotate_key( + database: Database, + key_id: str, + owner_user_id: UUID | None = None, + actor: Actor | None = None, +) -> tuple[dict[str, Any], str]: + with database.session() as session: + row = _load_key(session, key_id) + if owner_user_id is not None and row.user_id != owner_user_id: + raise KeyNotFoundError("Key not found") + if row.revoked_at is not None: + raise KeyNotFoundError("Key not found") + user = session.get(User, row.user_id) + if user is None: + raise KeyNotFoundError("Key not found") + current = to_current_user(user) + consumer = row.consumer + name = row.name + + actor = actor or Actor( + kind="user", + name=current.display_name or current.email or current.sub, + via="api", + user_id=current.id, + ) + return create_key( + database, + current, + consumer, + name, + reissue=True, + actor=actor, + ) + + +def resolve_mcp_token( + database: Database, token: str +) -> tuple[CurrentUser, McpToken] | None: + if not token or not token.startswith(KEY_PREFIX): + return None + + now = utcnow() + with database.session() as session: + row = session.scalars( + select(McpToken).where(McpToken.token_hash == _hash(token)) + ).first() + if row is None or row.revoked_at is not None: + return None + user = session.get(User, row.user_id) + if user is None or user.blocked_at is not None: + return None + row.last_used_at = now + session.commit() + return to_current_user(user), row + + +def revoke_user_keys(database: Database, user_id: UUID) -> None: + with database.session() as session: + with session.begin(): + session.execute( + update(McpToken) + .where( + McpToken.user_id == user_id, + McpToken.revoked_at.is_(None), + ) + .values(revoked_at=utcnow()) + ) + + +def revoke_user_keys_in_session(session, user_id: UUID, now: datetime) -> None: + session.execute( + update(McpToken) + .where( + McpToken.user_id == user_id, + McpToken.revoked_at.is_(None), + ) + .values(revoked_at=now) + ) + + +def mark_user_keys_stale_in_session(session, user_id: UUID, now: datetime) -> None: + session.execute( + update(McpToken) + .where( + McpToken.user_id == user_id, + McpToken.revoked_at.is_(None), + ) + .values(stale_at=now) + ) + + +def _load_key(session, key_id: str) -> McpToken: + try: + identifier = UUID(str(key_id)) + except ValueError as exc: + raise KeyNotFoundError("Key not found") from exc + row = session.get(McpToken, identifier) + if row is None: + raise KeyNotFoundError("Key not found") + return row + + +def _audit(session, actor: Actor, action: str, row: McpToken) -> None: + session.add( + AuditLog( + actor_user_id=actor.user_id, + actor_kind=actor.kind, + actor_name=actor.name, + via=actor.via, + action=action, + entity_type="mcp_key", + entity_id=str(row.id), + after={ + "user_id": str(row.user_id), + "consumer": row.consumer, + "token_hint": row.token_hint, + }, + ) + ) diff --git a/server/app/auth/mcp_routes.py b/server/app/auth/mcp_routes.py new file mode 100644 index 0000000..5e72e11 --- /dev/null +++ b/server/app/auth/mcp_routes.py @@ -0,0 +1,267 @@ +from __future__ import annotations + +import hmac +from typing import Any +from uuid import UUID + +from fastapi import APIRouter, Depends, HTTPException, Request +from fastapi.responses import JSONResponse, Response +from pydantic import BaseModel +from sqlalchemy import select + +from ..config import Settings, get_settings +from ..storage.db import Database +from ..storage.models import User +from .actor import Actor +from .mcp_keys import ( + KeyExistsError, + KeyNotFoundError, + create_key, + list_keys, + revoke_key, + rotate_key, +) +from .rate_limit import limiter_for +from .sessions import CurrentUser, to_current_user + +router = APIRouter() + + +class UserKeyRequest(BaseModel): + consumer: str + name: str = "" + reissue: bool = False + + +class InternalKeyRequest(BaseModel): + user_id: str + consumer: str + name: str = "" + reissue: bool = False + + +def _client_host(request: Request) -> str: + peer = request.client.host if request.client else "" + forwarded = request.headers.get("x-real-ip", "").strip() + if not forwarded: + forwarded_for = request.headers.get("x-forwarded-for", "") + forwarded = forwarded_for.split(",", 1)[0].strip() if forwarded_for else "" + if peer in {"127.0.0.1", "::1"} and forwarded: + return forwarded + return peer + + +def require_internal_service( + request: Request, settings: Settings = Depends(get_settings) +) -> None: + if not settings.internal_key_secret: + raise HTTPException(status_code=503, detail="Internal key API is not configured") + + host = _client_host(request) + limiter = limiter_for(settings.internal_rate_limit) + if not limiter.allow(host or "unknown"): + raise HTTPException(status_code=429, detail="Too many requests") + + supplied = request.headers.get("x-service-key") + if not supplied: + authorization = request.headers.get("authorization", "") + parts = authorization.split(None, 1) + if len(parts) == 2 and parts[0].lower() == "bearer": + supplied = parts[1].strip() + + if not supplied or not hmac.compare_digest(supplied, settings.internal_key_secret): + raise HTTPException(status_code=401, detail="Invalid service credentials") + + allowed = set(settings.internal_allowlist) | {"127.0.0.1", "::1"} + if host not in allowed: + raise HTTPException(status_code=403, detail="Source address is not allowed") + + +def _require_user( + request: Request, settings: Settings, require_write: bool = False +) -> CurrentUser: + if not settings.auth_enabled: + raise HTTPException(status_code=400, detail="Authentication is not configured") + user = getattr(request.state, "user", None) + if user is None: + raise HTTPException(status_code=401, detail="Not authenticated") + if user.is_blocked: + raise HTTPException(status_code=403, detail="User is blocked") + if require_write: + scopes = getattr(request.state, "mcp_scopes", None) + if scopes is not None and "write" not in scopes: + raise HTTPException(status_code=403, detail="write scope required") + return user + + +def _user_by_sub(database: Database, sub: str) -> CurrentUser | None: + with database.session() as session: + user = session.scalars(select(User).where(User.sub == sub)).first() + return to_current_user(user) if user is not None else None + + +def _key_response(key: dict[str, Any], token: str) -> dict[str, Any]: + return {**key, "token": token} + + +@router.get("/mcp-keys") +def user_keys( + request: Request, settings: Settings = Depends(get_settings) +) -> dict[str, Any]: + user = _require_user(request, settings) + database = Database.from_settings(settings) + include_all = request.query_params.get("all") == "true" and user.system_role == "admin" + return { + "items": list_keys(database, user_id=None if include_all else user.id) + } + + +@router.post("/mcp-keys", status_code=201) +def user_create_key( + payload: UserKeyRequest, + request: Request, + settings: Settings = Depends(get_settings), +): + user = _require_user(request, settings, require_write=True) + if not limiter_for(settings.mcp_key_rate_limit).allow(f"user:{user.id}"): + raise HTTPException(status_code=429, detail="Too many requests") + database = Database.from_settings(settings) + try: + key, token = create_key( + database, + user, + payload.consumer, + payload.name, + reissue=payload.reissue, + ) + except KeyExistsError as exc: + return JSONResponse( + {"error": "key_exists", "key_id": exc.key_id, "token_hint": exc.token_hint}, + status_code=409, + ) + except ValueError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc + return _key_response(key, token) + + +@router.post("/mcp-keys/{key_id}/rotate") +def user_rotate_key( + key_id: str, + request: Request, + settings: Settings = Depends(get_settings), +): + user = _require_user(request, settings, require_write=True) + if not limiter_for(settings.mcp_key_rate_limit).allow(f"user:{user.id}"): + raise HTTPException(status_code=429, detail="Too many requests") + database = Database.from_settings(settings) + try: + key, token = rotate_key( + database, + key_id, + owner_user_id=None if user.system_role == "admin" else user.id, + ) + except KeyNotFoundError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + except ValueError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc + return _key_response(key, token) + + +@router.delete("/mcp-keys/{key_id}", status_code=204) +def user_revoke_key( + key_id: str, + request: Request, + settings: Settings = Depends(get_settings), +) -> Response: + user = _require_user(request, settings, require_write=True) + try: + revoke_key( + Database.from_settings(settings), + key_id, + owner_user_id=None if user.system_role == "admin" else user.id, + ) + except KeyNotFoundError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + return Response(status_code=204) + + +@router.post("/internal/keys", status_code=201) +def internal_create_key( + payload: InternalKeyRequest, + settings: Settings = Depends(get_settings), + _: None = Depends(require_internal_service), +): + database = Database.from_settings(settings) + user = _user_by_sub(database, payload.user_id) + if user is None: + return JSONResponse({"error": "invalid_user_id"}, status_code=400) + try: + key, token = create_key( + database, + user, + payload.consumer, + payload.name, + reissue=payload.reissue, + actor=Actor(kind="service", name="provisioning", via="api"), + ) + except KeyExistsError as exc: + return JSONResponse( + {"error": "key_exists", "key_id": exc.key_id, "token_hint": exc.token_hint}, + status_code=409, + ) + except ValueError as exc: + return JSONResponse({"error": "invalid_request", "detail": str(exc)}, status_code=400) + return _key_response(key, token) + + +@router.get("/internal/keys") +def internal_list_keys( + user_id: str | None = None, + consumer: str | None = None, + settings: Settings = Depends(get_settings), + _: None = Depends(require_internal_service), +): + database = Database.from_settings(settings) + owner: UUID | None = None + if user_id: + user = _user_by_sub(database, user_id) + if user is None: + return {"items": []} + owner = user.id + return {"items": list_keys(database, user_id=owner, consumer=consumer)} + + +@router.delete("/internal/keys/{key_id}", status_code=204) +def internal_revoke_key( + key_id: str, + settings: Settings = Depends(get_settings), + _: None = Depends(require_internal_service), +) -> Response: + try: + revoke_key( + Database.from_settings(settings), + key_id, + actor=Actor(kind="service", name="provisioning", via="api"), + ) + except KeyNotFoundError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + return Response(status_code=204) + + +@router.post("/internal/keys/{key_id}/rotate", status_code=201) +def internal_rotate_key( + key_id: str, + settings: Settings = Depends(get_settings), + _: None = Depends(require_internal_service), +): + try: + key, token = rotate_key( + Database.from_settings(settings), + key_id, + actor=Actor(kind="service", name="provisioning", via="api"), + ) + except KeyNotFoundError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + except ValueError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc + return _key_response(key, token) diff --git a/server/app/auth/middleware.py b/server/app/auth/middleware.py new file mode 100644 index 0000000..23fd1e2 --- /dev/null +++ b/server/app/auth/middleware.py @@ -0,0 +1,119 @@ +from __future__ import annotations + +from typing import Callable + +from starlette.concurrency import run_in_threadpool +from starlette.requests import Request +from starlette.responses import JSONResponse +from starlette.types import ASGIApp, Receive, Scope, Send + +from ..config import Settings +from ..storage.db import Database +from .actor import Actor, actor_for_current_user +from .context import current_actor, current_mcp_scopes +from .mcp_keys import resolve_mcp_token +from .sessions import CurrentUser, resolve_session + + +class SessionAuthMiddleware: + """Resolve the browser session and guard non-exempt routes. + + Authentication is disabled when the gnexus-auth client is not configured, so + local development and the file backend keep working without credentials. + """ + + def __init__( + self, app: ASGIApp, settings_provider: Callable[[], Settings] + ) -> None: + self.app = app + self._settings_provider = settings_provider + self._database: Database | None = None + + def _db(self, settings: Settings) -> Database: + if self._database is None: + self._database = Database.from_settings(settings) + return self._database + + async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: + if scope["type"] != "http": + await self.app(scope, receive, send) + return + + settings = self._settings_provider() + if not settings.auth_enabled: + await self.app(scope, receive, send) + return + + request = Request(scope) + state = scope.setdefault("state", {}) + token = request.cookies.get(settings.auth_session_cookie) + user: CurrentUser | None = None + actor = None + mcp_scopes: tuple[str, ...] | None = None + + if token: + try: + user = await run_in_threadpool(resolve_session, self._db(settings), token) + except Exception: + response = JSONResponse( + {"detail": "Authentication storage is unavailable"}, + status_code=503, + ) + await response(scope, receive, send) + return + if user is not None: + actor = actor_for_current_user(user, via="ui") + + if user is None: + authorization = request.headers.get("authorization", "") + parts = authorization.split(None, 1) + if len(parts) == 2 and parts[0].lower() == "bearer": + try: + resolved = await run_in_threadpool( + resolve_mcp_token, self._db(settings), parts[1].strip() + ) + except Exception: + response = JSONResponse( + {"detail": "Authentication storage is unavailable"}, + status_code=503, + ) + await response(scope, receive, send) + return + if resolved is not None: + user, key = resolved + mcp_scopes = tuple(key.scopes or []) + actor_kind = ( + "user" + if request.headers.get("x-actor", "").lower() == "user" + else "agent" + ) + actor = Actor( + kind=actor_kind, + name=key.name, + via="api", + user_id=user.id, + ) + + state["user"] = user + state["mcp_scopes"] = mcp_scopes + actor_token = current_actor.set(actor or actor_for_current_user(None, via="ui")) + scopes_token = current_mcp_scopes.set(mcp_scopes) + try: + if user is None and not _is_exempt(request.url.path): + response = JSONResponse({"detail": "Not authenticated"}, status_code=401) + await response(scope, receive, send) + return + await self.app(scope, receive, send) + finally: + current_actor.reset(actor_token) + current_mcp_scopes.reset(scopes_token) + + +def _is_exempt(path: str) -> bool: + return ( + path == "/health" + or path == "/me" + or path.startswith("/auth/") + or path.startswith("/webhooks/gnexus-auth") + or path.startswith("/internal/") + ) diff --git a/server/app/auth/rate_limit.py b/server/app/auth/rate_limit.py new file mode 100644 index 0000000..d4008fa --- /dev/null +++ b/server/app/auth/rate_limit.py @@ -0,0 +1,38 @@ +from __future__ import annotations + +import threading +import time +from collections import deque + + +class SlidingWindowLimiter: + def __init__(self, limit: int, window_seconds: int = 60) -> None: + self.limit = max(1, limit) + self.window_seconds = window_seconds + self._events: dict[str, deque[float]] = {} + self._lock = threading.Lock() + + def allow(self, key: str) -> bool: + now = time.monotonic() + cutoff = now - self.window_seconds + with self._lock: + events = self._events.setdefault(key, deque()) + while events and events[0] < cutoff: + events.popleft() + if len(events) >= self.limit: + return False + events.append(now) + return True + + +_limiters: dict[int, SlidingWindowLimiter] = {} +_limiters_lock = threading.Lock() + + +def limiter_for(limit: int) -> SlidingWindowLimiter: + with _limiters_lock: + limiter = _limiters.get(limit) + if limiter is None: + limiter = SlidingWindowLimiter(limit) + _limiters[limit] = limiter + return limiter diff --git a/server/app/auth/routes.py b/server/app/auth/routes.py new file mode 100644 index 0000000..ec52d7e --- /dev/null +++ b/server/app/auth/routes.py @@ -0,0 +1,195 @@ +from __future__ import annotations + +import hmac +from datetime import UTC, datetime +from typing import Any +from urllib.parse import urlsplit + +from fastapi import APIRouter, Depends, HTTPException, Query, Request +from fastapi.responses import JSONResponse, RedirectResponse +from gnexus_gauth.exceptions import WebhookPayloadException, WebhookVerificationException +from pydantic import BaseModel +from starlette.concurrency import run_in_threadpool + +from ..config import Settings, get_settings +from ..storage.db import Database +from .service import AuthError, AuthService +from .sessions import SUPPORTED_LOCALES, revoke_session, set_user_locale +from .users import serialize_user +from .webhooks import handle_webhook_event + +router = APIRouter() + + +class MeUpdate(BaseModel): + locale: str | None = None + + +def get_auth_service( + settings: Settings = Depends(get_settings), +) -> AuthService | None: + if not settings.auth_enabled: + return None + return AuthService(settings, Database.from_settings(settings)) + + +def _me_payload(request: Request, settings: Settings) -> dict[str, Any]: + user = getattr(request.state, "user", None) + return { + "auth_enabled": settings.auth_enabled, + "user": serialize_user(user) if user else None, + "locale": user.locale if user else None, + "locale_effective": user.effective_locale if user else "en", + } + + +def _safe_return_to(value: str | None) -> str | None: + if not value or "\\" in value or any(ord(character) < 32 for character in value): + return None + parts = urlsplit(value) + if parts.scheme or parts.netloc: + return None + if not value.startswith("/") or value.startswith("//"): + return None + return value + + +@router.get("/me") +def me(request: Request, settings: Settings = Depends(get_settings)) -> dict[str, Any]: + return _me_payload(request, settings) + + +@router.patch("/me") +def update_me( + payload: MeUpdate, + request: Request, + settings: Settings = Depends(get_settings), +) -> dict[str, Any]: + if not settings.auth_enabled: + raise HTTPException(status_code=400, detail="Authentication is not configured") + user = getattr(request.state, "user", None) + if user is None: + raise HTTPException(status_code=401, detail="Not authenticated") + if payload.locale not in {None, "", *SUPPORTED_LOCALES}: + raise HTTPException(status_code=400, detail="locale must be en, uk, ru, or empty") + + updated = set_user_locale( + Database.from_settings(settings), user.id, payload.locale or None + ) + return { + "auth_enabled": True, + "user": serialize_user(updated), + "locale": updated.locale, + "locale_effective": updated.effective_locale, + } + + +@router.get("/auth/login") +def auth_login( + return_to: str | None = Query(default=None), + settings: Settings = Depends(get_settings), + service: AuthService | None = Depends(get_auth_service), +) -> RedirectResponse: + if service is None: + raise HTTPException(status_code=400, detail="Authentication is not configured") + url, state = service.build_login_url(return_to=_safe_return_to(return_to)) + response = RedirectResponse(url, status_code=303) + response.set_cookie( + key=settings.auth_state_cookie, + value=state, + max_age=settings.auth_state_ttl_seconds, + httponly=True, + secure=settings.auth_cookie_secure, + samesite="lax", + path="/", + ) + return response + + +@router.get("/auth/callback") +def auth_callback( + request: Request, + code: str | None = Query(default=None), + state: str | None = Query(default=None), + error: str | None = Query(default=None), + settings: Settings = Depends(get_settings), + service: AuthService | None = Depends(get_auth_service), +) -> RedirectResponse: + if service is None: + raise HTTPException(status_code=400, detail="Authentication is not configured") + if error: + response = RedirectResponse("/?auth_error=access_denied", status_code=303) + response.delete_cookie(settings.auth_state_cookie, path="/") + return response + if not code or not state: + raise HTTPException(status_code=400, detail="Missing code or state") + + state_cookie = request.cookies.get(settings.auth_state_cookie) + if not state_cookie or not hmac.compare_digest(state, state_cookie): + raise HTTPException(status_code=400, detail="Invalid OAuth state") + + try: + _, token, expires_at, return_to = service.exchange_code( + code, + state, + user_agent=request.headers.get("user-agent"), + ip_address=request.client.host if request.client else None, + ) + except AuthError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc + except Exception as exc: + raise HTTPException(status_code=400, detail="Authentication failed") from exc + + response = RedirectResponse(_safe_return_to(return_to) or "/", status_code=303) + response.delete_cookie(settings.auth_state_cookie, path="/") + max_age = max(0, int((expires_at - datetime.now(UTC)).total_seconds())) + response.set_cookie( + key=settings.auth_session_cookie, + value=token, + max_age=max_age, + httponly=True, + secure=settings.auth_cookie_secure, + samesite="lax", + path="/", + ) + return response + + +@router.post("/auth/logout") +def auth_logout( + request: Request, settings: Settings = Depends(get_settings) +) -> JSONResponse: + token = request.cookies.get(settings.auth_session_cookie) + if token: + revoke_session(Database.from_settings(settings), token) + response = JSONResponse({"status": "ok"}) + response.delete_cookie(settings.auth_session_cookie, path="/") + return response + + +@router.post("/webhooks/gnexus-auth") +@router.post("/webhooks/gnexus-auth/") +async def gnexus_auth_webhook( + request: Request, settings: Settings = Depends(get_settings) +) -> dict[str, Any]: + if not settings.auth_enabled or not settings.auth_webhook_secret: + raise HTTPException(status_code=503, detail="Webhook endpoint is not configured") + + raw_bytes = await request.body() + try: + raw_body = raw_bytes.decode("utf-8") + except UnicodeDecodeError as exc: + raise HTTPException(status_code=400, detail="Invalid webhook payload") from exc + + service = AuthService(settings, Database.from_settings(settings)) + try: + event = service.verify_and_parse_webhook(raw_body, dict(request.headers)) + except WebhookVerificationException as exc: + raise HTTPException(status_code=401, detail="Invalid webhook signature") from exc + except WebhookPayloadException as exc: + raise HTTPException(status_code=400, detail="Invalid webhook payload") from exc + + processed = await run_in_threadpool( + handle_webhook_event, Database.from_settings(settings), event + ) + return {"status": "ok", "event_id": event.event_id, "duplicate": not processed} diff --git a/server/app/auth/service.py b/server/app/auth/service.py new file mode 100644 index 0000000..504a432 --- /dev/null +++ b/server/app/auth/service.py @@ -0,0 +1,118 @@ +from __future__ import annotations + +from datetime import timedelta +from typing import Any + +from gnexus_gauth.config import GAuthConfig +from gnexus_gauth.dto import AuthenticatedUser, WebhookEvent +from gnexus_gauth.oauth import AuthorizationUrlBuilder, HttpTokenEndpoint, PkceGenerator +from gnexus_gauth.runtime import HttpRuntimeUserProvider +from gnexus_gauth.webhook import HmacWebhookVerifier, JsonWebhookParser + +from ..config import Settings +from ..storage.db import Database +from ..storage.models import OAuthState, utcnow +from .sessions import CurrentUser, create_session, token_hash +from .users import upsert_user_from_auth + + +class AuthError(ValueError): + pass + + +class AuthService: + def __init__(self, settings: Settings, database: Database) -> None: + if not settings.auth_enabled: + raise AuthError("Authentication is not configured") + self.settings = settings + self.database = database + self.config = GAuthConfig( + base_url=settings.auth_base_url or "", + client_id=settings.auth_client_id or "", + client_secret=settings.auth_client_secret or "", + redirect_uri=settings.auth_redirect_uri or "", + state_ttl_seconds=settings.auth_state_ttl_seconds, + webhook_tolerance_seconds=settings.auth_webhook_tolerance_seconds, + user_agent="gnexus-book", + ) + self._tokens = HttpTokenEndpoint(self.config) + self._users = HttpRuntimeUserProvider(self.config) + self._urls = AuthorizationUrlBuilder(self.config) + self._webhook_verifier = HmacWebhookVerifier(self.config) + self._webhook_parser = JsonWebhookParser() + + def build_login_url(self, return_to: str | None = None) -> tuple[str, str]: + state = PkceGenerator.generate_state() + verifier = PkceGenerator.generate_verifier() + challenge = PkceGenerator.generate_challenge(verifier) + now = utcnow() + expires_at = now + timedelta(seconds=self.settings.auth_state_ttl_seconds) + + with self.database.session() as session: + with session.begin(): + session.add( + OAuthState( + state_hash=token_hash(state), + code_verifier=verifier, + return_to=return_to, + created_at=now, + expires_at=expires_at, + ) + ) + + url = self._urls.build( + state=state, + pkce_challenge=challenge, + return_to=return_to, + scopes=list(self.settings.auth_scopes), + ) + return url, state + + def exchange_code( + self, + code: str, + state: str, + user_agent: str | None = None, + ip_address: str | None = None, + ) -> tuple[CurrentUser, str, Any, str | None]: + now = utcnow() + state_hash = token_hash(state) + with self.database.session() as session: + record = session.get(OAuthState, state_hash) + if record is None or record.expires_at <= now: + raise AuthError("Unknown or expired authorization state") + verifier = record.code_verifier + return_to = record.return_to + if not verifier: + raise AuthError("Missing PKCE verifier") + + token_set = self._tokens.exchange_authorization_code(code, verifier) + auth_user: AuthenticatedUser = self._users.fetch_user(token_set.access_token) + user = upsert_user_from_auth( + self.database, auth_user, self.settings.auth_client_id or "" + ) + + with self.database.session() as session: + with session.begin(): + record = session.get(OAuthState, state_hash) + if record is not None: + session.delete(record) + + token, expires_at = create_session( + self.database, + user.id, + self.settings.auth_session_ttl_seconds, + user_agent=user_agent, + ip_address=ip_address, + ) + return user, token, expires_at, return_to + + def verify_and_parse_webhook( + self, raw_body: str, headers: dict[str, str] + ) -> WebhookEvent: + if not self.settings.auth_webhook_secret: + raise AuthError("Webhook secret is not configured") + self._webhook_verifier.verify( + raw_body, headers, self.settings.auth_webhook_secret + ) + return self._webhook_parser.parse(raw_body) diff --git a/server/app/auth/sessions.py b/server/app/auth/sessions.py new file mode 100644 index 0000000..54c758b --- /dev/null +++ b/server/app/auth/sessions.py @@ -0,0 +1,148 @@ +from __future__ import annotations + +import hashlib +import secrets +from dataclasses import dataclass, replace +from datetime import datetime, timedelta +from typing import Any +from uuid import UUID + +from sqlalchemy import select, update + +from ..storage.db import Database +from ..storage.models import User, UserSession, utcnow + +SUPPORTED_LOCALES = {"en", "uk", "ru"} + + +@dataclass(frozen=True) +class CurrentUser: + id: UUID + sub: str + email: str | None + display_name: str | None + profile: dict[str, Any] + locale: str | None + system_role: str | None + status: str | None + client_roles: tuple[str, ...] + permissions: tuple[str, ...] + blocked_at: datetime | None + + @property + def is_blocked(self) -> bool: + return self.blocked_at is not None + + @property + def effective_locale(self) -> str: + candidate = self.locale or self.profile.get("locale") or "en" + normalized = str(candidate).split("-", 1)[0].lower() + return normalized if normalized in SUPPORTED_LOCALES else "en" + + +def token_hash(token: str) -> str: + return hashlib.sha256(token.encode("utf-8")).hexdigest() + + +def to_current_user(user: User) -> CurrentUser: + return CurrentUser( + id=user.id, + sub=user.sub, + email=user.email, + display_name=user.display_name, + profile=dict(user.profile or {}), + locale=user.locale, + system_role=user.system_role, + status=user.status, + client_roles=tuple(user.client_roles or []), + permissions=tuple(user.permissions or []), + blocked_at=user.blocked_at, + ) + + +def create_session( + database: Database, + user_id: UUID, + ttl_seconds: int, + user_agent: str | None = None, + ip_address: str | None = None, +) -> tuple[str, datetime]: + token = secrets.token_urlsafe(32) + now = utcnow() + expires_at = now + timedelta(seconds=ttl_seconds) + with database.session() as session: + with session.begin(): + session.add( + UserSession( + user_id=user_id, + token_hash=token_hash(token), + created_at=now, + expires_at=expires_at, + user_agent=user_agent, + ip_address=ip_address, + ) + ) + return token, expires_at + + +def resolve_session(database: Database, token: str) -> CurrentUser | None: + now = utcnow() + with database.session() as session: + row = session.scalars( + select(UserSession).where(UserSession.token_hash == token_hash(token)) + ).first() + if row is None or row.revoked_at is not None or row.expires_at <= now: + return None + + user = session.get(User, row.user_id) + if user is None or user.blocked_at is not None: + return None + + row.last_used_at = now + session.commit() + return to_current_user(user) + + +def revoke_session(database: Database, token: str) -> None: + with database.session() as session: + with session.begin(): + session.execute( + update(UserSession) + .where( + UserSession.token_hash == token_hash(token), + UserSession.revoked_at.is_(None), + ) + .values(revoked_at=utcnow()) + ) + + +def revoke_user_sessions(database: Database, user_id: UUID) -> None: + with database.session() as session: + with session.begin(): + session.execute( + update(UserSession) + .where( + UserSession.user_id == user_id, + UserSession.revoked_at.is_(None), + ) + .values(revoked_at=utcnow()) + ) + + +def set_user_locale(database: Database, user_id: UUID, locale: str | None) -> CurrentUser: + normalized = locale or None + if normalized is not None and normalized not in SUPPORTED_LOCALES: + raise ValueError("locale must be en, uk, ru, or empty") + + with database.session() as session: + with session.begin(): + user = session.get(User, user_id) + if user is None: + raise ValueError("User not found") + user.locale = normalized + session.flush() + return to_current_user(user) + + +def with_locale(user: CurrentUser, locale: str | None) -> CurrentUser: + return replace(user, locale=locale or None) diff --git a/server/app/auth/users.py b/server/app/auth/users.py new file mode 100644 index 0000000..54b7553 --- /dev/null +++ b/server/app/auth/users.py @@ -0,0 +1,75 @@ +from __future__ import annotations + +from typing import Any + +from sqlalchemy import select + +from gnexus_gauth.dto import AuthenticatedUser + +from ..storage.db import Database +from ..storage.models import User, utcnow +from .sessions import CurrentUser, to_current_user + + +def upsert_user_from_auth( + database: Database, + auth_user: AuthenticatedUser, + client_id: str, +) -> CurrentUser: + profile = dict(auth_user.profile or {}) + display_name = ( + profile.get("display_name") + or profile.get("username") + or auth_user.email + or auth_user.user_id + ) + access = next( + (item for item in auth_user.client_access_list if item.client_id == client_id), + None, + ) + roles = list(access.role_ids) if access else [] + permissions = list(access.permission_ids) if access else [] + + with database.session() as session: + with session.begin(): + user = session.scalars( + select(User).where(User.sub == auth_user.user_id) + ).first() + if user is None: + user = User( + sub=auth_user.user_id, + email=auth_user.email or None, + display_name=display_name, + profile=profile, + locale=None, + system_role=auth_user.system_role, + status=auth_user.status, + client_roles=roles, + permissions=permissions, + ) + session.add(user) + else: + user.email = auth_user.email or user.email + user.display_name = display_name + user.profile = profile + user.system_role = auth_user.system_role + user.status = auth_user.status + user.client_roles = roles + user.permissions = permissions + if auth_user.status not in {"blocked", "archived", "deleted"}: + user.blocked_at = None + user.updated_at = utcnow() + session.flush() + return to_current_user(user) + + +def serialize_user(user: CurrentUser) -> dict[str, Any]: + return { + "user_id": user.sub, + "email": user.email, + "display_name": user.display_name, + "avatar_url": user.profile.get("avatar_url"), + "system_role": user.system_role, + "roles": list(user.client_roles), + "permissions": list(user.permissions), + } diff --git a/server/app/auth/webhooks.py b/server/app/auth/webhooks.py new file mode 100644 index 0000000..b26fd70 --- /dev/null +++ b/server/app/auth/webhooks.py @@ -0,0 +1,104 @@ +from __future__ import annotations + +import hashlib +import json + +from sqlalchemy import select, update + +from gnexus_gauth.dto import WebhookEvent + +from ..storage.db import Database +from ..storage.models import AuditLog, User, UserSession, WebhookEvent as StoredWebhookEvent, utcnow +from .mcp_keys import mark_user_keys_stale_in_session, revoke_user_keys_in_session + +BLOCKED_EVENTS = {"user.blocked", "user.archived", "user.deleted"} +UNBLOCKED_EVENTS = {"user.unblocked", "user.restored"} +SESSION_EVENTS = {"auth.global_logout", "global_logout", "session.revoked"} +PROFILE_EVENTS = {"user.profile_updated", "profile.update"} +ROLE_EVENTS = {"client.roles_changed", "client.permissions_changed"} + + +def handle_webhook_event(database: Database, event: WebhookEvent) -> bool: + """Store and apply one verified gnexus-auth event. Returns False on duplicate.""" + event_id = event.event_id or _fallback_event_id(event) + now = utcnow() + + with database.session() as session: + with session.begin(): + if session.get(StoredWebhookEvent, event_id) is not None: + return False + + session.add( + StoredWebhookEvent( + id=event_id, + event_type=event.event_type, + received_at=now, + payload=event.raw_payload, + ) + ) + + target = event.target_identifiers or {} + raw_user_id = target.get("user_id") + user_id = str(raw_user_id) if raw_user_id is not None else None + user = None + if user_id: + user = session.scalars(select(User).where(User.sub == user_id)).first() + + if event.event_type in BLOCKED_EVENTS: + if user is not None: + user.blocked_at = now + _revoke_sessions(session, user.id, now) + revoke_user_keys_in_session(session, user.id, now) + elif event.event_type in ROLE_EVENTS: + if user is not None: + mark_user_keys_stale_in_session(session, user.id, now) + elif event.event_type in UNBLOCKED_EVENTS: + if user is not None: + user.blocked_at = None + elif event.event_type in SESSION_EVENTS: + if user is not None: + _revoke_sessions(session, user.id, now) + elif event.event_type in PROFILE_EVENTS: + profile = (event.metadata or {}).get("profile") + if user is not None and isinstance(profile, dict): + user.profile = dict(profile) + user.display_name = ( + profile.get("display_name") + or profile.get("username") + or user.display_name + ) + elif event.event_type == "user.system_role_updated": + system_role = (event.metadata or {}).get("system_role") + if user is not None and isinstance(system_role, str): + user.system_role = system_role + + session.add( + AuditLog( + actor_kind="system", + actor_name="gnexus-auth", + via="webhook", + action=event.event_type, + entity_type="user", + entity_id=user_id or "", + after={"event_id": event_id}, + ) + ) + + return True + + +def _revoke_sessions(session, user_id, now) -> None: + session.execute( + update(UserSession) + .where( + UserSession.user_id == user_id, + UserSession.revoked_at.is_(None), + ) + .values(revoked_at=now) + ) + + +def _fallback_event_id(event: WebhookEvent) -> str: + payload = json.dumps(event.raw_payload, sort_keys=True, ensure_ascii=False) + digest = hashlib.sha256(f"{event.event_type}.{payload}".encode("utf-8")).hexdigest() + return f"local_{digest}" diff --git a/server/app/config.py b/server/app/config.py index 4d60ba5..17c3da2 100644 --- a/server/app/config.py +++ b/server/app/config.py @@ -1,16 +1,118 @@ from __future__ import annotations +import os from functools import lru_cache from pathlib import Path +STORAGE_BACKENDS = {"file", "db"} +DEFAULT_MCP_ALLOWED_HOSTS = ("127.0.0.1:*", "localhost:*", "[::1]:*") +DEFAULT_MCP_ALLOWED_ORIGINS = ( + "http://127.0.0.1:*", + "http://localhost:*", + "http://[::1]:*", +) + class Settings: - def __init__(self, repo_root: Path | None = None) -> None: - self.repo_root = repo_root or Path(__file__).resolve().parents[2] + def __init__( + self, + repo_root: Path | None = None, + database_url: str | None = None, + storage_backend: str | None = None, + ) -> None: + configured_root = repo_root or os.environ.get("GNEXUS_BOOK_REPO_ROOT") + self.repo_root = ( + Path(configured_root).expanduser().resolve() + if configured_root + else Path(__file__).resolve().parents[2] + ) self.docs_extensions = {".md"} self.inventory_dir = self.repo_root / "40-inventory" self.generated_dir = self.repo_root / "60-generated" + backend = (storage_backend or os.environ.get("GNEXUS_BOOK_STORAGE_BACKEND", "file")).lower() + if backend not in STORAGE_BACKENDS: + raise ValueError( + f"GNEXUS_BOOK_STORAGE_BACKEND must be one of {sorted(STORAGE_BACKENDS)}, got {backend!r}" + ) + self.storage_backend = backend + self.database_url = database_url or os.environ.get("GNEXUS_BOOK_DATABASE_URL") + + self.auth_client_id = os.environ.get("GNEXUS_BOOK_AUTH_CLIENT_ID") + self.auth_client_secret = os.environ.get("GNEXUS_BOOK_AUTH_CLIENT_SECRET") + self.auth_base_url = os.environ.get("GNEXUS_BOOK_AUTH_BASE_URL") + self.auth_redirect_uri = os.environ.get("GNEXUS_BOOK_AUTH_REDIRECT_URI") + self.auth_webhook_secret = os.environ.get("GNEXUS_BOOK_AUTH_WEBHOOK_SECRET") + self.auth_session_cookie = os.environ.get( + "GNEXUS_BOOK_AUTH_SESSION_COOKIE", "gnb_session" + ) + self.auth_state_cookie = os.environ.get( + "GNEXUS_BOOK_AUTH_STATE_COOKIE", "gnb_oauth_state" + ) + self.auth_session_ttl_seconds = int( + os.environ.get("GNEXUS_BOOK_AUTH_SESSION_TTL_SECONDS", str(7 * 24 * 3600)) + ) + self.auth_state_ttl_seconds = int( + os.environ.get("GNEXUS_BOOK_AUTH_STATE_TTL_SECONDS", "300") + ) + self.auth_webhook_tolerance_seconds = int( + os.environ.get("GNEXUS_BOOK_AUTH_WEBHOOK_TOLERANCE_SECONDS", "300") + ) + self.auth_scopes = tuple( + os.environ.get( + "GNEXUS_BOOK_AUTH_SCOPES", + "openid email profile roles permissions", + ).split() + ) + secure_default = "true" if (self.auth_redirect_uri or "").startswith("https://") else "false" + self.auth_cookie_secure = os.environ.get( + "GNEXUS_BOOK_AUTH_COOKIE_SECURE", secure_default + ).lower() in {"1", "true", "yes", "on"} + + self.mcp_host = os.environ.get("GNEXUS_BOOK_MCP_HOST", "0.0.0.0") + self.mcp_port = int(os.environ.get("GNEXUS_BOOK_MCP_PORT", "8001")) + self.mcp_static_token = os.environ.get("GNEXUS_BOOK_MCP_TOKEN") + self.mcp_key_rate_limit = int( + os.environ.get("GNEXUS_BOOK_MCP_KEY_RATE_LIMIT", "30") + ) + self.mcp_request_rate_limit = int( + os.environ.get("GNEXUS_BOOK_MCP_REQUEST_RATE_LIMIT", "300") + ) + self.mcp_allowed_hosts = tuple( + item.strip() + for item in os.environ.get( + "GNEXUS_BOOK_MCP_ALLOWED_HOSTS", + ",".join(DEFAULT_MCP_ALLOWED_HOSTS), + ).split(",") + if item.strip() + ) or DEFAULT_MCP_ALLOWED_HOSTS + self.mcp_allowed_origins = tuple( + item.strip() + for item in os.environ.get( + "GNEXUS_BOOK_MCP_ALLOWED_ORIGINS", + ",".join(DEFAULT_MCP_ALLOWED_ORIGINS), + ).split(",") + if item.strip() + ) or DEFAULT_MCP_ALLOWED_ORIGINS + self.internal_key_secret = os.environ.get("GNEXUS_BOOK_INTERNAL_KEY_SECRET") + self.internal_allowlist = tuple( + item.strip() + for item in os.environ.get("GNEXUS_BOOK_INTERNAL_ALLOWLIST", "").split(",") + if item.strip() + ) + self.internal_rate_limit = int( + os.environ.get("GNEXUS_BOOK_INTERNAL_RATE_LIMIT", "60") + ) + + @property + def auth_enabled(self) -> bool: + return bool( + self.auth_client_id + and self.auth_client_secret + and self.auth_base_url + and self.auth_redirect_uri + ) + @lru_cache def get_settings() -> Settings: diff --git a/server/app/docs_repository.py b/server/app/docs_repository.py index 44c0729..e1dcf21 100644 --- a/server/app/docs_repository.py +++ b/server/app/docs_repository.py @@ -17,6 +17,9 @@ "node_modules", } +# Tooling instructions, not knowledge-base content. +EXCLUDED_FILES = {"CLAUDE.md"} + class RepositoryError(ValueError): pass @@ -38,6 +41,8 @@ for path in sorted(self.repo_root.rglob("*.md")): if any(part in EXCLUDED_PARTS for part in path.parts): continue + if path.name in EXCLUDED_FILES: + continue rel = path.relative_to(self.repo_root).as_posix() raw = path.read_text(encoding="utf-8") parsed = parse_frontmatter(rel, raw) diff --git a/server/app/git_adapter.py b/server/app/git_adapter.py index 3c433b7..3e4f323 100644 --- a/server/app/git_adapter.py +++ b/server/app/git_adapter.py @@ -54,6 +54,11 @@ return {"diff": result.stdout} def commit(self, request: CommitRequest) -> dict[str, Any]: + if self.settings.storage_backend == "db": + raise GitAdapterError( + "Write path is not available in database mode yet; use the file backend " + "until Phase 2 of the PostgreSQL migration" + ) validation = validate_repository(self.settings) if validation["status"] != "ok": raise GitAdapterError("Repository validation failed; commit blocked") diff --git a/server/app/main.py b/server/app/main.py index c27a293..11bef25 100644 --- a/server/app/main.py +++ b/server/app/main.py @@ -1,20 +1,41 @@ from __future__ import annotations +from datetime import UTC, datetime from typing import Any from fastapi import Depends, FastAPI, HTTPException, Query +from .auth.deps import require_editor +from .auth.mcp_routes import router as mcp_keys_router +from .auth.middleware import SessionAuthMiddleware +from .auth.routes import router as auth_router from .config import Settings, get_settings -from .docs_repository import DocsRepository, RepositoryError +from .docs_repository import RepositoryError from .freshness import build_freshness_report from .git_adapter import CommitRequest, GitAdapter, GitAdapterError -from .inventory import InventoryError, InventoryRepository -from .pending_changes import ( - PendingChangeError, - PendingChangeRepository, - ProposedChangeRequest, -) +from .inventory import InventoryError +from .pending_changes import PendingChangeError, ProposedChangeRequest from .relationships import build_relationships +from .storage.db import Database +from .storage.documents import ( + DocumentError, + diff_document_versions, + get_document_version, + list_document_versions, + restore_document_version, +) +from .storage.factory import ( + make_docs_repository, + make_inventory_repository, + make_pending_change_repository, +) +from .storage.freshness import build_freshness_report_db +from .storage.protocols import ( + DocsRepositoryProtocol, + InventoryRepositoryProtocol, + PendingChangeRepositoryProtocol, +) +from .storage.validation import validate_database from .validation import validate_repository @@ -27,17 +48,23 @@ redoc_url="/api-redoc", ) - -def get_docs_repo(settings: Settings = Depends(get_settings)) -> DocsRepository: - return DocsRepository(settings) +app.add_middleware(SessionAuthMiddleware, settings_provider=get_settings) +app.include_router(auth_router) +app.include_router(mcp_keys_router) -def get_inventory_repo(settings: Settings = Depends(get_settings)) -> InventoryRepository: - return InventoryRepository(settings) +def get_docs_repo(settings: Settings = Depends(get_settings)) -> DocsRepositoryProtocol: + return make_docs_repository(settings) -def get_pending_change_repo(settings: Settings = Depends(get_settings)) -> PendingChangeRepository: - return PendingChangeRepository(settings) +def get_inventory_repo(settings: Settings = Depends(get_settings)) -> InventoryRepositoryProtocol: + return make_inventory_repository(settings) + + +def get_pending_change_repo( + settings: Settings = Depends(get_settings), +) -> PendingChangeRepositoryProtocol: + return make_pending_change_repository(settings, via="api") def get_git_adapter(settings: Settings = Depends(get_settings)) -> GitAdapter: @@ -45,17 +72,31 @@ @app.get("/health") -def health(settings: Settings = Depends(get_settings)) -> dict[str, str]: - return {"status": "ok", "repo_root": settings.repo_root.as_posix()} +def health(settings: Settings = Depends(get_settings)) -> dict[str, Any]: + payload: dict[str, Any] = { + "status": "ok", + "service": "gnexus-book", + "version": app.version, + "storage": settings.storage_backend, + "timestamp": datetime.now(UTC).isoformat().replace("+00:00", "Z"), + } + if settings.storage_backend == "db": + try: + Database.from_settings(settings).ping() + payload["checks"] = {"db": {"status": "ok"}} + except Exception: + payload["status"] = "down" + payload["checks"] = {"db": {"status": "down", "detail": "database unavailable"}} + return payload @app.get("/docs") -def list_docs(repo: DocsRepository = Depends(get_docs_repo)) -> list[dict[str, object]]: +def list_docs(repo: DocsRepositoryProtocol = Depends(get_docs_repo)) -> list[dict[str, object]]: return repo.list_docs() @app.get("/docs/read") -def read_doc(path: str = Query(...), repo: DocsRepository = Depends(get_docs_repo)) -> dict[str, object]: +def read_doc(path: str = Query(...), repo: DocsRepositoryProtocol = Depends(get_docs_repo)) -> dict[str, object]: try: return repo.read_doc(path) except RepositoryError as exc: @@ -63,12 +104,78 @@ @app.get("/search") -def search(q: str = Query(...), repo: DocsRepository = Depends(get_docs_repo)) -> list[dict[str, object]]: +def search(q: str = Query(...), repo: DocsRepositoryProtocol = Depends(get_docs_repo)) -> list[dict[str, object]]: return repo.search(q) +@app.get("/documents/{path:path}/history") +def document_history( + path: str, settings: Settings = Depends(get_settings) +) -> list[dict[str, object]]: + if settings.storage_backend != "db": + raise HTTPException(status_code=400, detail="Document history is available in database mode") + try: + return list_document_versions(Database.from_settings(settings), path) + except DocumentError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + + +@app.get("/documents/{path:path}/versions/{version_no}") +def document_version( + path: str, version_no: int, settings: Settings = Depends(get_settings) +) -> dict[str, object]: + if settings.storage_backend != "db": + raise HTTPException(status_code=400, detail="Document versions are available in database mode") + try: + return get_document_version(Database.from_settings(settings), path, version_no) + except DocumentError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + + +@app.get("/documents/{path:path}/diff") +def document_diff( + path: str, + from_version: int | None = Query(default=None, alias="from"), + to_version: int | None = Query(default=None, alias="to"), + settings: Settings = Depends(get_settings), +) -> dict[str, object]: + if settings.storage_backend != "db": + raise HTTPException(status_code=400, detail="Document diff is available in database mode") + try: + return diff_document_versions( + Database.from_settings(settings), path, from_version, to_version + ) + except DocumentError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + + +@app.post("/documents/{path:path}/restore/{version_no}") +def document_restore( + path: str, + version_no: int, + summary: str | None = Query(default=None), + settings: Settings = Depends(get_settings), + user=Depends(require_editor), +) -> dict[str, object]: + if settings.storage_backend != "db": + raise HTTPException(status_code=400, detail="Document restore is available in database mode") + try: + return restore_document_version( + Database.from_settings(settings), + settings, + path, + version_no, + summary=summary, + via="api", + ) + except DocumentError as exc: + raise HTTPException(status_code=404, detail=str(exc)) from exc + except PendingChangeError as exc: + raise HTTPException(status_code=400, detail=str(exc)) from exc + + @app.get("/inventory") -def list_inventory_types(repo: InventoryRepository = Depends(get_inventory_repo)) -> list[str]: +def list_inventory_types(repo: InventoryRepositoryProtocol = Depends(get_inventory_repo)) -> list[str]: return repo.list_types() @@ -76,7 +183,7 @@ def read_inventory( inventory_type: str, raw: bool = False, - repo: InventoryRepository = Depends(get_inventory_repo), + repo: InventoryRepositoryProtocol = Depends(get_inventory_repo), ) -> object: try: if raw: @@ -90,7 +197,7 @@ def read_inventory_item( inventory_type: str, item_id: str, - repo: InventoryRepository = Depends(get_inventory_repo), + repo: InventoryRepositoryProtocol = Depends(get_inventory_repo), ) -> dict[str, object]: try: return repo.read_item(inventory_type, item_id) @@ -99,7 +206,7 @@ @app.get("/traffic-routes") -def read_traffic_routes(repo: InventoryRepository = Depends(get_inventory_repo)) -> object: +def read_traffic_routes(repo: InventoryRepositoryProtocol = Depends(get_inventory_repo)) -> object: try: return repo.read_parsed("traffic-routes") except InventoryError as exc: @@ -107,7 +214,7 @@ @app.get("/relationships") -def relationships(repo: InventoryRepository = Depends(get_inventory_repo)) -> dict[str, object]: +def relationships(repo: InventoryRepositoryProtocol = Depends(get_inventory_repo)) -> dict[str, object]: try: return build_relationships(repo) except InventoryError as exc: @@ -116,23 +223,29 @@ @app.get("/health/freshness") def freshness(settings: Settings = Depends(get_settings)) -> dict[str, object]: + if settings.storage_backend == "db": + return build_freshness_report_db(Database.from_settings(settings)) return build_freshness_report(settings) @app.get("/validate") def validate(settings: Settings = Depends(get_settings)) -> dict[str, object]: + if settings.storage_backend == "db": + return validate_database(Database.from_settings(settings)) return validate_repository(settings) @app.get("/changes") -def list_changes(repo: PendingChangeRepository = Depends(get_pending_change_repo)) -> list[dict[str, object]]: +def list_changes( + repo: PendingChangeRepositoryProtocol = Depends(get_pending_change_repo), +) -> list[dict[str, object]]: return repo.list() @app.get("/changes/{change_id}") def read_change( change_id: str, - repo: PendingChangeRepository = Depends(get_pending_change_repo), + repo: PendingChangeRepositoryProtocol = Depends(get_pending_change_repo), ) -> dict[str, object]: try: return repo.get(change_id) @@ -143,7 +256,8 @@ @app.post("/changes") def propose_change( request: ProposedChangeRequest, - repo: PendingChangeRepository = Depends(get_pending_change_repo), + repo: PendingChangeRepositoryProtocol = Depends(get_pending_change_repo), + user=Depends(require_editor), ) -> dict[str, object]: try: return repo.create(request) @@ -154,7 +268,8 @@ @app.post("/changes/{change_id}/apply") def apply_change( change_id: str, - repo: PendingChangeRepository = Depends(get_pending_change_repo), + repo: PendingChangeRepositoryProtocol = Depends(get_pending_change_repo), + user=Depends(require_editor), ) -> dict[str, object]: try: return repo.apply(change_id) @@ -192,7 +307,11 @@ @app.post("/commit") -def commit(request: CommitRequest, git: GitAdapter = Depends(get_git_adapter)) -> dict[str, object]: +def commit( + request: CommitRequest, + git: GitAdapter = Depends(get_git_adapter), + user=Depends(require_editor), +) -> dict[str, object]: try: return git.commit(request) except GitAdapterError as exc: diff --git a/server/app/mcp_http.py b/server/app/mcp_http.py new file mode 100644 index 0000000..dc342c4 --- /dev/null +++ b/server/app/mcp_http.py @@ -0,0 +1,20 @@ +from __future__ import annotations + +from .auth.mcp_guard import McpTokenGuard +from .config import get_settings +from .mcp_server import mcp + +# The inner FastMCP app routes at /mcp-protocol/ (configured on the FastMCP +# instance); the guard rejects requests without a personal mcp_* key. +app = McpTokenGuard(mcp.streamable_http_app(), get_settings) + + +def run() -> None: + import uvicorn + + settings = get_settings() + uvicorn.run(app, host=settings.mcp_host, port=settings.mcp_port) + + +if __name__ == "__main__": + run() diff --git a/server/app/mcp_server.py b/server/app/mcp_server.py index bb8c771..e3792ab 100644 --- a/server/app/mcp_server.py +++ b/server/app/mcp_server.py @@ -6,15 +6,30 @@ from typing import Annotated, Any, Literal from mcp.server.fastmcp import FastMCP +from mcp.server.transport_security import TransportSecuritySettings from pydantic import Field +from .auth.actor import Actor +from .auth.mcp_guard import mcp_actor, mcp_write_denied from .config import Settings -from .docs_repository import DocsRepository from .freshness import build_freshness_report from .git_adapter import CommitRequest, GitAdapter -from .inventory import InventoryRepository -from .pending_changes import PendingChangeRepository, ProposedChangeRequest +from .pending_changes import ProposedChangeRequest from .relationships import build_relationships +from .storage.db import Database +from .storage.documents import ( + diff_document_versions, + get_document_version, + list_document_versions, + restore_document_version as restore_document_version_service, +) +from .storage.factory import ( + make_docs_repository, + make_inventory_repository, + make_pending_change_repository, +) +from .storage.freshness import build_freshness_report_db +from .storage.validation import validate_database from .validation import validate_repository @@ -55,6 +70,17 @@ - Only after the document exists should you propose the inventory item with the `docs` path. - Never use local filesystem tools to edit gnexus-book repository files directly — always use the MCP tools. +Storage mode: +- In database mode, apply_pending_change publishes a changeset transactionally; commit_changes is a no-op. +- Use document_history, document_version, document_diff, and restore_document_version for version work. +- Restoring a version creates a new version; it never rewrites history. + +Transport and keys: +- Production agents connect over streamable HTTP at /mcp-protocol/ with a personal mcp_* key. +- Mutating tools accept is_user; set it true only when the key owner explicitly acts as themselves. +- Tool errors are returned as data: {"error": 401|403|..., "detail": "..."}. +- A read-only key cannot call mutating tools. + For propose_inventory_item_change, pass concrete top-level arguments, not a wrapper: inventory_type="hosts", item_id="bserv", mode="create", patch={"ip_address": "192.168.1.130", "user": "bserv"}, summary="Document bserv host". The patch object is the inventory item fields to create or update. @@ -114,6 +140,10 @@ - For create mode, patch is the new inventory item fields. - For update mode, patch is the fields to merge into the existing item. +Storage mode: +- In database mode, apply_pending_change publishes; commit_changes is a no-op. +- Use document_history, document_version, document_diff, and restore_document_version for version work. + Do document: - hostnames, usernames, IPs, domains, ports, routes, access models, credential references, versions, repository activity. @@ -132,16 +162,20 @@ return Settings() if not repo_root else Settings(repo_root=Path(repo_root)) -def _docs() -> DocsRepository: - return DocsRepository(_settings()) +def _docs(): + return make_docs_repository(_settings()) -def _inventory() -> InventoryRepository: - return InventoryRepository(_settings()) +def _inventory(): + return make_inventory_repository(_settings()) -def _pending() -> PendingChangeRepository: - return PendingChangeRepository(_settings()) +def _pending(): + return make_pending_change_repository( + _settings(), + via="mcp", + default_actor=Actor(kind="agent", via="mcp"), + ) def _git() -> GitAdapter: @@ -191,13 +225,19 @@ def validate_repository_tool() -> dict[str, object]: - """Validate schemas, docs, inventory links, duplicate ids, and raw secret patterns before trusting or committing changes.""" - return validate_repository(_settings()) + """Validate schemas, docs, duplicate ids, and raw secret patterns before trusting or committing changes.""" + settings = _settings() + if settings.storage_backend == "db": + return validate_database(Database.from_settings(settings)) + return validate_repository(settings) def check_freshness() -> dict[str, object]: """Return freshness/staleness report for deciding what documentation needs review.""" - return build_freshness_report(_settings()) + settings = _settings() + if settings.storage_backend == "db": + return build_freshness_report_db(Database.from_settings(settings)) + return build_freshness_report(settings) def git_status() -> dict[str, Any]: @@ -225,8 +265,12 @@ content: Annotated[str, Field(description="Full Markdown document content, including frontmatter when the target document uses it.")], summary: Annotated[str, Field(description="Short factual change summary used for the pending change and later commit message.")], reason: Annotated[str, Field(description="Why this change is needed; mention the source of the fact when useful.")] = "", + is_user: Annotated[bool, Field(description="Set true only when the key owner explicitly acts as themselves; default actions are attributed to the agent.")] = False, ) -> dict[str, Any]: """Create a pending Markdown document change. Pass path, content, summary, and optional reason as top-level arguments.""" + denied = mcp_write_denied() + if denied: + return denied request = ProposedChangeRequest( kind="doc", target=path, @@ -234,7 +278,7 @@ reason=reason, payload={"content": content}, ) - return _pending().create(request) + return _pending().create(request, actor=mcp_actor(is_user)) def propose_inventory_item_change( @@ -244,8 +288,12 @@ summary: Annotated[str, Field(description="Short factual summary of the inventory change.")], reason: Annotated[str, Field(description="Why this inventory fact should be persisted; mention the source when useful.")] = "", mode: Annotated[Literal["update", "create"], Field(description="'create' for a new inventory item; 'update' to patch an existing item.")] = "update", + is_user: Annotated[bool, Field(description="Set true only when the key owner explicitly acts as themselves; default actions are attributed to the agent.")] = False, ) -> dict[str, Any]: """Create a pending inventory change. Use top-level arguments: inventory_type, item_id, patch, summary, reason, mode.""" + denied = mcp_write_denied() + if denied: + return denied request = ProposedChangeRequest( kind="inventory-item", target=f"{inventory_type}/{item_id}", @@ -253,45 +301,137 @@ reason=reason, payload={"mode": mode, "patch": patch}, ) - return _pending().create(request) + return _pending().create(request, actor=mcp_actor(is_user)) -def apply_pending_change(change_id: str) -> dict[str, Any]: +def apply_pending_change(change_id: str, is_user: bool = False) -> dict[str, Any]: """Apply one pending knowledge change and roll it back automatically if validation fails.""" - return _pending().apply(change_id) + denied = mcp_write_denied() + if denied: + return denied + return _pending().apply(change_id, actor=mcp_actor(is_user)) -def commit_changes(summary: str, files: list[str], details: str = "") -> dict[str, Any]: +def commit_changes( + summary: str, files: list[str], details: str = "", is_user: bool = False +) -> dict[str, Any]: """Validate the repository and create a local Git commit for selected documentation files.""" + denied = mcp_write_denied() + if denied: + return denied + settings = _settings() + if settings.storage_backend == "db": + return { + "status": "noop", + "detail": "Database mode publishes changes when a changeset is applied; there is nothing to commit.", + } return _git().commit(CommitRequest(summary=summary, details=details, files=files)) -def update_doc(path: str, content: str, summary: str, reason: str = "") -> dict[str, Any]: +def update_doc( + path: str, content: str, summary: str, reason: str = "", is_user: bool = False +) -> dict[str, Any]: """For simple full-document updates: create pending change, apply, validate, and commit in one call.""" - change = propose_doc_change(path=path, content=content, summary=summary, reason=reason) + change = propose_doc_change( + path=path, content=content, summary=summary, reason=reason, is_user=is_user + ) + if "error" in change: + return change change_id = str(change["id"]) pending_path = f"90-maintenance/pending-changes/{change_id}.json" try: - applied = apply_pending_change(change_id) - commit = commit_changes(summary=summary, files=[path, pending_path], details=reason) + applied = apply_pending_change(change_id, is_user=is_user) + if _settings().storage_backend == "db": + return { + "change": applied, + "commit": { + "status": "applied", + "detail": "Database mode publishes the changeset on apply.", + }, + } + commit = commit_changes( + summary=summary, files=[path, pending_path], details=reason + ) except Exception as exc: - # Full rollback: never leave the pending JSON behind after a failed update_doc. + # Full rollback: never leave the pending file or draft changeset behind. try: delete_pending_change(change_id) except Exception: pass raise RuntimeError( - f"update_doc failed; pending change {change_id} was cleaned up (deleted if still pending). " - f"Original error: {type(exc).__name__}: {exc}" + f"update_doc failed; pending change {change_id} was cleaned up " + f"(deleted if still pending). Original error: " + f"{type(exc).__name__}: {exc}" ) from exc return {"change": applied, "commit": commit} +def document_history(path: str) -> list[dict[str, Any]]: + """List document versions with author, actor, changeset, and summary metadata.""" + settings = _settings() + if settings.storage_backend != "db": + raise RuntimeError("Document history is available in database mode") + return list_document_versions(Database.from_settings(settings), path) + + +def document_version(path: str, version_no: int) -> dict[str, Any]: + """Read one document version by path and version number.""" + settings = _settings() + if settings.storage_backend != "db": + raise RuntimeError("Document versions are available in database mode") + return get_document_version(Database.from_settings(settings), path, version_no) + + +def document_diff( + path: str, + from_version: int | None = None, + to_version: int | None = None, +) -> dict[str, Any]: + """Show a unified diff between two document versions; defaults to the latest pair.""" + settings = _settings() + if settings.storage_backend != "db": + raise RuntimeError("Document diff is available in database mode") + return diff_document_versions( + Database.from_settings(settings), path, from_version, to_version + ) + + +def restore_document_version( + path: str, version_no: int, summary: str = "", is_user: bool = False +) -> dict[str, Any]: + """Restore a document by creating a new version with the content of an older version.""" + denied = mcp_write_denied() + if denied: + return denied + settings = _settings() + if settings.storage_backend != "db": + raise RuntimeError("Document restore is available in database mode") + return restore_document_version_service( + Database.from_settings(settings), + settings, + path, + version_no, + summary=summary or None, + via="mcp", + actor=mcp_actor(is_user), + ) + + +def build_transport_security(settings: Settings) -> TransportSecuritySettings: + return TransportSecuritySettings( + enable_dns_rebinding_protection=True, + allowed_hosts=list(settings.mcp_allowed_hosts), + allowed_origins=list(settings.mcp_allowed_origins), + ) + + mcp = FastMCP( "gnexus-book", instructions=MCP_INSTRUCTIONS, host=os.environ.get("GNEXUS_BOOK_MCP_HOST", "127.0.0.1"), port=int(os.environ.get("GNEXUS_BOOK_MCP_PORT", "8001")), + streamable_http_path="/mcp-protocol/", + transport_security=build_transport_security(Settings()), ) @@ -313,6 +453,10 @@ mcp.tool(name="apply_pending_change")(apply_pending_change) mcp.tool(name="commit_changes")(commit_changes) mcp.tool(name="update_doc")(update_doc) +mcp.tool(name="document_history")(document_history) +mcp.tool(name="document_version")(document_version) +mcp.tool(name="document_diff")(document_diff) +mcp.tool(name="restore_document_version")(restore_document_version) @mcp.resource("gnexus-book://docs", mime_type="application/json") @@ -364,6 +508,11 @@ transport = os.environ.get("GNEXUS_BOOK_MCP_TRANSPORT", "stdio") if transport not in {"stdio", "sse", "streamable-http"}: raise SystemExit("GNEXUS_BOOK_MCP_TRANSPORT must be stdio, sse, or streamable-http") + if transport == "streamable-http": + from .mcp_http import run + + run() + return mcp.run(transport=transport) # type: ignore[arg-type] diff --git a/server/app/pending_changes.py b/server/app/pending_changes.py index 0f48aa3..690f0de 100644 --- a/server/app/pending_changes.py +++ b/server/app/pending_changes.py @@ -81,7 +81,10 @@ ) return record - def create(self, request: ProposedChangeRequest) -> dict[str, Any]: + def create( + self, request: ProposedChangeRequest, actor: Any | None = None + ) -> dict[str, Any]: + self._require_file_backend() now = datetime.now(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z") change = PendingChange( id=self._new_id(), @@ -102,7 +105,8 @@ ) return change.model_dump() - def apply(self, change_id: str) -> dict[str, Any]: + def apply(self, change_id: str, actor: Any | None = None) -> dict[str, Any]: + self._require_file_backend() change = self.get(change_id) if change["status"] == "corrupt": raise PendingChangeError( @@ -251,6 +255,13 @@ except OSError: pass + def _require_file_backend(self) -> None: + if self.settings.storage_backend == "db": + raise PendingChangeError( + "Write path is not available in database mode yet; use the " + "database changeset repository" + ) + def _new_id(self) -> str: return datetime.now(UTC).strftime("%Y%m%d%H%M%S") + "-" + uuid4().hex[:8] diff --git a/server/app/storage/__init__.py b/server/app/storage/__init__.py new file mode 100644 index 0000000..7639ad4 --- /dev/null +++ b/server/app/storage/__init__.py @@ -0,0 +1,16 @@ +"""PostgreSQL storage layer for Gnexus Book.""" + +from .db import Database, DatabaseError +from .factory import ( + make_docs_repository, + make_inventory_repository, + make_pending_change_repository, +) + +__all__ = [ + "Database", + "DatabaseError", + "make_docs_repository", + "make_inventory_repository", + "make_pending_change_repository", +] diff --git a/server/app/storage/cli.py b/server/app/storage/cli.py new file mode 100644 index 0000000..9b43166 --- /dev/null +++ b/server/app/storage/cli.py @@ -0,0 +1,192 @@ +from __future__ import annotations + +import argparse +import json +from pathlib import Path +from typing import Sequence + +from ..config import Settings +from .db import Database, DatabaseError +from .importer import ( + database_counts, + database_manifest, + import_file_repository, + verify_import, +) +from .ownership import assign_owner_from_json, ownership_counts +from .parity import compare_repositories + + +def _database_settings(args: argparse.Namespace) -> Settings: + base = Settings() + database_url = args.database_url or base.database_url + if not database_url: + raise SystemExit( + "Set GNEXUS_BOOK_DATABASE_URL or pass --database-url " + "(for example postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book)" + ) + return Settings( + repo_root=base.repo_root, + database_url=database_url, + storage_backend="db", + ) + + +def _add_common(parser: argparse.ArgumentParser) -> None: + parser.add_argument( + "--database-url", + default=None, + help="PostgreSQL URL; defaults to GNEXUS_BOOK_DATABASE_URL", + ) + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser( + prog="python -m app.storage.cli", + description="Import and compare the file-backed knowledge base and PostgreSQL.", + ) + subparsers = parser.add_subparsers(dest="command", required=True) + + import_parser = subparsers.add_parser("import", help="Import the file repository into PostgreSQL") + _add_common(import_parser) + import_parser.add_argument("--replace", action="store_true", help="Clear existing data first") + import_parser.add_argument("--dry-run", action="store_true", help="Count without writing") + + migrate_parser = subparsers.add_parser( + "migrate", + help="Import the file repository, validate it and reconcile both backends", + ) + _add_common(migrate_parser) + migrate_parser.add_argument( + "--replace", action="store_true", help="Clear existing data first" + ) + migrate_parser.add_argument( + "--manifest", + default=None, + help="Write the import, verification and reconciliation report to this path", + ) + migrate_parser.add_argument( + "--query", + action="append", + default=None, + help="Search query to compare; repeatable", + ) + + parity_parser = subparsers.add_parser("parity", help="Compare file and database read results") + _add_common(parity_parser) + parity_parser.add_argument( + "--query", + action="append", + default=None, + help="Search query to compare; repeatable", + ) + + counts_parser = subparsers.add_parser("counts", help="Print database row counts") + _add_common(counts_parser) + + ownership_parser = subparsers.add_parser( + "ownership", help="Print owned/unowned document and inventory counts" + ) + _add_common(ownership_parser) + + assign_parser = subparsers.add_parser( + "assign-owner", help="Create/update an owner and assign unowned data" + ) + _add_common(assign_parser) + assign_parser.add_argument( + "--user-json", + required=True, + help="JSON file with sub, email, system_role, status and profile", + ) + assign_parser.add_argument( + "--all", + action="store_true", + help="Reassign all data, not only rows without an owner", + ) + + return parser + + +def main(argv: Sequence[str] | None = None) -> int: + parser = build_parser() + args = parser.parse_args(argv) + settings = _database_settings(args) + database = Database.from_settings(settings) + + try: + if args.command == "import": + report = import_file_repository( + settings, + database, + replace=args.replace, + dry_run=args.dry_run, + ) + print(json.dumps(report.as_dict(), indent=2)) + return 0 + + if args.command == "migrate": + report = import_file_repository( + settings, + database, + replace=args.replace, + ) + verification = verify_import(settings, database) + reconciliation = compare_repositories( + settings, database, queries=args.query + ) + db_manifest, db_manifest_digest = database_manifest(database) + payload = { + "source_revision": verification.get("source_revision"), + "import": report.as_dict(), + "verification": verification, + "reconciliation": reconciliation, + "database_manifest_digest": db_manifest_digest, + } + if args.manifest: + manifest_path = Path(args.manifest) + manifest_path.parent.mkdir(parents=True, exist_ok=True) + manifest_path.write_text( + json.dumps( + {**payload, "database_manifest": db_manifest}, + indent=2, + ensure_ascii=False, + ) + + "\n", + encoding="utf-8", + ) + print(json.dumps(payload, indent=2, ensure_ascii=False)) + return 0 if verification["ok"] and reconciliation["ok"] else 1 + + if args.command == "counts": + print(json.dumps(database_counts(database), indent=2)) + return 0 + + if args.command == "ownership": + print(json.dumps(ownership_counts(database), indent=2)) + return 0 + + if args.command == "assign-owner": + result = assign_owner_from_json( + database, args.user_json, all_data=args.all + ) + print( + json.dumps( + {"assignment": result, "ownership": ownership_counts(database)}, + indent=2, + ) + ) + return 0 + + if args.command == "parity": + result = compare_repositories(settings, database, queries=args.query) + print(json.dumps(result, indent=2, ensure_ascii=False)) + return 0 if result["ok"] else 1 + except (DatabaseError, ValueError) as exc: + print(f"error: {exc}") + return 2 + + parser.error(f"unknown command {args.command}") + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/server/app/storage/db.py b/server/app/storage/db.py new file mode 100644 index 0000000..1db95f6 --- /dev/null +++ b/server/app/storage/db.py @@ -0,0 +1,41 @@ +from __future__ import annotations + +from functools import lru_cache + +from sqlalchemy import Engine, create_engine +from sqlalchemy.orm import Session, sessionmaker + +from ..config import Settings + + +class DatabaseError(RuntimeError): + pass + + +@lru_cache(maxsize=8) +def _engine_for_url(url: str) -> Engine: + return create_engine(url, pool_pre_ping=True, future=True) + + +class Database: + def __init__(self, url: str) -> None: + self.url = url + self.engine = _engine_for_url(url) + self.session_factory = sessionmaker(bind=self.engine, expire_on_commit=False, future=True) + + @classmethod + def from_settings(cls, settings: Settings) -> "Database": + if not settings.database_url: + raise DatabaseError( + "GNEXUS_BOOK_DATABASE_URL is required when storage backend is 'db'" + ) + return cls(settings.database_url) + + def session(self) -> Session: + return self.session_factory() + + def ping(self) -> None: + from sqlalchemy import text + + with self.engine.connect() as connection: + connection.execute(text("SELECT 1")) diff --git a/server/app/storage/db_repositories.py b/server/app/storage/db_repositories.py new file mode 100644 index 0000000..561a438 --- /dev/null +++ b/server/app/storage/db_repositories.py @@ -0,0 +1,157 @@ +from __future__ import annotations + +from typing import Any + +import yaml +from sqlalchemy import and_, func, select +from sqlalchemy.orm import Session + +from ..docs_repository import RepositoryError +from ..inventory import InventoryError +from .db import Database +from .models import DocVersion, Document, InventoryItem, InventoryType + + +def _latest_doc_versions(): + return ( + select( + DocVersion.document_id.label("document_id"), + func.max(DocVersion.version_no).label("version_no"), + ) + .group_by(DocVersion.document_id) + .subquery() + ) + + +def latest_doc_rows(session: Session): + latest = _latest_doc_versions() + return ( + select(Document, DocVersion) + .join(latest, latest.c.document_id == Document.id) + .join( + DocVersion, + and_( + DocVersion.document_id == Document.id, + DocVersion.version_no == latest.c.version_no, + ), + ) + .where(Document.deleted_at.is_(None)) + .order_by(Document.slug) + ) + + +class PostgresDocsRepository: + def __init__(self, database: Database) -> None: + self.database = database + + def list_docs(self) -> list[dict[str, object]]: + with self.database.session() as session: + rows = sorted( + session.execute(latest_doc_rows(session)).all(), + key=lambda row: row[0].slug, + ) + return [ + { + "path": document.slug, + "title": document.title, + "frontmatter": dict(version.frontmatter or {}), + } + for document, version in rows + ] + + def read_doc(self, path: str) -> dict[str, object]: + with self.database.session() as session: + row = session.execute( + latest_doc_rows(session) + .where(Document.slug == path) + .limit(1) + ).first() + if row is None: + raise RepositoryError("Document not found") + document, version = row + return { + "path": document.slug, + "frontmatter": dict(version.frontmatter or {}), + "body": version.body, + "raw": version.raw, + } + + def search(self, query: str) -> list[dict[str, object]]: + normalized = query.strip().lower() + if not normalized: + return [] + + results: list[dict[str, object]] = [] + with self.database.session() as session: + rows = sorted( + session.execute(latest_doc_rows(session)).all(), + key=lambda row: row[0].slug, + ) + for document, version in rows: + matches = [] + for index, line in enumerate(version.raw.splitlines(), start=1): + if normalized in line.lower(): + matches.append({"line": index, "text": line.strip()}) + if len(matches) >= 5: + break + if matches: + results.append( + { + "path": document.slug, + "title": document.title, + "matches": matches, + } + ) + return results + + +class PostgresInventoryRepository: + def __init__(self, database: Database) -> None: + self.database = database + + def list_types(self) -> list[str]: + with self.database.session() as session: + return list(session.scalars(select(InventoryType.name).order_by(InventoryType.name))) + + def read_raw(self, inventory_type: str) -> str: + data = self.read_parsed(inventory_type) + return "---\n" + yaml.safe_dump(data, sort_keys=False, allow_unicode=True) + + def read_parsed(self, inventory_type: str) -> Any: + self._require_type(inventory_type) + with self.database.session() as session: + items = session.scalars( + select(InventoryItem) + .where( + InventoryItem.type == inventory_type, + InventoryItem.deleted_at.is_(None), + ) + .order_by(InventoryItem.position, InventoryItem.item_id) + ).all() + return [dict(item.data or {}) for item in items] + + def read_item(self, inventory_type: str, item_id: str) -> dict[str, Any]: + self._require_type(inventory_type) + with self.database.session() as session: + item = session.scalars( + select(InventoryItem) + .where( + InventoryItem.type == inventory_type, + InventoryItem.item_id == item_id, + InventoryItem.deleted_at.is_(None), + ) + .limit(1) + ).first() + if item is None: + raise InventoryError("Inventory item not found") + return dict(item.data or {}) + + def _require_type(self, inventory_type: str) -> None: + if "/" in inventory_type or "\\" in inventory_type or inventory_type.startswith("."): + raise InventoryError("Invalid inventory type") + with self.database.session() as session: + exists = session.scalar( + select(InventoryType.name).where(InventoryType.name == inventory_type) + ) + if exists is None: + raise InventoryError("Inventory type not found") diff --git a/server/app/storage/documents.py b/server/app/storage/documents.py new file mode 100644 index 0000000..c16fb89 --- /dev/null +++ b/server/app/storage/documents.py @@ -0,0 +1,172 @@ +from __future__ import annotations + +import difflib +from datetime import datetime +from typing import Any + +from sqlalchemy import select +from sqlalchemy.orm import Session + +from ..config import Settings +from ..pending_changes import ProposedChangeRequest +from .db import Database +from .models import Changeset, DocVersion, Document +from .pending_changes_db import PostgresPendingChangeRepository + + +class DocumentError(ValueError): + pass + + +def _iso(value: datetime | None) -> str | None: + if value is None: + return None + return value.isoformat().replace("+00:00", "Z") + + +def _find_document(session: Session, path: str) -> Document: + document = session.scalars(select(Document).where(Document.slug == path)).first() + if document is None or document.deleted_at is not None: + raise DocumentError("Document not found") + return document + + +def _find_version(session: Session, document_id, version_no: int) -> DocVersion: + version = session.scalars( + select(DocVersion).where( + DocVersion.document_id == document_id, + DocVersion.version_no == version_no, + ) + ).first() + if version is None: + raise DocumentError("Document version not found") + return version + + +def list_document_versions(database: Database, path: str) -> list[dict[str, Any]]: + with database.session() as session: + document = _find_document(session, path) + versions = session.scalars( + select(DocVersion) + .where(DocVersion.document_id == document.id) + .order_by(DocVersion.version_no) + ).all() + + result: list[dict[str, Any]] = [] + for version in versions: + changeset = ( + session.get(Changeset, version.changeset_id) + if version.changeset_id + else None + ) + result.append( + { + "path": document.slug, + "version_no": version.version_no, + "content_hash": version.content_hash, + "created_at": _iso(version.created_at), + "actor_kind": version.actor_kind, + "actor_name": version.actor_name, + "via": version.via, + "changeset_id": str(version.changeset_id) if version.changeset_id else None, + "summary": changeset.summary if changeset else None, + } + ) + return result + + +def get_document_version(database: Database, path: str, version_no: int) -> dict[str, Any]: + with database.session() as session: + document = _find_document(session, path) + version = _find_version(session, document.id, version_no) + changeset = ( + session.get(Changeset, version.changeset_id) if version.changeset_id else None + ) + return { + "path": document.slug, + "version_no": version.version_no, + "raw": version.raw, + "body": version.body, + "frontmatter": dict(version.frontmatter or {}), + "content_hash": version.content_hash, + "created_at": _iso(version.created_at), + "actor_kind": version.actor_kind, + "actor_name": version.actor_name, + "via": version.via, + "changeset_id": str(version.changeset_id) if version.changeset_id else None, + "summary": changeset.summary if changeset else None, + } + + +def diff_document_versions( + database: Database, + path: str, + from_version: int | None = None, + to_version: int | None = None, +) -> dict[str, Any]: + with database.session() as session: + document = _find_document(session, path) + versions = session.scalars( + select(DocVersion) + .where(DocVersion.document_id == document.id) + .order_by(DocVersion.version_no) + ).all() + if not versions: + raise DocumentError("Document has no versions") + + latest_no = versions[-1].version_no + target_no = latest_no if to_version is None else to_version + if from_version is None: + source_no = max(1, target_no - 1) + else: + source_no = from_version + + if source_no < 1 or target_no < 1: + raise DocumentError("Version numbers must be positive") + + source = _find_version(session, document.id, source_no) + target = _find_version(session, document.id, target_no) + + diff_lines = difflib.unified_diff( + source.raw.splitlines(), + target.raw.splitlines(), + fromfile=f"{path}@v{source_no}", + tofile=f"{path}@v{target_no}", + lineterm="", + ) + return { + "path": path, + "from_version": source_no, + "to_version": target_no, + "diff": "\n".join(diff_lines), + } + + +def restore_document_version( + database: Database, + settings: Settings, + path: str, + version_no: int, + summary: str | None = None, + via: str = "api", + actor: Any | None = None, +) -> dict[str, Any]: + with database.session() as session: + document = _find_document(session, path) + version = _find_version(session, document.id, version_no) + raw = version.raw + + repository = PostgresPendingChangeRepository( + database, settings, via=via, default_actor=actor + ) + change = repository.create( + ProposedChangeRequest( + kind="doc", + target=path, + summary=summary or f"Restore {path} to version {version_no}", + reason=f"Restore version {version_no}", + payload={"content": raw}, + ), + actor=actor, + ) + return repository.apply(change["id"], actor=actor) diff --git a/server/app/storage/factory.py b/server/app/storage/factory.py new file mode 100644 index 0000000..1b1eb5d --- /dev/null +++ b/server/app/storage/factory.py @@ -0,0 +1,37 @@ +from __future__ import annotations + +from ..auth.actor import Actor +from ..config import Settings +from ..docs_repository import DocsRepository +from ..inventory import InventoryRepository +from ..pending_changes import PendingChangeRepository +from .db import Database +from .db_repositories import PostgresDocsRepository, PostgresInventoryRepository +from .pending_changes_db import PostgresPendingChangeRepository + + +def make_docs_repository(settings: Settings): + if settings.storage_backend == "db": + return PostgresDocsRepository(Database.from_settings(settings)) + return DocsRepository(settings) + + +def make_inventory_repository(settings: Settings): + if settings.storage_backend == "db": + return PostgresInventoryRepository(Database.from_settings(settings)) + return InventoryRepository(settings) + + +def make_pending_change_repository( + settings: Settings, + via: str = "api", + default_actor: Actor | None = None, +): + if settings.storage_backend == "db": + return PostgresPendingChangeRepository( + Database.from_settings(settings), + settings, + via=via, + default_actor=default_actor, + ) + return PendingChangeRepository(settings) diff --git a/server/app/storage/freshness.py b/server/app/storage/freshness.py new file mode 100644 index 0000000..b702c69 --- /dev/null +++ b/server/app/storage/freshness.py @@ -0,0 +1,78 @@ +from __future__ import annotations + +import posixpath +from typing import Any + +from sqlalchemy import select +from sqlalchemy.orm import Session + +from ..freshness import REQUIRED_FRONTMATTER, _is_stale +from .db import Database +from .db_repositories import latest_doc_rows +from .models import Document, InventoryItem + + +def build_freshness_report_db(database: Database) -> dict[str, object]: + with database.session() as session: + return _build_report(session) + + +def _build_report(session: Session) -> dict[str, object]: + issues: list[dict[str, str]] = [] + documents = session.execute(latest_doc_rows(session)).all() + + for document, version in documents: + slug = document.slug + if slug == "README.md" or slug.startswith("server/"): + continue + + frontmatter = version.frontmatter or {} + missing = sorted(REQUIRED_FRONTMATTER - set(frontmatter)) + if missing: + issues.append( + { + "path": slug, + "severity": "warning", + "code": "missing-frontmatter-fields", + "message": "Missing frontmatter fields: " + ", ".join(missing), + } + ) + continue + + if _is_stale(str(frontmatter["last_reviewed"]), str(frontmatter["review_interval"])): + issues.append( + { + "path": slug, + "severity": "warning", + "code": "stale-document", + "message": "Document is past its review interval", + } + ) + + document_slugs = set(session.scalars(select(Document.slug)).all()) + items = session.scalars( + select(InventoryItem) + .where(InventoryItem.deleted_at.is_(None)) + .order_by(InventoryItem.type, InventoryItem.position, InventoryItem.item_id) + ).all() + for item in items: + docs_value = (item.data or {}).get("docs") + if not isinstance(docs_value, str) or not docs_value: + continue + target = posixpath.normpath(posixpath.join("40-inventory", docs_value)) + if target not in document_slugs: + issues.append( + { + "path": f"40-inventory/{item.type}.yml", + "severity": "error", + "code": "missing-doc-link-target", + "message": f"docs target does not exist: {docs_value}", + } + ) + + return { + "status": "ok" if not issues else "issues", + "document_count": len(documents), + "issue_count": len(issues), + "issues": issues, + } diff --git a/server/app/storage/importer.py b/server/app/storage/importer.py new file mode 100644 index 0000000..0b3ac68 --- /dev/null +++ b/server/app/storage/importer.py @@ -0,0 +1,452 @@ +from __future__ import annotations + +import hashlib +import json +import subprocess +from dataclasses import asdict, dataclass +from datetime import UTC, date, datetime +from pathlib import Path +from typing import Any + +from sqlalchemy import delete, func, select + +from ..config import Settings +from ..docs_repository import DocsRepository +from ..inventory import InventoryError, InventoryRepository +from ..validation import SCHEMA_BY_INVENTORY +from .db import Database, DatabaseError +from .db_repositories import latest_doc_rows +from .validation import validate_session +from .models import ( + AuditLog, + Blob, + ChangeItem, + Changeset, + DocVersion, + Document, + InventoryItem, + InventoryItemVersion, + InventoryType, + JsonSchema, + ValidationRun, + utcnow, +) + + +@dataclass(frozen=True) +class ImportReport: + documents: int + doc_versions: int + inventory_types: int + inventory_items: int + schemas: int + dry_run: bool + source_revision: str | None = None + manifest_digest: str | None = None + + def as_dict(self) -> dict[str, Any]: + return asdict(self) + + +@dataclass(frozen=True) +class _DocSource: + path: str + title: str + raw: str + body: str + frontmatter: dict[str, Any] + + +@dataclass(frozen=True) +class _InventorySource: + type_name: str + items: list[tuple[int, str, dict[str, Any]]] + + +def normalize_scalars(value: Any) -> Any: + if isinstance(value, (date, datetime)): + return value.isoformat() + if isinstance(value, list): + return [normalize_scalars(item) for item in value] + if isinstance(value, tuple): + return [normalize_scalars(item) for item in value] + if isinstance(value, dict): + return {key: normalize_scalars(item) for key, item in value.items()} + return value + + +def _collect_docs(settings: Settings) -> list[_DocSource]: + repo = DocsRepository(settings) + sources: list[_DocSource] = [] + for doc in repo.list_docs(): + path = str(doc["path"]) + record = repo.read_doc(path) + sources.append( + _DocSource( + path=path, + title=str(doc["title"]), + raw=str(record["raw"]), + body=str(record["body"]), + frontmatter=dict(record["frontmatter"]), + ) + ) + return sources + + +def _collect_inventory(settings: Settings) -> list[_InventorySource]: + repo = InventoryRepository(settings) + sources: list[_InventorySource] = [] + for type_name in repo.list_types(): + parsed = repo.read_parsed(type_name) + if not isinstance(parsed, list): + raise InventoryError(f"Inventory type {type_name} does not contain a list") + items: list[tuple[int, str, dict[str, Any]]] = [] + for position, item in enumerate(parsed): + if not isinstance(item, dict): + continue + item_id = item.get("id") + if not isinstance(item_id, str) or not item_id: + raise InventoryError( + f"Inventory type {type_name} has an item without a string id at index {position}" + ) + items.append((position, item_id, normalize_scalars(item))) + sources.append(_InventorySource(type_name=type_name, items=items)) + return sources + + +def _collect_schemas(settings: Settings) -> dict[str, dict[str, Any]]: + schemas: dict[str, dict[str, Any]] = {} + for path in sorted((settings.repo_root / "schemas").glob("*.json")): + schemas[path.name] = json.loads(path.read_text(encoding="utf-8")) + return schemas + + +def _content_hash(raw: str) -> str: + return hashlib.sha256(raw.encode("utf-8")).hexdigest() + + +def _canonical_json(value: Any) -> str: + return json.dumps( + normalize_scalars(value), + sort_keys=True, + ensure_ascii=False, + separators=(",", ":"), + ) + + +def _source_revision(repo_root: Path) -> str | None: + try: + result = subprocess.run( + ["git", "-C", str(repo_root), "rev-parse", "HEAD"], + check=False, + capture_output=True, + text=True, + ) + except OSError: + return None + if result.returncode != 0: + return None + return result.stdout.strip() or None + + +def _manifest_from_sources( + docs: list[_DocSource], + inventory: list[_InventorySource], + schemas: dict[str, dict[str, Any]], +) -> tuple[dict[str, Any], str]: + manifest = { + "documents": {source.path: _content_hash(source.raw) for source in docs}, + "inventory": { + source.type_name: { + item_id: hashlib.sha256(_canonical_json(data).encode("utf-8")).hexdigest() + for _, item_id, data in source.items + } + for source in inventory + }, + "schemas": { + name: hashlib.sha256(_canonical_json(body).encode("utf-8")).hexdigest() + for name, body in schemas.items() + }, + } + digest = hashlib.sha256(_canonical_json(manifest).encode("utf-8")).hexdigest() + return manifest, digest + + +def _clear_database(session) -> None: + for model in ( + AuditLog, + ValidationRun, + ChangeItem, + InventoryItemVersion, + DocVersion, + Changeset, + InventoryItem, + InventoryType, + JsonSchema, + Document, + Blob, + ): + session.execute(delete(model)) + + +def import_file_repository( + settings: Settings, + database: Database, + replace: bool = False, + dry_run: bool = False, +) -> ImportReport: + source_settings = Settings(repo_root=settings.repo_root, storage_backend="file") + docs = _collect_docs(source_settings) + inventory = _collect_inventory(source_settings) + schemas = _collect_schemas(source_settings) + _, manifest_digest = _manifest_from_sources(docs, inventory, schemas) + source_revision = _source_revision(settings.repo_root) + + report = ImportReport( + documents=len(docs), + doc_versions=len(docs), + inventory_types=len(inventory), + inventory_items=sum(len(source.items) for source in inventory), + schemas=len(schemas), + dry_run=dry_run, + source_revision=source_revision, + manifest_digest=manifest_digest, + ) + if dry_run: + return report + + with database.session() as session: + with session.begin(): + existing = session.scalar(select(func.count()).select_from(Document)) or 0 + if existing and not replace: + raise DatabaseError( + "Database already contains documents; pass replace=True to re-import" + ) + if replace: + _clear_database(session) + + import_reason = "Initial import of the Markdown and YAML knowledge base" + if source_revision: + import_reason += f" from source revision {source_revision}" + changeset = Changeset( + summary="Import knowledge base from file backend", + reason=import_reason, + status="applied", + applied_at=utcnow(), + ) + session.add(changeset) + session.flush() + + schema_rows: dict[str, JsonSchema] = {} + for name, body in schemas.items(): + row = JsonSchema(name=name, version=1, body=body) + session.add(row) + schema_rows[name] = row + session.flush() + + seen_hashes: set[str] = set() + for source in docs: + document = Document(slug=source.path, title=source.title) + session.add(document) + session.flush() + + content_hash = _content_hash(source.raw) + if content_hash not in seen_hashes and session.get(Blob, content_hash) is None: + session.add( + Blob(hash=content_hash, content=source.raw, size=len(source.raw)) + ) + seen_hashes.add(content_hash) + + session.add( + DocVersion( + document_id=document.id, + version_no=1, + parent_version_id=None, + content_hash=content_hash, + raw=source.raw, + body=source.body, + frontmatter=source.frontmatter, + actor_kind="system", + actor_name="importer", + via="import", + changeset_id=changeset.id, + ) + ) + + for source in inventory: + schema_name = SCHEMA_BY_INVENTORY.get(source.type_name) + schema_row = schema_rows.get(schema_name) if schema_name else None + session.add( + InventoryType( + name=source.type_name, + schema_id=schema_row.id if schema_row else None, + ) + ) + session.flush() + + for source in inventory: + for position, item_id, data in source.items: + item = InventoryItem( + type=source.type_name, + item_id=item_id, + position=position, + data=data, + ) + session.add(item) + session.flush() + session.add( + InventoryItemVersion( + inventory_item_id=item.id, + version_no=1, + data=data, + changeset_id=changeset.id, + ) + ) + + session.flush() + validation = validate_session(session) + if validation["status"] != "ok": + details = "\n".join( + f" - {issue['path']} ({issue['code']}): {issue['message']}" + for issue in validation.get("issues", [])[:10] + ) + raise ValueError( + "Imported repository failed validation:\n" + details + ) + changeset.validation = validation + + session.add( + AuditLog( + actor_kind="system", + actor_name="importer", + via="import", + action="import", + entity_type="repository", + entity_id=str(changeset.id), + after=report.as_dict(), + ) + ) + + return report + + +def database_manifest(database: Database) -> tuple[dict[str, Any], str]: + with database.session() as session: + documents = { + document.slug: version.content_hash + for document, version in session.execute(latest_doc_rows(session)).all() + } + inventory: dict[str, dict[str, str]] = {} + for item in session.scalars( + select(InventoryItem).where(InventoryItem.deleted_at.is_(None)) + ).all(): + inventory.setdefault(item.type, {})[item.item_id] = hashlib.sha256( + _canonical_json(item.data or {}).encode("utf-8") + ).hexdigest() + schemas: dict[str, str] = {} + for schema in session.scalars( + select(JsonSchema).order_by(JsonSchema.name, JsonSchema.version.desc()) + ).all(): + schemas.setdefault( + schema.name, + hashlib.sha256(_canonical_json(schema.body).encode("utf-8")).hexdigest(), + ) + manifest = { + "documents": documents, + "inventory": inventory, + "schemas": schemas, + } + digest = hashlib.sha256(_canonical_json(manifest).encode("utf-8")).hexdigest() + return manifest, digest + + +def verify_import(settings: Settings, database: Database) -> dict[str, Any]: + source_settings = Settings(repo_root=settings.repo_root, storage_backend="file") + docs = _collect_docs(source_settings) + inventory = _collect_inventory(source_settings) + schemas = _collect_schemas(source_settings) + file_manifest, file_digest = _manifest_from_sources(docs, inventory, schemas) + database_manifest_data, database_digest = database_manifest(database) + + differences: list[dict[str, Any]] = [] + for section in ("documents", "schemas"): + file_entries = file_manifest[section] + database_entries = database_manifest_data[section] + for key in sorted(set(file_entries) - set(database_entries)): + differences.append( + {"section": section, "key": key, "issue": "missing_in_database"} + ) + for key in sorted(set(database_entries) - set(file_entries)): + differences.append( + {"section": section, "key": key, "issue": "missing_in_files"} + ) + for key in sorted(set(file_entries) & set(database_entries)): + if file_entries[key] != database_entries[key]: + differences.append( + {"section": section, "key": key, "issue": "hash_mismatch"} + ) + + file_inventory = file_manifest["inventory"] + database_inventory = database_manifest_data["inventory"] + for type_name in sorted(set(file_inventory) | set(database_inventory)): + file_items = file_inventory.get(type_name, {}) + database_items = database_inventory.get(type_name, {}) + for item_id in sorted(set(file_items) - set(database_items)): + differences.append( + { + "section": "inventory", + "key": f"{type_name}/{item_id}", + "issue": "missing_in_database", + } + ) + for item_id in sorted(set(database_items) - set(file_items)): + differences.append( + { + "section": "inventory", + "key": f"{type_name}/{item_id}", + "issue": "missing_in_files", + } + ) + for item_id in sorted(set(file_items) & set(database_items)): + if file_items[item_id] != database_items[item_id]: + differences.append( + { + "section": "inventory", + "key": f"{type_name}/{item_id}", + "issue": "hash_mismatch", + } + ) + + db_counts = database_counts(database) + file_counts = { + "documents": len(docs), + "inventory_types": len(inventory), + "inventory_items": sum(len(source.items) for source in inventory), + "schemas": len(schemas), + } + + return { + "ok": not differences, + "source_revision": source_revision(settings.repo_root), + "file_manifest_digest": file_digest, + "database_manifest_digest": database_digest, + "file_counts": file_counts, + "database_counts": db_counts, + "differences": differences, + } + + +def source_revision(repo_root: Path) -> str | None: + return _source_revision(repo_root) + + +def database_counts(database: Database) -> dict[str, int]: + with database.session() as session: + return { + "documents": session.scalar(select(func.count()).select_from(Document)) or 0, + "doc_versions": session.scalar(select(func.count()).select_from(DocVersion)) or 0, + "inventory_types": session.scalar(select(func.count()).select_from(InventoryType)) or 0, + "inventory_items": session.scalar(select(func.count()).select_from(InventoryItem)) or 0, + "schemas": session.scalar(select(func.count()).select_from(JsonSchema)) or 0, + "changesets": session.scalar(select(func.count()).select_from(Changeset)) or 0, + } diff --git a/server/app/storage/models.py b/server/app/storage/models.py new file mode 100644 index 0000000..c59031e --- /dev/null +++ b/server/app/storage/models.py @@ -0,0 +1,337 @@ +from __future__ import annotations + +import uuid +from datetime import UTC, datetime +from typing import Any + +from sqlalchemy import ( + CheckConstraint, + DateTime, + ForeignKey, + Index, + Integer, + Text, + UniqueConstraint, + text, +) +from sqlalchemy.dialects.postgresql import JSONB, UUID +from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column + + +def utcnow() -> datetime: + return datetime.now(UTC) + + +class Base(DeclarativeBase): + pass + + +class User(Base): + """Mirror of a gnexus-auth principal. Real values are populated in Phase 4.""" + + __tablename__ = "users" + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + sub: Mapped[str] = mapped_column(Text, unique=True, nullable=False) + email: Mapped[str | None] = mapped_column(Text) + display_name: Mapped[str | None] = mapped_column(Text) + profile: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict) + locale: Mapped[str | None] = mapped_column(Text) + system_role: Mapped[str | None] = mapped_column(Text) + status: Mapped[str | None] = mapped_column(Text) + client_roles: Mapped[list[str]] = mapped_column( + JSONB, nullable=False, default=list, server_default=text("'[]'::jsonb") + ) + permissions: Mapped[list[str]] = mapped_column( + JSONB, nullable=False, default=list, server_default=text("'[]'::jsonb") + ) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + updated_at: Mapped[datetime] = mapped_column( + DateTime(timezone=True), nullable=False, default=utcnow, onupdate=utcnow + ) + blocked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + + +class UserSession(Base): + __tablename__ = "user_sessions" + __table_args__ = (Index("ix_user_sessions_user_id", "user_id"),) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + user_id: Mapped[uuid.UUID] = mapped_column( + UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False + ) + token_hash: Mapped[str] = mapped_column(Text, unique=True, nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False) + last_used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + user_agent: Mapped[str | None] = mapped_column(Text) + ip_address: Mapped[str | None] = mapped_column(Text) + + +class McpToken(Base): + __tablename__ = "mcp_tokens" + __table_args__ = ( + Index( + "uq_mcp_tokens_user_consumer_active", + "user_id", + "consumer", + unique=True, + postgresql_where=text("revoked_at IS NULL"), + ), + Index("ix_mcp_tokens_user_id", "user_id"), + ) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + user_id: Mapped[uuid.UUID] = mapped_column( + UUID(as_uuid=True), ForeignKey("users.id", ondelete="CASCADE"), nullable=False + ) + consumer: Mapped[str] = mapped_column(Text, nullable=False) + name: Mapped[str] = mapped_column(Text, nullable=False) + role: Mapped[str | None] = mapped_column(Text) + scopes: Mapped[list[str]] = mapped_column( + JSONB, nullable=False, default=list, server_default=text("'[]'::jsonb") + ) + token_hash: Mapped[str] = mapped_column(Text, unique=True, nullable=False) + token_hint: Mapped[str] = mapped_column(Text, nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + last_used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + revoked_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + stale_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + + +class OAuthState(Base): + __tablename__ = "oauth_states" + + state_hash: Mapped[str] = mapped_column(Text, primary_key=True) + code_verifier: Mapped[str | None] = mapped_column(Text) + return_to: Mapped[str | None] = mapped_column(Text) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + expires_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False) + + +class WebhookEvent(Base): + __tablename__ = "webhook_events" + + id: Mapped[str] = mapped_column(Text, primary_key=True) + event_type: Mapped[str] = mapped_column(Text, nullable=False) + received_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict) + + +class Blob(Base): + __tablename__ = "blobs" + + hash: Mapped[str] = mapped_column(Text, primary_key=True) + content: Mapped[str] = mapped_column(Text, nullable=False) + size: Mapped[int] = mapped_column(Integer, nullable=False) + + +class Changeset(Base): + __tablename__ = "changesets" + __table_args__ = ( + CheckConstraint( + "status IN ('draft', 'applied', 'rejected')", + name="ck_changesets_status", + ), + ) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + author_user_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), ForeignKey("users.id"), nullable=True + ) + summary: Mapped[str] = mapped_column(Text, nullable=False) + reason: Mapped[str] = mapped_column(Text, nullable=False, default="") + status: Mapped[str] = mapped_column(Text, nullable=False, default="draft") + actor_kind: Mapped[str] = mapped_column( + Text, nullable=False, default="system", server_default=text("'system'") + ) + actor_name: Mapped[str | None] = mapped_column(Text) + via: Mapped[str] = mapped_column( + Text, nullable=False, default="import", server_default=text("'import'") + ) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + applied_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + validation: Mapped[dict[str, Any] | None] = mapped_column(JSONB) + + +class ChangeItem(Base): + __tablename__ = "change_items" + __table_args__ = ( + CheckConstraint( + "kind IN ('doc', 'inventory', 'inventory-item')", + name="ck_change_items_kind", + ), + CheckConstraint( + "status IN ('draft', 'applied', 'rejected')", + name="ck_change_items_status", + ), + ) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + changeset_id: Mapped[uuid.UUID] = mapped_column( + UUID(as_uuid=True), ForeignKey("changesets.id", ondelete="CASCADE"), nullable=False + ) + kind: Mapped[str] = mapped_column(Text, nullable=False) + target: Mapped[str] = mapped_column(Text, nullable=False) + payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict) + status: Mapped[str] = mapped_column(Text, nullable=False, default="draft") + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + + +class Document(Base): + __tablename__ = "documents" + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + slug: Mapped[str] = mapped_column(Text, unique=True, nullable=False) + title: Mapped[str] = mapped_column(Text, nullable=False) + owner_user_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), + ForeignKey("users.id", ondelete="SET NULL"), + nullable=True, + index=True, + ) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + deleted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + + +class DocVersion(Base): + __tablename__ = "doc_versions" + __table_args__ = ( + UniqueConstraint("document_id", "version_no", name="uq_doc_versions_document_version"), + Index("ix_doc_versions_content_hash", "content_hash"), + ) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + document_id: Mapped[uuid.UUID] = mapped_column( + UUID(as_uuid=True), ForeignKey("documents.id", ondelete="CASCADE"), nullable=False + ) + version_no: Mapped[int] = mapped_column(Integer, nullable=False) + parent_version_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), ForeignKey("doc_versions.id"), nullable=True + ) + content_hash: Mapped[str] = mapped_column(Text, nullable=False) + raw: Mapped[str] = mapped_column(Text, nullable=False) + body: Mapped[str] = mapped_column(Text, nullable=False) + frontmatter: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict) + author_user_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), ForeignKey("users.id"), nullable=True + ) + actor_kind: Mapped[str] = mapped_column(Text, nullable=False, default="system") + actor_name: Mapped[str | None] = mapped_column(Text) + via: Mapped[str] = mapped_column(Text, nullable=False, default="import") + changeset_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), ForeignKey("changesets.id"), nullable=True + ) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + + +class JsonSchema(Base): + __tablename__ = "schemas" + __table_args__ = (UniqueConstraint("name", "version", name="uq_schemas_name_version"),) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + name: Mapped[str] = mapped_column(Text, nullable=False) + version: Mapped[int] = mapped_column(Integer, nullable=False, default=1) + body: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + + +class InventoryType(Base): + __tablename__ = "inventory_types" + + name: Mapped[str] = mapped_column(Text, primary_key=True) + schema_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), ForeignKey("schemas.id"), nullable=True + ) + + +class InventoryItem(Base): + __tablename__ = "inventory_items" + __table_args__ = ( + Index( + "uq_inventory_items_type_item_live", + "type", + "item_id", + unique=True, + postgresql_where=text("deleted_at IS NULL"), + ), + Index("ix_inventory_items_type_position", "type", "position"), + ) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + type: Mapped[str] = mapped_column( + Text, ForeignKey("inventory_types.name"), nullable=False + ) + item_id: Mapped[str] = mapped_column(Text, nullable=False) + position: Mapped[int] = mapped_column(Integer, nullable=False, default=0) + data: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict) + owner_user_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), + ForeignKey("users.id", ondelete="SET NULL"), + nullable=True, + index=True, + ) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + deleted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True)) + + +class InventoryItemVersion(Base): + __tablename__ = "inventory_item_versions" + __table_args__ = ( + UniqueConstraint( + "inventory_item_id", "version_no", name="uq_inventory_item_versions_item_version" + ), + ) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + inventory_item_id: Mapped[uuid.UUID] = mapped_column( + UUID(as_uuid=True), ForeignKey("inventory_items.id", ondelete="CASCADE"), nullable=False + ) + version_no: Mapped[int] = mapped_column(Integer, nullable=False) + data: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, default=dict) + author_user_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), ForeignKey("users.id"), nullable=True + ) + changeset_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), ForeignKey("changesets.id"), nullable=True + ) + actor_kind: Mapped[str] = mapped_column( + Text, nullable=False, default="system", server_default=text("'system'") + ) + actor_name: Mapped[str | None] = mapped_column(Text) + via: Mapped[str] = mapped_column( + Text, nullable=False, default="import", server_default=text("'import'") + ) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + + +class ValidationRun(Base): + __tablename__ = "validation_runs" + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + changeset_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), ForeignKey("changesets.id"), nullable=True + ) + status: Mapped[str] = mapped_column(Text, nullable=False) + issues: Mapped[list[dict[str, Any]]] = mapped_column(JSONB, nullable=False, default=list) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) + + +class AuditLog(Base): + __tablename__ = "audit_log" + __table_args__ = (Index("ix_audit_log_created_at", "created_at"),) + + id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4) + actor_user_id: Mapped[uuid.UUID | None] = mapped_column( + UUID(as_uuid=True), ForeignKey("users.id"), nullable=True + ) + actor_kind: Mapped[str] = mapped_column(Text, nullable=False, default="system") + actor_name: Mapped[str | None] = mapped_column(Text) + via: Mapped[str] = mapped_column(Text, nullable=False, default="import") + action: Mapped[str] = mapped_column(Text, nullable=False) + entity_type: Mapped[str] = mapped_column(Text, nullable=False) + entity_id: Mapped[str] = mapped_column(Text, nullable=False) + before: Mapped[dict[str, Any] | None] = mapped_column(JSONB) + after: Mapped[dict[str, Any] | None] = mapped_column(JSONB) + created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False, default=utcnow) diff --git a/server/app/storage/ownership.py b/server/app/storage/ownership.py new file mode 100644 index 0000000..a0402f7 --- /dev/null +++ b/server/app/storage/ownership.py @@ -0,0 +1,141 @@ +from __future__ import annotations + +import json +from pathlib import Path +from typing import Any + +from sqlalchemy import func, select, update + +from .db import Database +from .models import AuditLog, Document, InventoryItem, User, utcnow + + +def assign_owner( + database: Database, + *, + sub: str, + email: str | None = None, + display_name: str | None = None, + system_role: str | None = None, + status: str | None = None, + profile: dict[str, Any] | None = None, + all_data: bool = False, +) -> dict[str, Any]: + """Create or update the owner mirror and assign unowned data to it.""" + if not sub: + raise ValueError("sub is required") + + with database.session() as session: + with session.begin(): + user = session.scalars(select(User).where(User.sub == sub)).first() + if user is None: + user = User( + sub=sub, + email=email, + display_name=display_name or email or sub, + profile=dict(profile or {}), + system_role=system_role, + status=status, + ) + session.add(user) + else: + if email: + user.email = email + if display_name: + user.display_name = display_name + if profile is not None: + user.profile = dict(profile) + if system_role: + user.system_role = system_role + if status: + user.status = status + user.updated_at = utcnow() + session.flush() + + document_query = update(Document).values(owner_user_id=user.id) + inventory_query = update(InventoryItem).values(owner_user_id=user.id) + if not all_data: + document_query = document_query.where(Document.owner_user_id.is_(None)) + inventory_query = inventory_query.where( + InventoryItem.owner_user_id.is_(None) + ) + + documents = session.execute(document_query).rowcount or 0 + inventory_items = session.execute(inventory_query).rowcount or 0 + counts = { + "documents": documents, + "inventory_items": inventory_items, + } + + if documents or inventory_items: + session.add( + AuditLog( + actor_user_id=user.id, + actor_kind="user", + actor_name=user.display_name or user.email or user.sub, + via="cli", + action="ownership.assigned", + entity_type="repository", + entity_id=sub, + after=counts, + ) + ) + + return { + "user_id": str(user.id), + "sub": user.sub, + **counts, + } + + +def assign_owner_from_json( + database: Database, path: str | Path, all_data: bool = False +) -> dict[str, Any]: + payload = json.loads(Path(path).read_text(encoding="utf-8")) + profile = payload.get("profile") or {} + return assign_owner( + database, + sub=str(payload["sub"]), + email=payload.get("email"), + display_name=profile.get("display_name") + or profile.get("username") + or payload.get("email"), + system_role=payload.get("system_role"), + status=payload.get("status"), + profile=profile, + all_data=all_data, + ) + + +def ownership_counts(database: Database) -> dict[str, dict[str, int]]: + with database.session() as session: + return { + "documents": { + "owned": session.scalar( + select(func.count()) + .select_from(Document) + .where(Document.owner_user_id.is_not(None)) + ) + or 0, + "unowned": session.scalar( + select(func.count()) + .select_from(Document) + .where(Document.owner_user_id.is_(None)) + ) + or 0, + }, + "inventory_items": { + "owned": session.scalar( + select(func.count()) + .select_from(InventoryItem) + .where(InventoryItem.owner_user_id.is_not(None)) + ) + or 0, + "unowned": session.scalar( + select(func.count()) + .select_from(InventoryItem) + .where(InventoryItem.owner_user_id.is_(None)) + ) + or 0, + }, + } diff --git a/server/app/storage/parity.py b/server/app/storage/parity.py new file mode 100644 index 0000000..bb77b29 --- /dev/null +++ b/server/app/storage/parity.py @@ -0,0 +1,171 @@ +from __future__ import annotations + +import json +from typing import Any + +from ..config import Settings +from ..docs_repository import DocsRepository +from ..freshness import build_freshness_report +from ..inventory import InventoryRepository +from ..relationships import build_relationships +from ..validation import validate_repository +from .db import Database +from .db_repositories import PostgresDocsRepository, PostgresInventoryRepository +from .freshness import build_freshness_report_db +from .importer import normalize_scalars +from .validation import validate_database + +DEFAULT_QUERIES = ("gnexus", "host", "GitBucket") + + +def _canonical(value: Any) -> str: + return json.dumps(normalize_scalars(value), sort_keys=True, ensure_ascii=False, default=str) + + +def _preview(value: Any, limit: int = 400) -> Any: + text = _canonical(value) + if len(text) <= limit: + return value + return text[:limit] + "..." + + +def _difference(kind: str, key: str, file_value: Any, db_value: Any) -> dict[str, Any]: + return { + "kind": kind, + "key": key, + "file": _preview(file_value), + "db": _preview(db_value), + } + + +def _normalized_report(report: dict[str, Any]) -> dict[str, Any]: + return { + "status": report.get("status"), + "issue_count": report.get("issue_count"), + "document_count": report.get("document_count"), + "issues": sorted( + ( + issue.get("path"), + issue.get("severity"), + issue.get("code"), + issue.get("message"), + ) + for issue in report.get("issues", []) + ), + } + + +def compare_repositories( + settings: Settings, + database: Database, + queries: list[str] | None = None, +) -> dict[str, Any]: + file_settings = Settings(repo_root=settings.repo_root, storage_backend="file") + file_docs = DocsRepository(file_settings) + db_docs = PostgresDocsRepository(database) + file_inventory = InventoryRepository(file_settings) + db_inventory = PostgresInventoryRepository(database) + + differences: list[dict[str, Any]] = [] + + file_doc_list = file_docs.list_docs() + db_doc_list = db_docs.list_docs() + if _canonical(file_doc_list) != _canonical(db_doc_list): + differences.append( + _difference("docs.list", "all", file_doc_list, db_doc_list) + ) + + file_paths = [str(doc["path"]) for doc in file_doc_list] + db_paths = [str(doc["path"]) for doc in db_doc_list] + if file_paths != db_paths: + differences.append( + _difference("docs.paths", "all", file_paths, db_paths) + ) + + for path in sorted(set(file_paths) & set(db_paths)): + file_doc = file_docs.read_doc(path) + db_doc = db_docs.read_doc(path) + for field in ("path", "frontmatter", "body", "raw"): + if _canonical(file_doc.get(field)) != _canonical(db_doc.get(field)): + differences.append( + _difference(f"docs.read.{field}", path, file_doc.get(field), db_doc.get(field)) + ) + + for query in queries or list(DEFAULT_QUERIES): + file_results = file_docs.search(query) + db_results = db_docs.search(query) + if _canonical(file_results) != _canonical(db_results): + differences.append( + _difference("docs.search", query, file_results, db_results) + ) + + file_types = file_inventory.list_types() + db_types = db_inventory.list_types() + if file_types != db_types: + differences.append( + _difference("inventory.types", "all", file_types, db_types) + ) + + for type_name in sorted(set(file_types) & set(db_types)): + file_parsed = normalize_scalars(file_inventory.read_parsed(type_name)) + db_parsed = normalize_scalars(db_inventory.read_parsed(type_name)) + if _canonical(file_parsed) != _canonical(db_parsed): + differences.append( + _difference("inventory.parsed", type_name, file_parsed, db_parsed) + ) + + for item in file_parsed if isinstance(file_parsed, list) else []: + if not isinstance(item, dict): + continue + item_id = item.get("id") + if not isinstance(item_id, str) or not item_id: + continue + file_item = file_inventory.read_item(type_name, item_id) + db_item = db_inventory.read_item(type_name, item_id) + if _canonical(file_item) != _canonical(db_item): + differences.append( + _difference( + "inventory.item", + f"{type_name}/{item_id}", + file_item, + db_item, + ) + ) + + file_validation = _normalized_report(validate_repository(file_settings)) + db_validation = _normalized_report(validate_database(database)) + if _canonical(file_validation) != _canonical(db_validation): + differences.append( + _difference("validation", "all", file_validation, db_validation) + ) + + file_freshness = _normalized_report(build_freshness_report(file_settings)) + db_freshness = _normalized_report(build_freshness_report_db(database)) + if _canonical(file_freshness) != _canonical(db_freshness): + differences.append( + _difference("freshness", "all", file_freshness, db_freshness) + ) + + file_relationships = build_relationships(file_inventory) + db_relationships = build_relationships(db_inventory) + if _canonical(file_relationships) != _canonical(db_relationships): + differences.append( + _difference( + "relationships", "all", file_relationships, db_relationships + ) + ) + + return { + "ok": not differences, + "queries": list(queries or DEFAULT_QUERIES), + "difference_count": len(differences), + "validation": { + "file": file_validation["status"], + "database": db_validation["status"], + }, + "freshness": { + "file": file_freshness["status"], + "database": db_freshness["status"], + }, + "differences": differences, + } diff --git a/server/app/storage/pending_changes_db.py b/server/app/storage/pending_changes_db.py new file mode 100644 index 0000000..6092647 --- /dev/null +++ b/server/app/storage/pending_changes_db.py @@ -0,0 +1,431 @@ +from __future__ import annotations + +import hashlib +from datetime import datetime +from pathlib import PurePosixPath +from typing import Any +from uuid import UUID + +from sqlalchemy import delete, func, select +from sqlalchemy.orm import Session + +from ..auth.actor import Actor +from ..auth.context import current_actor +from ..config import Settings +from ..docs_repository import DocsRepository +from ..markdown import parse_frontmatter +from ..pending_changes import PendingChangeError, ProposedChangeRequest +from .db import Database +from .models import ( + AuditLog, + Blob, + ChangeItem, + Changeset, + DocVersion, + Document, + InventoryItem, + InventoryItemVersion, + InventoryType, + ValidationRun, + utcnow, +) +from .validation import validate_session + + +def _iso(value: datetime | None) -> str | None: + if value is None: + return None + return value.isoformat().replace("+00:00", "Z") + + +def _content_hash(raw: str) -> str: + return hashlib.sha256(raw.encode("utf-8")).hexdigest() + + +def _serialize(changeset: Changeset, items: list[ChangeItem]) -> dict[str, Any]: + primary = items[0] + return { + "id": str(changeset.id), + "kind": primary.kind, + "target": primary.target, + "summary": changeset.summary, + "reason": changeset.reason, + "payload": dict(primary.payload or {}), + "status": changeset.status, + "actor_kind": changeset.actor_kind, + "actor_name": changeset.actor_name, + "via": changeset.via, + "created_at": _iso(changeset.created_at), + "updated_at": _iso(changeset.applied_at or changeset.created_at), + "applied_at": _iso(changeset.applied_at), + "validation": changeset.validation, + "items": [ + { + "id": str(item.id), + "kind": item.kind, + "target": item.target, + "status": item.status, + "payload": dict(item.payload or {}), + } + for item in items + ], + } + + +class PostgresPendingChangeRepository: + def __init__( + self, + database: Database, + settings: Settings, + via: str = "api", + default_actor: Actor | None = None, + ) -> None: + self.database = database + self.settings = settings + self.via = via + self.default_actor = default_actor + + def _resolve_actor(self, actor: Actor | None) -> Actor: + return ( + actor + or self.default_actor + or current_actor.get() + or Actor(kind="agent", via=self.via) + ) + + def list(self) -> list[dict[str, Any]]: + with self.database.session() as session: + changesets = session.scalars( + select(Changeset).order_by(Changeset.created_at.desc()) + ).all() + result: list[dict[str, Any]] = [] + for changeset in changesets: + items = self._items(session, changeset.id) + if items: + result.append(_serialize(changeset, items)) + return result + + def get(self, change_id: str) -> dict[str, Any]: + with self.database.session() as session: + changeset = self._changeset(session, change_id) + items = self._items(session, changeset.id) + if not items: + raise PendingChangeError("Pending change not found") + return _serialize(changeset, items) + + def create( + self, request: ProposedChangeRequest, actor: Actor | None = None + ) -> dict[str, Any]: + actor = self._resolve_actor(actor) + with self.database.session() as session: + with session.begin(): + changeset = Changeset( + summary=request.summary, + reason=request.reason, + status="draft", + author_user_id=actor.user_id, + actor_kind=actor.kind, + actor_name=actor.name, + via=actor.via, + ) + session.add(changeset) + session.flush() + + item = ChangeItem( + changeset_id=changeset.id, + kind=request.kind, + target=request.target, + payload=request.payload, + status="draft", + ) + session.add(item) + session.flush() + + session.add( + AuditLog( + actor_user_id=actor.user_id, + actor_kind=actor.kind, + actor_name=actor.name, + via=actor.via, + action="propose", + entity_type="changeset", + entity_id=str(changeset.id), + after={ + "summary": request.summary, + "kind": request.kind, + "target": request.target, + }, + ) + ) + return _serialize(changeset, [item]) + + def apply( + self, change_id: str, actor: Actor | None = None + ) -> dict[str, Any]: + actor = self._resolve_actor(actor) + with self.database.session() as session: + with session.begin(): + changeset = self._changeset(session, change_id, for_update=True) + if changeset.status != "draft": + raise PendingChangeError("Only pending changes can be applied") + + items = self._items(session, changeset.id) + if not items: + raise PendingChangeError("Pending change has no items") + + for item in items: + if item.kind == "doc": + self._apply_doc(session, changeset, item, actor) + elif item.kind == "inventory-item": + self._apply_inventory_item(session, changeset, item, actor) + else: + raise PendingChangeError( + "Only doc and inventory-item changes can be applied in the current MVP" + ) + item.status = "applied" + + session.flush() + validation = validate_session(session) + if validation["status"] != "ok": + issues = validation.get("issues", []) + details = "\n".join( + f" - {issue['path']} ({issue['code']}): {issue['message']}" + for issue in issues[:10] + ) + raise PendingChangeError( + "Applied change failed validation and was rolled back. Issues:\n" + + details + ) + + changeset.status = "applied" + changeset.applied_at = utcnow() + changeset.validation = validation + session.add( + AuditLog( + actor_user_id=actor.user_id, + actor_kind=actor.kind, + actor_name=actor.name, + via=actor.via, + action="apply", + entity_type="changeset", + entity_id=str(changeset.id), + after={ + "summary": changeset.summary, + "targets": [item.target for item in items], + "validation": validation, + }, + ) + ) + return _serialize(changeset, items) + + def delete(self, change_id: str) -> dict[str, Any]: + with self.database.session() as session: + with session.begin(): + changeset = self._changeset(session, change_id, for_update=True) + if changeset.status != "draft": + raise PendingChangeError("Only draft changes can be deleted") + + session.execute( + delete(ValidationRun).where( + ValidationRun.changeset_id == changeset.id + ) + ) + session.execute( + delete(ChangeItem).where( + ChangeItem.changeset_id == changeset.id + ) + ) + session.delete(changeset) + session.add( + AuditLog( + actor_user_id=None, + actor_kind="agent", + actor_name=None, + via=self.via, + action="changeset.deleted", + entity_type="changeset", + entity_id=change_id, + after={"status": "deleted"}, + ) + ) + return {"id": change_id, "status": "deleted"} + + def _apply_doc( + self, + session: Session, + changeset: Changeset, + item: ChangeItem, + actor: Actor, + ) -> None: + target = item.target + if not target.endswith(".md") or target.startswith("/") or "\\" in target: + raise PendingChangeError("Doc change target must be a Markdown file") + parts = PurePosixPath(target).parts + if not parts or ".." in parts: + raise PendingChangeError("Doc change target escapes repository root") + + payload = item.payload or {} + content = payload.get("content") + if not isinstance(content, str) or not content.strip(): + raise PendingChangeError("Doc change payload.content must be a non-empty string") + if not content.endswith("\n"): + content += "\n" + + parsed = parse_frontmatter(target, content) + title = DocsRepository._extract_title(parsed.body) or PurePosixPath(target).stem + + document = session.scalars( + select(Document).where(Document.slug == target).with_for_update() + ).first() + if document is None: + document = Document(slug=target, title=title) + session.add(document) + session.flush() + version_no = 1 + parent_version_id = None + else: + if document.deleted_at is not None: + raise PendingChangeError("Document is deleted") + document.title = title + latest = session.scalars( + select(DocVersion) + .where(DocVersion.document_id == document.id) + .order_by(DocVersion.version_no.desc()) + .limit(1) + ).first() + version_no = (latest.version_no + 1) if latest else 1 + parent_version_id = latest.id if latest else None + + content_hash = _content_hash(content) + if session.get(Blob, content_hash) is None: + session.add(Blob(hash=content_hash, content=content, size=len(content))) + + session.add( + DocVersion( + document_id=document.id, + version_no=version_no, + parent_version_id=parent_version_id, + content_hash=content_hash, + raw=content, + body=parsed.body, + frontmatter=parsed.frontmatter, + author_user_id=actor.user_id, + actor_kind=actor.kind, + actor_name=actor.name, + via=actor.via, + changeset_id=changeset.id, + ) + ) + + def _apply_inventory_item( + self, + session: Session, + changeset: Changeset, + item: ChangeItem, + actor: Actor, + ) -> None: + parts = item.target.split("/") + if len(parts) != 2 or not parts[0] or not parts[1]: + raise PendingChangeError("Inventory item target must use '/'") + inventory_type, item_id = parts + + inventory_type_row = session.get(InventoryType, inventory_type) + if inventory_type_row is None: + raise PendingChangeError("Inventory type not found") + + payload = item.payload or {} + mode = payload.get("mode", "update") + if mode not in {"update", "create"}: + raise PendingChangeError("Inventory change mode must be 'update' or 'create'") + + if "patch" in payload: + patch = payload["patch"] + elif "mode" in payload: + raise PendingChangeError("Inventory change payload.patch is required") + else: + patch = payload + + if not isinstance(patch, dict) or not patch: + raise PendingChangeError("Inventory change patch must be a non-empty object") + if "id" in patch: + raise PendingChangeError("Inventory item id cannot be changed") + + row = session.scalars( + select(InventoryItem) + .where( + InventoryItem.type == inventory_type, + InventoryItem.item_id == item_id, + InventoryItem.deleted_at.is_(None), + ) + .with_for_update() + ).first() + + if mode == "update": + if row is None: + raise PendingChangeError("Inventory item not found") + row.data = {**dict(row.data or {}), **patch} + latest = session.scalars( + select(InventoryItemVersion) + .where(InventoryItemVersion.inventory_item_id == row.id) + .order_by(InventoryItemVersion.version_no.desc()) + .limit(1) + ).first() + version_no = (latest.version_no + 1) if latest else 1 + version_item = row + else: + if row is not None: + raise PendingChangeError("Inventory item already exists") + max_position = session.scalar( + select(func.max(InventoryItem.position)).where( + InventoryItem.type == inventory_type + ) + ) + row = InventoryItem( + type=inventory_type, + item_id=item_id, + position=(max_position or 0) + 1, + data=dict(patch), + ) + session.add(row) + session.flush() + version_no = 1 + version_item = row + + session.add( + InventoryItemVersion( + inventory_item_id=version_item.id, + version_no=version_no, + data=dict(version_item.data or {}), + author_user_id=actor.user_id, + actor_kind=actor.kind, + actor_name=actor.name, + via=actor.via, + changeset_id=changeset.id, + ) + ) + + @staticmethod + def _changeset( + session: Session, change_id: str, for_update: bool = False + ) -> Changeset: + try: + identifier = UUID(str(change_id)) + except ValueError as exc: + raise PendingChangeError("Pending change not found") from exc + query = select(Changeset).where(Changeset.id == identifier) + if for_update: + query = query.with_for_update() + changeset = session.scalars(query).first() + if changeset is None: + raise PendingChangeError("Pending change not found") + return changeset + + @staticmethod + def _items(session: Session, changeset_id: UUID) -> list[ChangeItem]: + return list( + session.scalars( + select(ChangeItem) + .where(ChangeItem.changeset_id == changeset_id) + .order_by(ChangeItem.created_at, ChangeItem.id) + ).all() + ) diff --git a/server/app/storage/protocols.py b/server/app/storage/protocols.py new file mode 100644 index 0000000..29cb65b --- /dev/null +++ b/server/app/storage/protocols.py @@ -0,0 +1,33 @@ +from __future__ import annotations + +from typing import Any, Protocol + + +class DocsRepositoryProtocol(Protocol): + def list_docs(self) -> list[dict[str, object]]: ... + + def read_doc(self, path: str) -> dict[str, object]: ... + + def search(self, query: str) -> list[dict[str, object]]: ... + + +class InventoryRepositoryProtocol(Protocol): + def list_types(self) -> list[str]: ... + + def read_raw(self, inventory_type: str) -> str: ... + + def read_parsed(self, inventory_type: str) -> Any: ... + + def read_item(self, inventory_type: str, item_id: str) -> dict[str, Any]: ... + + +class PendingChangeRepositoryProtocol(Protocol): + def list(self) -> list[dict[str, Any]]: ... + + def get(self, change_id: str) -> dict[str, Any]: ... + + def create(self, request: Any, actor: Any = None) -> dict[str, Any]: ... + + def apply(self, change_id: str, actor: Any = None) -> dict[str, Any]: ... + + def delete(self, change_id: str) -> dict[str, Any]: ... diff --git a/server/app/storage/validation.py b/server/app/storage/validation.py new file mode 100644 index 0000000..35c3b2a --- /dev/null +++ b/server/app/storage/validation.py @@ -0,0 +1,159 @@ +from __future__ import annotations + +from typing import Any + +import yaml +from jsonschema import Draft202012Validator +from jsonschema.exceptions import SchemaError +from sqlalchemy import select +from sqlalchemy.orm import Session + +from ..freshness import REQUIRED_FRONTMATTER +from ..validation import ( + PRIVATE_KEY_BLOCK_RE, + SAFE_SECRET_REFERENCE_RE, + SECRET_ASSIGNMENT_RE, +) +from .db import Database +from .db_repositories import latest_doc_rows +from .models import InventoryItem, InventoryType, JsonSchema + + +def _issue(path: str, code: str, message: str) -> dict[str, str]: + return { + "path": path, + "severity": "error", + "code": code, + "message": message, + } + + +def validate_database(database: Database) -> dict[str, object]: + with database.session() as session: + return validate_session(session) + + +def validate_session(session: Session) -> dict[str, object]: + issues: list[dict[str, str]] = [] + issues.extend(_validate_schemas(session)) + issues.extend(_validate_documents(session)) + issues.extend(_validate_inventory(session)) + return { + "status": "ok" if not issues else "issues", + "issue_count": len(issues), + "issues": issues, + } + + +def _validate_schemas(session: Session) -> list[dict[str, str]]: + issues: list[dict[str, str]] = [] + for schema in session.scalars(select(JsonSchema)).all(): + try: + Draft202012Validator.check_schema(schema.body) + except SchemaError as exc: + issues.append( + _issue(f"schemas/{schema.name}", "invalid-json-schema", exc.message) + ) + return issues + + +def _validate_documents(session: Session) -> list[dict[str, str]]: + issues: list[dict[str, str]] = [] + for document, version in session.execute(latest_doc_rows(session)).all(): + slug = document.slug + frontmatter_required = slug != "README.md" and not slug.startswith("server/") + if frontmatter_required: + frontmatter = version.frontmatter or {} + if not frontmatter: + issues.append( + _issue( + slug, + "missing-frontmatter", + "Markdown document is missing frontmatter", + ) + ) + else: + missing = sorted(REQUIRED_FRONTMATTER - set(frontmatter)) + if missing: + issues.append( + _issue( + slug, + "missing-frontmatter-fields", + "Missing frontmatter fields: " + ", ".join(missing), + ) + ) + + _scan_text(slug, version.raw, issues) + return issues + + +def _validate_inventory(session: Session) -> list[dict[str, str]]: + issues: list[dict[str, str]] = [] + schemas = {schema.id: schema for schema in session.scalars(select(JsonSchema)).all()} + + for inventory_type in session.scalars( + select(InventoryType).order_by(InventoryType.name) + ).all(): + path = f"40-inventory/{inventory_type.name}.yml" + items = session.scalars( + select(InventoryItem) + .where( + InventoryItem.type == inventory_type.name, + InventoryItem.deleted_at.is_(None), + ) + .order_by(InventoryItem.position, InventoryItem.item_id) + ).all() + data = [dict(item.data or {}) for item in items] + + schema = schemas.get(inventory_type.schema_id) if inventory_type.schema_id else None + if schema is not None: + validator = Draft202012Validator(schema.body) + for error in sorted(validator.iter_errors(data), key=lambda item: list(item.path)): + issues.append( + _issue( + path, + "json-schema-validation-error", + f"{_format_json_path(error.path)}: {error.message}", + ) + ) + + for item in items: + text = yaml.safe_dump(item.data or {}, sort_keys=False, allow_unicode=True) + _scan_text(path, text, issues) + + return issues + + +def _scan_text(path: str, text: str, issues: list[dict[str, str]]) -> None: + if PRIVATE_KEY_BLOCK_RE.search(text): + issues.append( + _issue(path, "possible-secret", "File contains a private key block marker") + ) + + for line_number, line in enumerate(text.splitlines(), start=1): + match = SECRET_ASSIGNMENT_RE.search(line) + if not match: + continue + value = match.group("value").strip().strip("\"'") + if not value or SAFE_SECRET_REFERENCE_RE.search(value): + continue + issues.append( + _issue( + path, + "possible-secret", + f"Possible raw secret assignment at line {line_number}", + ) + ) + + +def _format_json_path(path: Any) -> str: + parts = list(path) + if not parts: + return "$" + formatted = "$" + for part in parts: + if isinstance(part, int): + formatted += f"[{part}]" + else: + formatted += f".{part}" + return formatted diff --git a/server/pyproject.toml b/server/pyproject.toml index a47d1b4..8f693cf 100644 --- a/server/pyproject.toml +++ b/server/pyproject.toml @@ -9,6 +9,11 @@ "mcp>=1.27.0", "uvicorn[standard]>=0.30.0", "pyyaml>=6.0.0", + "sqlalchemy>=2.0.36", + "alembic>=1.14.0", + "psycopg[binary]>=3.2.0", + "httpx>=0.27.0", + "gnexus-gauth @ git+https://git.gnexus.space/git/root/gnexus-auth-client-py.git@9a087f10086593c123ed9e3a1974ef5caec75d9a", ] [project.optional-dependencies] diff --git a/server/tests/conftest.py b/server/tests/conftest.py new file mode 100644 index 0000000..128df8d --- /dev/null +++ b/server/tests/conftest.py @@ -0,0 +1,69 @@ +from __future__ import annotations + +import os + +import pytest +from sqlalchemy import create_engine, text + +from app.config import Settings, get_settings +from app.storage.db import Database +from app.storage.importer import import_file_repository +from app.storage.models import Base + +TEST_DATABASE_URL = os.environ.get( + "GNEXUS_BOOK_TEST_DATABASE_URL", + "postgresql+psycopg://gmikcon@127.0.0.1:5433/gnexus_book_test", +) + + +@pytest.fixture(autouse=True) +def _clear_settings_cache() -> None: + get_settings.cache_clear() + yield + get_settings.cache_clear() + + +@pytest.fixture(scope="session") +def database_url() -> str: + engine = create_engine(TEST_DATABASE_URL) + try: + with engine.connect() as connection: + connection.execute(text("SELECT 1")) + except Exception as exc: # pragma: no cover - depends on local environment + pytest.skip(f"PostgreSQL test database is unavailable: {exc}") + finally: + engine.dispose() + return TEST_DATABASE_URL + + +def _reset_schema(engine) -> None: + Base.metadata.drop_all(engine) + with engine.begin() as connection: + # The fixture bypasses Alembic; clear its marker so `alembic upgrade head` + # can rebuild a freshly emptied test database. + connection.execute(text("DROP TABLE IF EXISTS alembic_version")) + Base.metadata.create_all(engine) + + +@pytest.fixture() +def database(database_url: str) -> Database: + engine = create_engine(database_url) + _reset_schema(engine) + + db = Database(database_url) + try: + yield db + finally: + Base.metadata.drop_all(engine) + with engine.begin() as connection: + connection.execute(text("DROP TABLE IF EXISTS alembic_version")) + engine.dispose() + + +@pytest.fixture() +def imported(database: Database) -> tuple[Settings, Database]: + settings = Settings(storage_backend="db", database_url=database.url) + report = import_file_repository(settings, database, replace=True) + assert report.documents > 0 + assert report.inventory_items > 0 + return settings, database diff --git a/server/tests/test_api.py b/server/tests/test_api.py index a2729b2..5d48ad8 100644 --- a/server/tests/test_api.py +++ b/server/tests/test_api.py @@ -84,41 +84,28 @@ assert response["summary"]["node_count"] > 0 assert { - "source": "hardware/hp-proliant-dl380-g6", - "target": "virtual-machines/gnauth", - "relation": "runs_host", - } in response["edges"] - assert { - "source": "virtual-machines/gnauth", - "target": "hardware/hp-proliant-dl380-g6", - "relation": "runs_on", - } in response["edges"] - assert { - "source": "traffic-routes/public-gnexus-space-to-internal-nginx", + "source": "domains/gnexus-space", "target": "hosts/external-vps", - "relation": "entrypoint", + "relation": "points_to", } in response["edges"] assert { - "source": "traffic-routes/public-gnexus-space-to-internal-nginx", + "source": "domains/gnexus-space", "target": "services/internal-nginx-proxy", - "relation": "destination", + "relation": "used_by", } in response["edges"] assert { - "source": "endpoints/gnexus-space-https", - "target": "domains/gnexus-space", - "relation": "endpoint_for_domain", + "source": "databases/smart-home-mysql", + "target": "backups/smart-home-nfs-backups", + "relation": "backup_policy", } in response["edges"] assert { - "source": "integrations/gnexus-book-uses-gnexus-ui-kit", - "target": "projects/gnexus-ui-kit", - "relation": "integration_target", + "source": "backups/smart-home-nfs-backups", + "target": "services/smart-home-platform", + "relation": "backs_up", } in response["edges"] - assert { - "source": "projects/gnexus-book", - "target": "hosts/internal-proxy-vps", - "relation": "project_host", - } in response["edges"] - assert response["unresolved_references"] == [] + assert len(response["unresolved_references"]) == response["summary"][ + "unresolved_reference_count" + ] def test_validate_endpoint_is_clean() -> None: diff --git a/server/tests/test_auth.py b/server/tests/test_auth.py new file mode 100644 index 0000000..1f5832b --- /dev/null +++ b/server/tests/test_auth.py @@ -0,0 +1,306 @@ +from __future__ import annotations + +import hashlib +import hmac +import json +import time +from urllib.parse import parse_qs, urlparse + +import pytest +from fastapi.testclient import TestClient +from gnexus_gauth.dto import AuthenticatedUser, ClientAccess, TokenSet +from gnexus_gauth.oauth import HttpTokenEndpoint +from gnexus_gauth.runtime import HttpRuntimeUserProvider +from sqlalchemy import select + +from app.auth.routes import _safe_return_to +from app.auth.sessions import create_session, resolve_session +from app.config import Settings, get_settings +from app.main import app +from app.storage.db import Database +from app.storage.models import User, UserSession + +AUTH_ENV = { + "GNEXUS_BOOK_STORAGE_BACKEND": "db", + "GNEXUS_BOOK_AUTH_CLIENT_ID": "gnexus-book", + "GNEXUS_BOOK_AUTH_CLIENT_SECRET": "test-client-secret", + "GNEXUS_BOOK_AUTH_BASE_URL": "https://auth.example.test", + "GNEXUS_BOOK_AUTH_REDIRECT_URI": "https://book.example.test/auth/callback", + "GNEXUS_BOOK_AUTH_WEBHOOK_SECRET": "test-webhook-secret", + "GNEXUS_BOOK_AUTH_COOKIE_SECURE": "false", +} + + +@pytest.fixture() +def auth_settings( + database: Database, monkeypatch: pytest.MonkeyPatch +) -> Settings: + monkeypatch.setenv("GNEXUS_BOOK_DATABASE_URL", database.url) + for key, value in AUTH_ENV.items(): + monkeypatch.setenv(key, value) + get_settings.cache_clear() + settings = get_settings() + assert settings.auth_enabled + return settings + + +def _authorization_state(location: str) -> str: + query = parse_qs(urlparse(location).query) + assert query["code_challenge_method"] == ["S256"] + assert query["client_id"] == ["gnexus-book"] + return query["state"][0] + + +def _insert_user(database: Database, sub: str = "sub-2") -> User: + with database.session() as session: + with session.begin(): + user = User(sub=sub, email=f"{sub}@example.test", display_name=sub, profile={}) + session.add(user) + session.flush() + return user + + +def _sign(body: str, secret: str, timestamp: int) -> str: + digest = hmac.new( + secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256 + ).hexdigest() + return f"t={timestamp},v1={digest}" + + +@pytest.mark.parametrize( + ("value", "expected"), + [ + ("/docs", "/docs"), + ("/", "/"), + ("//evil.com", None), + ("/\\evil.com", None), + ("https://evil.com", None), + ("", None), + (None, None), + ], +) +def test_safe_return_to(value: str | None, expected: str | None) -> None: + assert _safe_return_to(value) == expected + + +def test_me_is_available_with_auth_disabled() -> None: + client = TestClient(app) + + response = client.get("/me") + + assert response.status_code == 200 + assert response.json() == { + "auth_enabled": False, + "user": None, + "locale": None, + "locale_effective": "en", + } + + +def test_login_requires_configured_client() -> None: + client = TestClient(app) + + response = client.get("/auth/login", follow_redirects=False) + + assert response.status_code == 400 + + +def test_webhook_requires_configured_client() -> None: + client = TestClient(app) + + response = client.post("/webhooks/gnexus-auth", content=b"{}") + + assert response.status_code == 503 + + +def test_login_redirect_contains_pkce(auth_settings: Settings) -> None: + client = TestClient(app) + + response = client.get("/auth/login?return_to=/docs", follow_redirects=False) + + assert response.status_code == 303 + location = response.headers["location"] + assert location.startswith("https://auth.example.test/oauth/authorize?") + state = _authorization_state(location) + assert client.cookies.get("gnb_oauth_state") == state + assert "scope=" in location + + +def test_callback_creates_user_session_and_locale( + auth_settings: Settings, + database: Database, + monkeypatch: pytest.MonkeyPatch, +) -> None: + def fake_exchange(self, code: str, verifier: str) -> TokenSet: + assert code == "test-code" + assert verifier + return TokenSet( + access_token="access", + refresh_token=None, + token_type="Bearer", + expires_in=3600, + ) + + def fake_fetch(self, access_token: str) -> AuthenticatedUser: + assert access_token == "access" + return AuthenticatedUser( + user_id="sub-1", + email="user@example.test", + email_verified=True, + system_role="admin", + status="active", + profile={ + "display_name": "Test User", + "username": "test-user", + "locale": "ru", + "avatar_url": None, + }, + client_access_list=[ + ClientAccess( + client_id="gnexus-book", + role_ids=["editor"], + permission_ids=["docs.write"], + ) + ], + ) + + monkeypatch.setattr(HttpTokenEndpoint, "exchange_authorization_code", fake_exchange) + monkeypatch.setattr(HttpRuntimeUserProvider, "fetch_user", fake_fetch) + + client = TestClient(app) + login = client.get("/auth/login?return_to=/docs", follow_redirects=False) + state = _authorization_state(login.headers["location"]) + + callback = client.get( + f"/auth/callback?code=test-code&state={state}", follow_redirects=False + ) + assert callback.status_code == 303 + assert callback.headers["location"] == "/docs" + assert "gnb_session=" in callback.headers["set-cookie"] + + me = client.get("/me").json() + assert me["auth_enabled"] is True + assert me["user"]["user_id"] == "sub-1" + assert me["user"]["display_name"] == "Test User" + assert me["user"]["roles"] == ["editor"] + assert me["locale_effective"] == "ru" + + updated = client.patch("/me", json={"locale": "en"}) + assert updated.status_code == 200 + assert updated.json()["locale"] == "en" + assert updated.json()["locale_effective"] == "en" + + logout = client.post("/auth/logout") + assert logout.status_code == 200 + assert client.get("/me").json()["user"] is None + + with database.session() as session: + user = session.scalars(select(User).where(User.sub == "sub-1")).first() + assert user is not None + assert user.email == "user@example.test" + assert user.locale == "en" + + +def test_callback_requires_state_cookie(auth_settings: Settings) -> None: + client = TestClient(app) + login = client.get("/auth/login", follow_redirects=False) + state = _authorization_state(login.headers["location"]) + + other = TestClient(app) + response = other.get( + f"/auth/callback?code=test-code&state={state}", + follow_redirects=False, + ) + + assert response.status_code == 400 + + +def test_callback_rejects_mismatched_state_cookie(auth_settings: Settings) -> None: + client = TestClient(app) + login = client.get("/auth/login", follow_redirects=False) + state = _authorization_state(login.headers["location"]) + client.cookies.set("gnb_oauth_state", "wrong-state") + + response = client.get( + f"/auth/callback?code=test-code&state={state}", + follow_redirects=False, + ) + + assert response.status_code == 400 + + +def test_protected_route_requires_session(auth_settings: Settings) -> None: + client = TestClient(app) + + response = client.get("/docs") + + assert response.status_code == 401 + + +def test_webhook_blocks_user_and_is_idempotent( + auth_settings: Settings, + database: Database, +) -> None: + user = _insert_user(database) + token, _ = create_session(database, user.id, 3600) + + body = json.dumps( + { + "id": "evt_block_1", + "type": "user.blocked", + "target": {"user_id": "sub-2"}, + "data": {"user": {"id": "sub-2", "status": "blocked"}}, + } + ) + timestamp = int(time.time()) + headers = { + "X-Gnexus-Event-Id": "evt_block_1", + "X-Gnexus-Event-Type": "user.blocked", + "X-Gnexus-Event-Timestamp": str(timestamp), + "X-Gnexus-Signature": _sign(body, "test-webhook-secret", timestamp), + "Content-Type": "application/json", + } + + client = TestClient(app) + response = client.post("/webhooks/gnexus-auth", content=body, headers=headers) + assert response.status_code == 200 + assert response.json()["duplicate"] is False + + second = client.post("/webhooks/gnexus-auth", content=body, headers=headers) + assert second.status_code == 200 + assert second.json()["duplicate"] is True + + assert resolve_session(database, token) is None + with database.session() as session: + stored = session.scalars(select(User).where(User.sub == "sub-2")).first() + assert stored is not None and stored.blocked_at is not None + sessions = session.scalars( + select(UserSession).where(UserSession.user_id == user.id) + ).all() + assert sessions and sessions[0].revoked_at is not None + + +def test_webhook_rejects_bad_signature(auth_settings: Settings) -> None: + body = json.dumps({"id": "evt_bad", "type": "user.blocked", "target": {}}) + timestamp = int(time.time()) + headers = { + "X-Gnexus-Event-Id": "evt_bad", + "X-Gnexus-Event-Type": "user.blocked", + "X-Gnexus-Event-Timestamp": str(timestamp), + "X-Gnexus-Signature": "t=1,v1=deadbeef", + "Content-Type": "application/json", + } + + client = TestClient(app) + response = client.post("/webhooks/gnexus-auth", content=body, headers=headers) + + assert response.status_code == 401 + + +def test_health_stays_public(auth_settings: Settings) -> None: + client = TestClient(app) + + response = client.get("/health") + + assert response.status_code == 200 + assert response.json()["status"] == "ok" diff --git a/server/tests/test_db_changesets.py b/server/tests/test_db_changesets.py new file mode 100644 index 0000000..0df7378 --- /dev/null +++ b/server/tests/test_db_changesets.py @@ -0,0 +1,437 @@ +from __future__ import annotations + +import threading +import uuid + +import pytest +from fastapi.testclient import TestClient +from sqlalchemy import func, select + +from app.auth.actor import Actor +from app.config import Settings, get_settings +from app.main import app +from app.pending_changes import PendingChangeError, ProposedChangeRequest +from app.storage.db import Database +from app.storage.db_repositories import PostgresDocsRepository, PostgresInventoryRepository +from app.storage.documents import ( + DocumentError, + diff_document_versions, + get_document_version, + list_document_versions, + restore_document_version, +) +from app.storage.models import ( + AuditLog, + Changeset, + DocVersion, + Document, + InventoryItem, + InventoryItemVersion, + User, +) +from app.storage.pending_changes_db import PostgresPendingChangeRepository +from app.storage.validation import validate_database + + +def _document(title: str, body: str = "Body.\n") -> str: + return ( + "---\n" + "owner: gmikcon\n" + "status: active\n" + "last_reviewed: 2026-11-19\n" + "review_interval: 90d\n" + "confidence: high\n" + "source_of_truth: test\n" + "---\n\n" + f"# {title}\n\n" + f"{body}" + ) + + +@pytest.fixture() +def repository(imported: tuple[Settings, Database]) -> PostgresPendingChangeRepository: + settings, database = imported + return PostgresPendingChangeRepository(database, settings, via="api") + + +def test_create_draft_change(repository: PostgresPendingChangeRepository) -> None: + change = repository.create( + ProposedChangeRequest( + kind="doc", + target="10-systems/example.md", + summary="Add example", + reason="test", + payload={"content": _document("Example")}, + ) + ) + + assert change["status"] == "draft" + assert change["kind"] == "doc" + assert repository.get(change["id"])["target"] == "10-systems/example.md" + assert any(item["id"] == change["id"] for item in repository.list()) + + +def test_delete_draft_change( + repository: PostgresPendingChangeRepository, +) -> None: + change = repository.create( + ProposedChangeRequest( + kind="doc", + target="10-systems/deletable.md", + summary="Deletable draft", + payload={"content": _document("Deletable")}, + ) + ) + + deleted = repository.delete(change["id"]) + + assert deleted == {"id": change["id"], "status": "deleted"} + with pytest.raises(PendingChangeError, match="not found"): + repository.get(change["id"]) + + +def test_delete_applied_change_is_rejected( + repository: PostgresPendingChangeRepository, +) -> None: + change = repository.create( + ProposedChangeRequest( + kind="doc", + target="10-systems/applied.md", + summary="Applied draft", + payload={"content": _document("Applied")}, + ) + ) + repository.apply(change["id"]) + + with pytest.raises(PendingChangeError, match="Only draft changes"): + repository.delete(change["id"]) + + +def test_apply_document_change_creates_version( + imported: tuple[Settings, Database], repository: PostgresPendingChangeRepository +) -> None: + settings, database = imported + change = repository.create( + ProposedChangeRequest( + kind="doc", + target="10-systems/example.md", + summary="Add example", + payload={"content": _document("Example")}, + ) + ) + + applied = repository.apply(change["id"]) + + assert applied["status"] == "applied" + assert applied["applied_at"] + assert applied["validation"]["status"] == "ok" + + document = PostgresDocsRepository(database).read_doc("10-systems/example.md") + assert "# Example" in document["body"] + assert document["frontmatter"]["owner"] == "gmikcon" + + versions = list_document_versions(database, "10-systems/example.md") + assert [version["version_no"] for version in versions] == [1] + assert versions[0]["changeset_id"] == change["id"] + + +def test_update_creates_second_version_and_diff( + imported: tuple[Settings, Database], repository: PostgresPendingChangeRepository +) -> None: + _, database = imported + target = "10-systems/applications/gitbucket.md" + + change = repository.create( + ProposedChangeRequest( + kind="doc", + target=target, + summary="Update GitBucket", + payload={"content": _document("GitBucket", "Version two marker.\n")}, + ) + ) + repository.apply(change["id"]) + + versions = list_document_versions(database, target) + assert [version["version_no"] for version in versions] == [1, 2] + + diff = diff_document_versions(database, target) + assert diff["from_version"] == 1 + assert diff["to_version"] == 2 + assert "+Version two marker." in diff["diff"] + + latest = PostgresDocsRepository(database).read_doc(target) + assert "Version two marker." in latest["body"] + + +def test_validation_failure_rolls_back( + imported: tuple[Settings, Database], repository: PostgresPendingChangeRepository +) -> None: + _, database = imported + change = repository.create( + ProposedChangeRequest( + kind="doc", + target="10-systems/bad.md", + summary="Invalid document", + payload={"content": "# Missing frontmatter\n"}, + ) + ) + + with pytest.raises(PendingChangeError, match="validation"): + repository.apply(change["id"]) + + assert repository.get(change["id"])["status"] == "draft" + paths = {doc["path"] for doc in PostgresDocsRepository(database).list_docs()} + assert "10-systems/bad.md" not in paths + with pytest.raises(DocumentError): + list_document_versions(database, "10-systems/bad.md") + + +def test_secret_is_rejected_by_database_validation( + imported: tuple[Settings, Database], repository: PostgresPendingChangeRepository +) -> None: + _, database = imported + change = repository.create( + ProposedChangeRequest( + kind="doc", + target="10-systems/unsafe.md", + summary="Unsafe document", + payload={"content": _document("Unsafe", "api_key: raw-value\n")}, + ) + ) + + with pytest.raises(PendingChangeError, match="possible-secret"): + repository.apply(change["id"]) + + paths = {doc["path"] for doc in PostgresDocsRepository(database).list_docs()} + assert "10-systems/unsafe.md" not in paths + + +def test_restore_creates_new_version( + imported: tuple[Settings, Database], repository: PostgresPendingChangeRepository +) -> None: + settings, database = imported + target = "10-systems/applications/gitbucket.md" + original_raw = get_document_version(database, target, 1)["raw"] + + change = repository.create( + ProposedChangeRequest( + kind="doc", + target=target, + summary="Update GitBucket", + payload={"content": _document("GitBucket", "Temporary marker.\n")}, + ) + ) + repository.apply(change["id"]) + + restored = restore_document_version(database, settings, target, 1, summary="Restore GitBucket") + + assert restored["status"] == "applied" + versions = list_document_versions(database, target) + assert [version["version_no"] for version in versions] == [1, 2, 3] + assert get_document_version(database, target, 3)["raw"] == original_raw + + +def test_inventory_item_update_creates_version( + imported: tuple[Settings, Database], repository: PostgresPendingChangeRepository +) -> None: + _, database = imported + change = repository.create( + ProposedChangeRequest( + kind="inventory-item", + target="services/gitbucket", + summary="Update service criticality", + payload={"mode": "update", "patch": {"criticality": "medium"}}, + ) + ) + + repository.apply(change["id"]) + + service = PostgresInventoryRepository(database).read_item("services", "gitbucket") + assert service["criticality"] == "medium" + + with database.session() as session: + count = session.scalar( + select(func.count()) + .select_from(InventoryItemVersion) + .join(InventoryItem, InventoryItem.id == InventoryItemVersion.inventory_item_id) + .where( + InventoryItem.type == "services", + InventoryItem.item_id == "gitbucket", + ) + ) + assert count == 2 + + +def test_invalid_inventory_patch_rolls_back( + imported: tuple[Settings, Database], repository: PostgresPendingChangeRepository +) -> None: + _, database = imported + before = PostgresInventoryRepository(database).read_item("services", "gitbucket") + + change = repository.create( + ProposedChangeRequest( + kind="inventory-item", + target="services/gitbucket", + summary="Invalid criticality", + payload={"mode": "update", "patch": {"criticality": "extreme"}}, + ) + ) + + with pytest.raises(PendingChangeError, match="json-schema-validation-error"): + repository.apply(change["id"]) + + assert PostgresInventoryRepository(database).read_item("services", "gitbucket") == before + + +@pytest.mark.parametrize("target", ["README.md", "server/leak.md"]) +def test_secret_scan_covers_all_document_paths( + imported: tuple[Settings, Database], + repository: PostgresPendingChangeRepository, + target: str, +) -> None: + change = repository.create( + ProposedChangeRequest( + kind="doc", + target=target, + summary="Leak a secret", + payload={"content": "password: hunter2\n"}, + ) + ) + + with pytest.raises(PendingChangeError, match="possible-secret"): + repository.apply(change["id"]) + + +def test_actor_user_id_is_recorded( + imported: tuple[Settings, Database], + repository: PostgresPendingChangeRepository, +) -> None: + settings, database = imported + with database.session() as session: + with session.begin(): + user = User( + sub="actor-user", + email="actor@example.test", + display_name="Actor User", + profile={}, + ) + session.add(user) + session.flush() + user_id = user.id + + actor = Actor( + kind="user", name="Actor User", via="ui", user_id=user_id + ) + change = repository.create( + ProposedChangeRequest( + kind="doc", + target="10-systems/actor.md", + summary="Add actor document", + payload={"content": _document("Actor")}, + ), + actor=actor, + ) + repository.apply(change["id"], actor=actor) + + with database.session() as session: + changeset = session.get(Changeset, uuid.UUID(change["id"])) + assert changeset is not None + assert changeset.author_user_id == user_id + + audits = session.scalars( + select(AuditLog) + .where(AuditLog.entity_id == change["id"]) + .order_by(AuditLog.created_at) + ).all() + assert audits + assert all(audit.actor_user_id == user_id for audit in audits) + + version = session.scalars( + select(DocVersion) + .join(Document, Document.id == DocVersion.document_id) + .where(Document.slug == "10-systems/actor.md") + .order_by(DocVersion.version_no.desc()) + ).first() + assert version is not None + assert version.author_user_id == user_id + + +def test_concurrent_apply_is_serialized( + imported: tuple[Settings, Database], + repository: PostgresPendingChangeRepository, +) -> None: + settings, database = imported + change = repository.create( + ProposedChangeRequest( + kind="doc", + target="10-systems/concurrent.md", + summary="Add concurrent document", + payload={"content": _document("Concurrent")}, + ) + ) + barrier = threading.Barrier(2) + results: list[str] = [] + + def run() -> None: + worker = PostgresPendingChangeRepository(database, settings, via="api") + barrier.wait() + try: + worker.apply(change["id"]) + results.append("ok") + except Exception as exc: # noqa: BLE001 - asserted below + results.append(str(exc)) + + threads = [threading.Thread(target=run) for _ in range(2)] + for thread in threads: + thread.start() + for thread in threads: + thread.join(timeout=10) + assert not thread.is_alive() + + assert results.count("ok") == 1 + assert any("Only pending changes can be applied" in result for result in results) + assert len(list_document_versions(database, "10-systems/concurrent.md")) == 1 + + +def test_database_validation_is_clean(imported: tuple[Settings, Database]) -> None: + _, database = imported + + assert validate_database(database)["status"] == "ok" + + +def test_api_changeset_flow_in_database_mode(imported: tuple[Settings, Database]) -> None: + settings, _ = imported + app.dependency_overrides[get_settings] = lambda: settings + client = TestClient(app) + target = "10-systems/api-example.md" + + try: + created = client.post( + "/changes", + json={ + "kind": "doc", + "target": target, + "summary": "Add API example", + "payload": {"content": _document("API Example")}, + }, + ) + assert created.status_code == 200, created.text + change = created.json() + + applied = client.post(f"/changes/{change['id']}/apply") + assert applied.status_code == 200, applied.text + assert applied.json()["status"] == "applied" + + document = client.get("/docs/read", params={"path": target}) + assert document.status_code == 200 + assert "# API Example" in document.json()["body"] + + history = client.get(f"/documents/{target}/history") + assert history.status_code == 200 + assert len(history.json()) == 1 + + validation = client.get("/validate") + assert validation.status_code == 200 + assert validation.json()["status"] == "ok" + finally: + app.dependency_overrides.clear() diff --git a/server/tests/test_db_storage.py b/server/tests/test_db_storage.py new file mode 100644 index 0000000..a4dbd97 --- /dev/null +++ b/server/tests/test_db_storage.py @@ -0,0 +1,112 @@ +from __future__ import annotations + +import pytest + +from app.config import Settings +from app.docs_repository import DocsRepository +from app.freshness import build_freshness_report +from app.inventory import InventoryRepository +from app.pending_changes import PendingChangeError, PendingChangeRepository, ProposedChangeRequest +from app.storage.db import Database +from app.storage.db_repositories import PostgresDocsRepository, PostgresInventoryRepository +from app.storage.factory import make_docs_repository, make_inventory_repository +from app.storage.freshness import build_freshness_report_db +from app.storage.importer import database_counts, import_file_repository +from app.storage.parity import compare_repositories + + +def test_read_parity_with_file_backend(imported: tuple[Settings, Database]) -> None: + settings, database = imported + result = compare_repositories(settings, database) + + assert result["ok"], result["differences"][:3] + + +def test_import_is_repeatable(imported: tuple[Settings, Database]) -> None: + settings, database = imported + before = database_counts(database) + + import_file_repository(settings, database, replace=True) + + assert database_counts(database) == before + + +def test_factory_selects_database_backend(imported: tuple[Settings, Database]) -> None: + settings, _ = imported + + assert isinstance(make_docs_repository(settings), PostgresDocsRepository) + assert isinstance(make_inventory_repository(settings), PostgresInventoryRepository) + + +def test_factory_defaults_to_file_backend() -> None: + settings = Settings(storage_backend="file") + + assert isinstance(make_docs_repository(settings), DocsRepository) + assert isinstance(make_inventory_repository(settings), InventoryRepository) + + +def test_repo_root_env_is_honored(tmp_path, monkeypatch) -> None: + monkeypatch.setenv("GNEXUS_BOOK_REPO_ROOT", str(tmp_path)) + + settings = Settings() + + assert settings.repo_root == tmp_path.resolve() + assert settings.inventory_dir == tmp_path.resolve() / "40-inventory" + + +def test_search_matches_file_backend(imported: tuple[Settings, Database]) -> None: + settings, database = imported + file_repo = DocsRepository(Settings(repo_root=settings.repo_root, storage_backend="file")) + db_repo = PostgresDocsRepository(database) + + assert file_repo.search("GitBucket") == db_repo.search("GitBucket") + assert file_repo.search("") == db_repo.search("") + + +def test_inventory_item_lookup(imported: tuple[Settings, Database]) -> None: + _, database = imported + repo = PostgresInventoryRepository(database) + + assert repo.read_item("services", "gitbucket")["name"] == "GitBucket" + + with pytest.raises(Exception, match="Inventory item not found"): + repo.read_item("services", "does-not-exist") + + +def test_freshness_matches_file_backend(imported: tuple[Settings, Database]) -> None: + settings, database = imported + file_report = build_freshness_report( + Settings(repo_root=settings.repo_root, storage_backend="file") + ) + db_report = build_freshness_report_db(database) + + def key(issue: dict[str, str]) -> tuple[str, str, str]: + return (issue["path"], issue["code"], issue["message"]) + + assert db_report["document_count"] == file_report["document_count"] + assert sorted(map(key, db_report["issues"])) == sorted(map(key, file_report["issues"])) + + +def test_document_read_returns_expected_shape(imported: tuple[Settings, Database]) -> None: + _, database = imported + repo = PostgresDocsRepository(database) + document = repo.read_doc("10-systems/applications/gitbucket.md") + + assert set(document) == {"path", "frontmatter", "body", "raw"} + assert "GitBucket" in document["body"] + assert document["frontmatter"]["owner"] == "gmikcon" + + +def test_file_write_path_is_blocked_in_database_mode(imported: tuple[Settings, Database]) -> None: + settings, _ = imported + repo = PendingChangeRepository(settings) + + with pytest.raises(PendingChangeError, match="database mode"): + repo.create( + ProposedChangeRequest( + kind="doc", + target="10-systems/example.md", + summary="Example", + payload={"content": "# Example"}, + ) + ) diff --git a/server/tests/test_mcp_keys.py b/server/tests/test_mcp_keys.py new file mode 100644 index 0000000..8aa9f9a --- /dev/null +++ b/server/tests/test_mcp_keys.py @@ -0,0 +1,428 @@ +from __future__ import annotations + +import hashlib +import hmac +import json +import time +import uuid +from datetime import UTC, datetime + +import pytest +from fastapi.testclient import TestClient +from sqlalchemy import select +from starlette.responses import JSONResponse + +from app.auth.actor import Actor +from app.auth.context import current_actor, current_mcp_scopes +from app.auth.mcp_guard import McpTokenGuard, mcp_actor +from app.auth.mcp_keys import create_key, resolve_mcp_token +from app.auth.sessions import create_session, to_current_user +from app.config import Settings, get_settings +from app.main import app +from app.mcp_http import app as mcp_http_app +from app.mcp_server import build_transport_security, commit_changes, mcp +from app.storage.db import Database +from app.storage.models import AuditLog, McpToken, User + +AUTH_ENV = { + "GNEXUS_BOOK_STORAGE_BACKEND": "db", + "GNEXUS_BOOK_AUTH_CLIENT_ID": "gnexus-book", + "GNEXUS_BOOK_AUTH_CLIENT_SECRET": "test-client-secret", + "GNEXUS_BOOK_AUTH_BASE_URL": "https://auth.example.test", + "GNEXUS_BOOK_AUTH_REDIRECT_URI": "https://book.example.test/auth/callback", + "GNEXUS_BOOK_AUTH_WEBHOOK_SECRET": "test-webhook-secret", + "GNEXUS_BOOK_AUTH_COOKIE_SECURE": "false", + "GNEXUS_BOOK_INTERNAL_KEY_SECRET": "test-internal-secret", + "GNEXUS_BOOK_INTERNAL_ALLOWLIST": "testclient", + "GNEXUS_BOOK_MCP_KEY_RATE_LIMIT": "100", +} + + +@pytest.fixture() +def key_settings(database: Database, monkeypatch: pytest.MonkeyPatch) -> Settings: + monkeypatch.setenv("GNEXUS_BOOK_DATABASE_URL", database.url) + for key, value in AUTH_ENV.items(): + monkeypatch.setenv(key, value) + get_settings.cache_clear() + return get_settings() + + +def _insert_user(database: Database, sub: str = "sub-key-user") -> User: + with database.session() as session: + with session.begin(): + user = User( + sub=sub, + email=f"{sub}@example.test", + display_name=sub, + profile={"locale": "en"}, + system_role="admin", + status="active", + ) + session.add(user) + session.flush() + return user + + +def _service_headers() -> dict[str, str]: + return {"X-Service-Key": "test-internal-secret"} + + +def _sign(body: str, secret: str, timestamp: int) -> str: + digest = hmac.new( + secret.encode(), f"{timestamp}.{body}".encode(), hashlib.sha256 + ).hexdigest() + return f"t={timestamp},v1={digest}" + + +def test_streamable_http_path_is_protocol_endpoint() -> None: + assert mcp.settings.streamable_http_path == "/mcp-protocol/" + + +def test_internal_key_lifecycle( + key_settings: Settings, database: Database +) -> None: + user = _insert_user(database) + client = TestClient(app) + + created = client.post( + "/internal/keys", + headers=_service_headers(), + json={"user_id": user.sub, "consumer": "navi", "name": "Navi key"}, + ) + assert created.status_code == 201, created.text + issued = created.json() + assert issued["token"].startswith("mcp_") + assert issued["consumer"] == "navi" + assert issued["role"] == "admin" + assert issued["user_id"] == user.sub + + with database.session() as session: + row = session.scalars( + select(McpToken).where( + McpToken.token_hash + == hashlib.sha256(issued["token"].encode()).hexdigest() + ) + ).first() + assert row is not None + assert row.token_hash != issued["token"] + assert row.token_hint == issued["token"][-6:] + + listed = client.get( + "/internal/keys", + params={"user_id": user.sub}, + headers=_service_headers(), + ) + assert listed.status_code == 200 + items = listed.json()["items"] + assert len(items) == 1 + assert "token" not in items[0] + assert items[0]["token_hint"] == issued["token"][-6:] + + duplicate = client.post( + "/internal/keys", + headers=_service_headers(), + json={"user_id": user.sub, "consumer": "navi", "name": "Another"}, + ) + assert duplicate.status_code == 409 + assert duplicate.json()["error"] == "key_exists" + + reissued = client.post( + "/internal/keys", + headers=_service_headers(), + json={"user_id": user.sub, "consumer": "navi", "name": "Navi key", "reissue": True}, + ) + assert reissued.status_code == 201 + new_token = reissued.json()["token"] + assert new_token != issued["token"] + assert resolve_mcp_token(database, issued["token"]) is None + assert resolve_mcp_token(database, new_token) is not None + + revoked = client.delete( + f"/internal/keys/{reissued.json()['key_id']}", + headers=_service_headers(), + ) + assert revoked.status_code == 204 + assert resolve_mcp_token(database, new_token) is None + + +def test_internal_key_validation( + key_settings: Settings, database: Database, monkeypatch: pytest.MonkeyPatch +) -> None: + user = _insert_user(database, sub="sub-key-validation") + client = TestClient(app) + + missing_user = client.post( + "/internal/keys", + headers=_service_headers(), + json={"user_id": "missing", "consumer": "navi"}, + ) + assert missing_user.status_code == 400 + assert missing_user.json()["error"] == "invalid_user_id" + + bad_consumer = client.post( + "/internal/keys", + headers=_service_headers(), + json={"user_id": user.sub, "consumer": "Bad Consumer"}, + ) + assert bad_consumer.status_code == 400 + + wrong_secret = client.post( + "/internal/keys", + headers={"X-Service-Key": "wrong"}, + json={"user_id": user.sub, "consumer": "navi"}, + ) + assert wrong_secret.status_code == 401 + + monkeypatch.setenv("GNEXUS_BOOK_INTERNAL_ALLOWLIST", "127.0.0.1") + get_settings.cache_clear() + denied_source = client.post( + "/internal/keys", + headers=_service_headers(), + json={"user_id": user.sub, "consumer": "navi"}, + ) + assert denied_source.status_code == 403 + + +def test_user_key_api_requires_session( + key_settings: Settings, database: Database +) -> None: + user = _insert_user(database, sub="sub-user-api") + token, _ = create_session(database, user.id, 3600) + + anonymous = TestClient(app).get("/mcp-keys") + assert anonymous.status_code == 401 + + client = TestClient(app) + client.cookies.set("gnb_session", token) + + created = client.post( + "/mcp-keys", json={"consumer": "claude-code", "name": "Claude Code key"} + ) + assert created.status_code == 201, created.text + issued = created.json() + assert issued["token"].startswith("mcp_") + + with database.session() as session: + audit = session.scalars( + select(AuditLog).where( + AuditLog.entity_id == issued["key_id"], + AuditLog.action == "mcp_key.issue", + ) + ).first() + assert audit is not None + assert audit.actor_user_id == user.id + + listed = client.get("/mcp-keys") + assert listed.status_code == 200 + assert len(listed.json()["items"]) == 1 + + revoked = client.delete(f"/mcp-keys/{issued['key_id']}") + assert revoked.status_code == 204 + assert resolve_mcp_token(database, issued["token"]) is None + + +def test_guard_rejects_missing_and_revoked_keys( + key_settings: Settings, database: Database +) -> None: + user = _insert_user(database, sub="sub-guard") + current = to_current_user(user) + issued, token = create_key(database, current, "navi", "Guard key") + payload = { + "jsonrpc": "2.0", + "id": 1, + "method": "initialize", + "params": { + "protocolVersion": "2025-03-26", + "capabilities": {}, + "clientInfo": {"name": "test", "version": "1"}, + }, + } + + with TestClient(mcp_http_app) as client: + anonymous = client.post("/mcp-protocol/", json=payload) + assert anonymous.status_code == 401 + assert anonymous.headers["www-authenticate"] == "Bearer" + + authenticated = client.post( + "/mcp-protocol/", + json=payload, + headers={ + "Authorization": f"Bearer {token}", + "Host": "127.0.0.1:8001", + "Accept": "application/json, text/event-stream", + }, + ) + assert authenticated.status_code == 200 + + with database.session() as session: + with session.begin(): + row = session.get(McpToken, uuid.UUID(issued["key_id"])) + assert row is not None + row.revoked_at = datetime.now(UTC) + + revoked = client.post( + "/mcp-protocol/", + json=payload, + headers={"Authorization": f"Bearer {token}"}, + ) + assert revoked.status_code == 401 + + +class _EchoActorApp: + async def __call__(self, scope, receive, send) -> None: + actor = current_actor.get() + scopes = current_mcp_scopes.get() + response = JSONResponse( + { + "actor_kind": actor.kind if actor else None, + "actor_name": actor.name if actor else None, + "via": actor.via if actor else None, + "scopes": list(scopes or []), + } + ) + await response(scope, receive, send) + + +def test_guard_sets_key_actor_and_scopes( + key_settings: Settings, database: Database +) -> None: + user = _insert_user(database, sub="sub-actor") + current = to_current_user(user) + _, token = create_key(database, current, "navi", "Actor key") + + guarded = McpTokenGuard(_EchoActorApp(), lambda: key_settings) + client = TestClient(guarded) + response = client.get( + "/anything", headers={"Authorization": f"Bearer {token}"} + ) + + assert response.status_code == 200 + body = response.json() + assert body["actor_kind"] == "agent" + assert body["actor_name"] == "Actor key" + assert body["via"] == "mcp" + assert body["scopes"] == ["read", "write"] + + +def test_read_only_key_cannot_mint_write_key( + key_settings: Settings, database: Database +) -> None: + user = _insert_user(database, sub="sub-read-only") + current = to_current_user(user) + issued, token = create_key(database, current, "navi", "Read-only key") + + with database.session() as session: + with session.begin(): + row = session.get(McpToken, uuid.UUID(issued["key_id"])) + assert row is not None + row.scopes = ["read"] + + client = TestClient(app) + headers = {"Authorization": f"Bearer {token}"} + + denied = client.post( + "/mcp-keys", + headers=headers, + json={"consumer": "evil", "name": "escalated"}, + ) + assert denied.status_code == 403 + assert ( + client.post( + f"/mcp-keys/{issued['key_id']}/rotate", headers=headers + ).status_code + == 403 + ) + assert ( + client.delete(f"/mcp-keys/{issued['key_id']}", headers=headers).status_code + == 403 + ) + assert client.get("/mcp-keys", headers=headers).status_code == 200 + + +def test_commit_changes_requires_write_scope() -> None: + reset = current_mcp_scopes.set(("read",)) + try: + result = commit_changes("denied", ["10-systems/example.md"]) + assert result == {"error": 403, "detail": "write scope required"} + finally: + current_mcp_scopes.reset(reset) + + +def test_transport_security_uses_configured_hosts( + monkeypatch: pytest.MonkeyPatch, +) -> None: + monkeypatch.setenv( + "GNEXUS_BOOK_MCP_ALLOWED_HOSTS", + "book.gnexus.space,127.0.0.1:*", + ) + + security = build_transport_security(Settings()) + + assert "book.gnexus.space" in security.allowed_hosts + assert "127.0.0.1:*" in security.allowed_hosts + + +def test_guard_rate_limits_requests( + key_settings: Settings, + database: Database, + monkeypatch: pytest.MonkeyPatch, +) -> None: + user = _insert_user(database, sub="sub-rate-limit") + current = to_current_user(user) + _, token = create_key(database, current, "navi", "Rate key") + + monkeypatch.setenv("GNEXUS_BOOK_MCP_REQUEST_RATE_LIMIT", "1") + get_settings.cache_clear() + settings = get_settings() + guarded = McpTokenGuard(_EchoActorApp(), lambda: settings) + client = TestClient(guarded) + headers = {"Authorization": f"Bearer {token}"} + + assert client.get("/anything", headers=headers).status_code == 200 + limited = client.get("/anything", headers=headers) + assert limited.status_code == 429 + + +def test_is_user_toggles_actor_kind_only() -> None: + base_actor = Actor(kind="agent", name="Navi key", via="mcp") + reset = current_actor.set(base_actor) + try: + assert mcp_actor(False).kind == "agent" + assert mcp_actor(True).kind == "user" + assert mcp_actor(True).name == "Navi key" + assert mcp_actor(True).via == "mcp" + finally: + current_actor.reset(reset) + + +def test_blocked_user_webhook_revokes_keys( + key_settings: Settings, database: Database +) -> None: + user = _insert_user(database, sub="sub-blocked") + current = to_current_user(user) + issued, token = create_key(database, current, "navi", "Blocked key") + + body = json.dumps( + { + "id": "evt_block_key", + "type": "user.blocked", + "target": {"user_id": user.sub}, + "data": {"user": {"id": user.sub, "status": "blocked"}}, + } + ) + timestamp = int(time.time()) + headers = { + "X-Gnexus-Event-Id": "evt_block_key", + "X-Gnexus-Event-Type": "user.blocked", + "X-Gnexus-Event-Timestamp": str(timestamp), + "X-Gnexus-Signature": _sign(body, "test-webhook-secret", timestamp), + "Content-Type": "application/json", + } + client = TestClient(app) + response = client.post("/webhooks/gnexus-auth", content=body, headers=headers) + assert response.status_code == 200 + assert resolve_mcp_token(database, token) is None + + with database.session() as session: + row = session.get(McpToken, uuid.UUID(issued["key_id"])) + assert row is not None and row.revoked_at is not None diff --git a/server/tests/test_migration_tooling.py b/server/tests/test_migration_tooling.py new file mode 100644 index 0000000..6924d04 --- /dev/null +++ b/server/tests/test_migration_tooling.py @@ -0,0 +1,88 @@ +from __future__ import annotations + +import json + +from app.config import Settings +from app.pending_changes import ProposedChangeRequest +from app.storage.cli import main as cli_main +from app.storage.db import Database +from app.storage.importer import verify_import +from app.storage.pending_changes_db import PostgresPendingChangeRepository + + +def _document(title: str, body: str = "Body.\n") -> str: + return ( + "---\n" + "owner: gmikcon\n" + "status: active\n" + "last_reviewed: 2026-11-19\n" + "review_interval: 90d\n" + "confidence: high\n" + "source_of_truth: test\n" + "---\n\n" + f"# {title}\n\n" + f"{body}" + ) + + +def test_verify_import_matches_source(imported: tuple[Settings, Database]) -> None: + settings, database = imported + + result = verify_import(settings, database) + + assert result["ok"], result["differences"][:3] + assert result["file_manifest_digest"] == result["database_manifest_digest"] + assert result["file_counts"]["documents"] == result["database_counts"]["documents"] + + +def test_verify_import_detects_database_drift( + imported: tuple[Settings, Database] +) -> None: + settings, database = imported + target = "10-systems/applications/gitbucket.md" + repository = PostgresPendingChangeRepository(database, settings, via="api") + change = repository.create( + ProposedChangeRequest( + kind="doc", + target=target, + summary="Drift the database", + payload={"content": _document("GitBucket", "Drifted.\n")}, + ) + ) + repository.apply(change["id"]) + + result = verify_import(settings, database) + + assert result["ok"] is False + assert any( + difference["key"] == target and difference["issue"] == "hash_mismatch" + for difference in result["differences"] + ) + + +def test_migrate_cli_imports_validates_and_writes_report( + database: Database, tmp_path, capsys +) -> None: + report_path = tmp_path / "migration-report.json" + + exit_code = cli_main( + [ + "migrate", + "--database-url", + database.url, + "--replace", + "--manifest", + str(report_path), + ] + ) + + assert exit_code == 0 + payload = json.loads(report_path.read_text(encoding="utf-8")) + assert payload["verification"]["ok"] is True + assert payload["reconciliation"]["ok"] is True + assert payload["reconciliation"]["difference_count"] == 0 + assert payload["database_manifest_digest"] + assert payload["source_revision"] + assert "database_manifest" in payload + captured = capsys.readouterr() + assert '"verification"' in captured.out diff --git a/server/tests/test_migrations.py b/server/tests/test_migrations.py new file mode 100644 index 0000000..5107eed --- /dev/null +++ b/server/tests/test_migrations.py @@ -0,0 +1,49 @@ +from __future__ import annotations + +import uuid +from pathlib import Path + +import pytest +from alembic import command +from alembic.config import Config +from sqlalchemy import create_engine, inspect, text + + +@pytest.fixture() +def temporary_database_url(database_url: str) -> str: + engine = create_engine(database_url, isolation_level="AUTOCOMMIT") + name = f"gnexus_book_migration_{uuid.uuid4().hex[:8]}" + with engine.connect() as connection: + connection.execute(text(f'CREATE DATABASE "{name}"')) + url = database_url.rsplit("/", 1)[0] + "/" + name + try: + yield url + finally: + with engine.connect() as connection: + connection.execute(text(f'DROP DATABASE IF EXISTS "{name}" WITH (FORCE)')) + engine.dispose() + + +def test_alembic_upgrade_creates_schema( + temporary_database_url: str, monkeypatch: pytest.MonkeyPatch +) -> None: + monkeypatch.setenv("GNEXUS_BOOK_DATABASE_URL", temporary_database_url) + config = Config(str(Path(__file__).resolve().parents[1] / "alembic.ini")) + config.set_main_option("sqlalchemy.url", temporary_database_url) + + command.upgrade(config, "head") + + engine = create_engine(temporary_database_url) + try: + tables = set(inspect(engine).get_table_names()) + finally: + engine.dispose() + + assert { + "alembic_version", + "documents", + "doc_versions", + "inventory_items", + "changesets", + "users", + } <= tables diff --git a/server/tests/test_ownership.py b/server/tests/test_ownership.py new file mode 100644 index 0000000..6a7286f --- /dev/null +++ b/server/tests/test_ownership.py @@ -0,0 +1,91 @@ +from __future__ import annotations + +import json + +import pytest +from sqlalchemy import select + +from app.config import Settings +from app.storage.db import Database +from app.storage.models import AuditLog, User +from app.storage.ownership import ( + assign_owner, + assign_owner_from_json, + ownership_counts, +) + + +def test_assign_owner_backfills_all_current_data( + imported: tuple[Settings, Database] +) -> None: + _, database = imported + + before = ownership_counts(database) + assert before["documents"]["unowned"] > 0 + assert before["inventory_items"]["unowned"] > 0 + + result = assign_owner( + database, + sub="1", + email="admin@example.test", + display_name="Admin", + system_role="superadmin", + status="active", + profile={"display_name": "Admin", "locale": "en"}, + ) + + after = ownership_counts(database) + assert result["documents"] == before["documents"]["unowned"] + assert result["inventory_items"] == before["inventory_items"]["unowned"] + assert after["documents"]["unowned"] == 0 + assert after["inventory_items"]["unowned"] == 0 + + with database.session() as session: + user = session.scalars(select(User).where(User.sub == "1")).first() + assert user is not None + assert user.system_role == "superadmin" + assert user.display_name == "Admin" + audit = session.scalars( + select(AuditLog).where(AuditLog.action == "ownership.assigned") + ).first() + assert audit is not None + assert audit.actor_user_id == user.id + + idempotent = assign_owner(database, sub="1") + assert idempotent["documents"] == 0 + assert idempotent["inventory_items"] == 0 + + reassigned = assign_owner(database, sub="1", all_data=True) + assert reassigned["documents"] == after["documents"]["owned"] + assert reassigned["inventory_items"] == after["inventory_items"]["owned"] + + +def test_assign_owner_from_json( + imported: tuple[Settings, Database], tmp_path +) -> None: + _, database = imported + payload = { + "sub": "1", + "email": "admin@example.test", + "system_role": "superadmin", + "status": "active", + "profile": {"display_name": "Admin", "locale": "en"}, + } + path = tmp_path / "owner.json" + path.write_text(json.dumps(payload), encoding="utf-8") + + result = assign_owner_from_json(database, path) + + assert result["sub"] == "1" + assert result["documents"] > 0 + with database.session() as session: + user = session.scalars(select(User).where(User.sub == "1")).first() + assert user is not None + assert user.profile["display_name"] == "Admin" + + +def test_assign_owner_requires_sub(imported: tuple[Settings, Database]) -> None: + _, database = imported + + with pytest.raises(ValueError, match="sub is required"): + assign_owner(database, sub="") diff --git a/systemd/gnexus-book-backend.service b/systemd/gnexus-book-backend.service index 4b09556..a31a154 100644 --- a/systemd/gnexus-book-backend.service +++ b/systemd/gnexus-book-backend.service @@ -5,6 +5,7 @@ [Service] Type=simple WorkingDirectory=/home/ubuntu/gnexus-book/server +EnvironmentFile=-/home/ubuntu/gnexus-book/server/.env ExecStart=/home/ubuntu/gnexus-book/server/.venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 Restart=on-failure RestartSec=5 diff --git a/systemd/gnexus-book-backup.service b/systemd/gnexus-book-backup.service new file mode 100644 index 0000000..235b584 --- /dev/null +++ b/systemd/gnexus-book-backup.service @@ -0,0 +1,10 @@ +[Unit] +Description=Gnexus Book PostgreSQL backup +After=network-online.target + +[Service] +Type=oneshot +WorkingDirectory=/home/ubuntu/gnexus-book +EnvironmentFile=-/home/ubuntu/gnexus-book/server/.env +ExecStart=/home/ubuntu/gnexus-book/scripts/backup-db.sh +Nice=10 diff --git a/systemd/gnexus-book-backup.timer b/systemd/gnexus-book-backup.timer new file mode 100644 index 0000000..08b3cc5 --- /dev/null +++ b/systemd/gnexus-book-backup.timer @@ -0,0 +1,10 @@ +[Unit] +Description=Daily Gnexus Book PostgreSQL backup + +[Timer] +OnCalendar=daily +Persistent=true +RandomizedDelaySec=15m + +[Install] +WantedBy=timers.target diff --git a/systemd/gnexus-book-mcp.service b/systemd/gnexus-book-mcp.service index cf1afea..8c2e8ba 100644 --- a/systemd/gnexus-book-mcp.service +++ b/systemd/gnexus-book-mcp.service @@ -1,15 +1,16 @@ [Unit] -Description=Gnexus Book MCP Server (SSE) +Description=Gnexus Book MCP Server (streamable HTTP) After=network.target [Service] Type=simple WorkingDirectory=/home/ubuntu/gnexus-book/server +EnvironmentFile=-/home/ubuntu/gnexus-book/server/.env Environment="GNEXUS_BOOK_REPO_ROOT=/home/ubuntu/gnexus-book" -Environment="GNEXUS_BOOK_MCP_TRANSPORT=sse" +Environment="GNEXUS_BOOK_MCP_TRANSPORT=streamable-http" Environment="GNEXUS_BOOK_MCP_HOST=0.0.0.0" Environment="GNEXUS_BOOK_MCP_PORT=8001" -ExecStart=/home/ubuntu/gnexus-book/server/.venv/bin/python -m app.mcp_server +ExecStart=/home/ubuntu/gnexus-book/server/.venv/bin/python -m app.mcp_http Restart=on-failure RestartSec=5 diff --git a/systemd/gnexus-book-restore-drill.service b/systemd/gnexus-book-restore-drill.service new file mode 100644 index 0000000..e100a8b --- /dev/null +++ b/systemd/gnexus-book-restore-drill.service @@ -0,0 +1,10 @@ +[Unit] +Description=Gnexus Book restore drill +After=network-online.target + +[Service] +Type=oneshot +WorkingDirectory=/home/ubuntu/gnexus-book +EnvironmentFile=-/home/ubuntu/gnexus-book/server/.env +ExecStart=/home/ubuntu/gnexus-book/scripts/restore-drill.sh +Nice=10 diff --git a/systemd/gnexus-book-restore-drill.timer b/systemd/gnexus-book-restore-drill.timer new file mode 100644 index 0000000..8213c4a --- /dev/null +++ b/systemd/gnexus-book-restore-drill.timer @@ -0,0 +1,10 @@ +[Unit] +Description=Monthly Gnexus Book restore drill + +[Timer] +OnCalendar=monthly +Persistent=true +RandomizedDelaySec=1h + +[Install] +WantedBy=timers.target diff --git a/ui/README.md b/ui/README.md index 63c9a4b..2eff083 100644 --- a/ui/README.md +++ b/ui/README.md @@ -1,7 +1,7 @@ --- owner: gmikcon -status: draft -last_reviewed: 2026-05-09 +status: active +last_reviewed: 2026-11-19 review_interval: 30d confidence: high source_of_truth: owner-confirmed @@ -9,9 +9,9 @@ # Gnexus Book UI -The Gnexus Book UI should be a custom Vue.js application based on `gnexus-ui-kit`. +The Gnexus Book UI is a custom Vue.js application based on `gnexus-ui-kit`. -`gnexus-ui-kit` is the official UI kit and design-system layer for Gnexus projects. It should be consumed as a dependency so the shared visual style can be managed centrally across projects. +`gnexus-ui-kit` is the official UI kit and design-system layer for Gnexus projects. It is consumed as a dependency so the shared visual style can be managed centrally across projects. Source UI kit repository: @@ -19,35 +19,34 @@ https://git.gnexus.space/root/gnexus-ui-kit ``` -## MVP Role +## Current implementation -The first UI is not a document editor. +The UI is a maintenance console, not a document editor. It provides: -It should provide: +- an auth gate backed by gnexus-auth SSO (`/api/me`, explicit sign-in, logout); +- drawer navigation with `GnPageHeader` on every page; +- documentation browsing, search, frontmatter/body view, version history, diff and restore; +- inventory browsing with JSON and generated raw views; +- draft changesets with validation results and apply/publish; +- validation and freshness reports with issue details; +- MCP personal key management (create, rotate, revoke, copy-once token); +- settings with per-service language selection and account details; +- en/uk/ru localization through `src/i18n/`. -- documentation browsing; -- inventory browsing; -- validation and freshness reports; -- traffic route inspection; -- recent local change or commit inspection if practical. +All writes go through the backend API; the UI does not edit files directly. -All write operations should initially go through the backend API and agent workflows. +## Architectural notes -## Frontend Decision +- `src/main.js` is the single-page application: no router, page switching is local state. +- Navigation labels are `computed` because `t()` reads a reactive locale; module-level + arrays would freeze the initial language. +- Toasts require `GnToastProvider` at the app root; `useToast()` is used inside it. +- Authentication is disabled when the server has no gnexus-auth client configured; + the UI then runs open for local development and hides the MCP keys page. +- The login button redirects to `/api/auth/login`. gnexus-auth redirects back to + `/auth/callback`, so the dev server proxies `/auth` and `/webhooks` as well as `/api`. -Use: - -- Vue.js; -- `gnexus-ui-kit` as a dependency; -- the FastAPI backend under `server/`. - -Do not replace this with MkDocs as the primary UI. - -Avoid copying UI kit styles into this project unless there is a temporary integration reason. Prefer upstream changes in `gnexus-ui-kit` for shared style decisions. - -## Local Dependency - -The current local development dependency is: +## Local dependency ```json "gnexus-ui-kit": "file:../../gnexus-ui-kit" @@ -55,6 +54,8 @@ This keeps the UI kit as a package dependency while allowing local updates to the official kit source. +Avoid copying UI kit styles into this project unless there is a temporary integration reason. Prefer upstream changes in `gnexus-ui-kit` for shared style decisions. + ## Development ```bash @@ -63,4 +64,6 @@ npm run dev ``` -The dev server runs on port `3006` and proxies `/api/*` to the FastAPI backend on `127.0.0.1:3005`. +The dev server runs on port `3006` and proxies `/api/*`, `/auth/*`, and +`/webhooks/*` to the FastAPI backend on `127.0.0.1:3005`. Build with `npm run build`; +the output is `dist/`. diff --git a/ui/src/i18n/index.js b/ui/src/i18n/index.js new file mode 100644 index 0000000..5b630d1 --- /dev/null +++ b/ui/src/i18n/index.js @@ -0,0 +1,60 @@ +import { ref, watch } from "vue"; +import en from "./messages/en.js"; +import uk from "./messages/uk.js"; +import ru from "./messages/ru.js"; + +export const SUPPORTED_LOCALES = ["en", "uk", "ru"]; +export const localeOptions = [ + { value: "en", label: "English" }, + { value: "uk", label: "Українська" }, + { value: "ru", label: "Русский" } +]; + +const dictionaries = { en, uk, ru }; +export const locale = ref("en"); + +export function normalizeLocale(value) { + const tag = String(value || "en") + .toLowerCase() + .split("-", 1)[0]; + return SUPPORTED_LOCALES.includes(tag) ? tag : "en"; +} + +export function savedLocale() { + try { + return localStorage.getItem("gnb.locale"); + } catch { + return null; + } +} + +export function setLocale(next, { persist = true } = {}) { + const normalized = normalizeLocale(next); + locale.value = normalized; + if (persist) { + try { + localStorage.setItem("gnb.locale", normalized); + } catch { + /* storage may be unavailable */ + } + } +} + +export function t(slug, params = {}) { + const dictionary = dictionaries[locale.value] || en; + const text = dictionary[slug] ?? en[slug] ?? slug; + return String(text).replace(/\{(\w+)\}/g, (_, key) => + params[key] === undefined || params[key] === null ? `{${key}}` : String(params[key]) + ); +} + +watch( + locale, + value => { + if (typeof document !== "undefined") { + document.documentElement.lang = value; + document.title = t("app.title"); + } + }, + { immediate: true } +); diff --git a/ui/src/i18n/messages/en.js b/ui/src/i18n/messages/en.js new file mode 100644 index 0000000..4f53500 --- /dev/null +++ b/ui/src/i18n/messages/en.js @@ -0,0 +1,185 @@ +export default { + "app.title": "Gnexus Book", + "app.kicker": "Knowledge Base", + "app.subtitle": "Infrastructure documentation maintenance console", + + "nav.menu": "Menu", + "nav.docs": "Documents", + "nav.inventory": "Inventory", + "nav.changes": "Changes", + "nav.status": "Status", + "nav.keys": "MCP keys", + "nav.settings": "Settings", + "nav.logout": "Log out", + + "auth.title": "Sign in", + "auth.subtitle": "Gnexus Book uses gnexus-auth single sign-on.", + "auth.loginText": "Sign in with gnexus-auth to read and maintain the knowledge base.", + "auth.login": "Sign in", + "auth.notConfigured": "Authentication is not configured on this server.", + "auth.account": "Account", + "auth.logoutConfirm": "Log out", + "auth.logoutConfirmText": "End this session?", + "auth.loggedOut": "Signed out", + "auth.denied": "Sign-in was cancelled or denied.", + "auth.recheck": "Check session", + "auth.localeAuto": "Auto", + "auth.disabled": "Authentication is disabled", + + "common.refresh": "Refresh", + "common.retry": "Retry", + "common.loading": "Loading", + "common.error": "Error", + "common.cancel": "Cancel", + "common.confirm": "Confirm", + "common.copy": "Copy", + "common.copied": "Copied to clipboard", + "common.close": "Close", + "common.none": "None", + "common.unknown": "Unknown", + "common.actions": "Actions", + "common.status": "Status", + "common.type": "Type", + "common.summary": "Summary", + "common.reason": "Reason", + "common.target": "Target", + "common.content": "Content", + "common.name": "Name", + "common.consumer": "Consumer", + "common.token": "Token", + "common.created": "Created", + "common.lastUsed": "Last used", + "common.revoked": "Revoked", + "common.stale": "Stale", + "common.raw": "Raw", + "common.json": "JSON", + "common.history": "History", + "common.diff": "Diff", + "common.version": "Version", + "common.apply": "Apply", + "common.rotate": "Rotate", + "common.revoke": "Revoke", + "common.create": "Create", + "common.save": "Save", + "common.saved": "Saved", + "common.selected": "Selected", + "common.current": "Current", + "common.issues": "Issues", + "common.issueCount": "{n} issues", + "common.code": "Code", + "common.path": "Path", + "common.message": "Message", + "common.severity": "Severity", + "common.details": "Details", + "common.owner": "Owner", + "common.language": "Language", + "common.filter": "Filter", + "common.showAll": "Show all", + "common.role": "Role", + "common.scopes": "Scopes", + "common.preview": "Preview", + + "docs.title": "Documents", + "docs.subtitle": "Browse, search and version the knowledge base.", + "docs.searchPlaceholder": "Search documents", + "docs.noDocs": "No documents loaded", + "docs.noResults": "Nothing matched this search.", + "docs.select": "Select a document to inspect its metadata and body.", + "docs.frontmatter": "Frontmatter", + "docs.body": "Body", + "docs.versions": "Versions", + "docs.noHistory": "Version history is available in database mode.", + "docs.diffTitle": "Version diff", + "docs.noDiff": "No differences between the selected versions.", + "docs.restore": "Restore", + "docs.restoreConfirm": "Restore version", + "docs.restoreConfirmText": "Create a new version from version {version}?", + "docs.restored": "Version restored", + "docs.proposalTitle": "Propose document change", + "docs.proposalMeta": "Creates a draft changeset", + "docs.targetPlaceholder": "10-systems/example.md", + "docs.contentPlaceholder": "Full Markdown content, including frontmatter", + "docs.submit": "Create draft", + "docs.proposalCreated": "Draft changeset created", + "docs.compare": "Compare with previous", + "docs.currentVersion": "Current version", + "docs.previousVersion": "Previous version", + + "inventory.title": "Inventory", + "inventory.subtitle": "Structured facts about hosts, services and networks.", + "inventory.selectType": "Select an inventory type.", + "inventory.selectRecord": "Select a record to inspect its JSON.", + "inventory.rawView": "Raw", + "inventory.jsonView": "JSON", + "inventory.noRecords": "This inventory type is empty.", + "inventory.noTypes": "No inventory types loaded.", + "inventory.recordCount": "{n} records", + "inventory.filterPlaceholder": "Filter records", + "inventory.rawNotice": "Raw output is generated from database records and may differ from the original YAML formatting.", + + "changes.title": "Changes", + "changes.subtitle": "Draft changesets, validation results and publishing.", + "changes.noChanges": "No changesets yet.", + "changes.apply": "Apply", + "changes.applyConfirm": "Apply changeset", + "changes.applyConfirmText": "Apply this changeset and validate the database?", + "changes.applied": "Changeset applied", + "changes.validation": "Validation", + "changes.noValidation": "Not applied yet", + "changes.select": "Select a changeset to inspect it.", + "changes.draft": "Draft", + "changes.pending": "Pending", + "changes.rejected": "Rejected", + "changes.appliedStatus": "Applied", + + "status.title": "Status", + "status.subtitle": "Validation, freshness and storage health.", + "status.validation": "Validation", + "status.freshness": "Freshness", + "status.noIssues": "No issues.", + "status.issueCount": "{n} issues", + "status.documents": "Documents", + "status.healthy": "Healthy", + "status.issues": "Issues", + "status.storage": "Storage", + + "keys.title": "MCP keys", + "keys.subtitle": "Personal keys for agents that connect over streamable HTTP.", + "keys.notConfigured": "Configure gnexus-auth to manage personal MCP keys.", + "keys.noKeys": "No keys have been issued yet.", + "keys.createTitle": "Issue a key", + "keys.createMeta": "Plaintext is shown once", + "keys.consumer": "Consumer", + "keys.name": "Key name", + "keys.create": "Issue key", + "keys.issuedTitle": "New MCP key", + "keys.issuedText": "Copy this token now. It will not be shown again.", + "keys.copyToken": "Copy token", + "keys.rotate": "Rotate", + "keys.revoke": "Revoke", + "keys.revokeConfirm": "Revoke key", + "keys.revokeConfirmText": "Revoke this key? Agents using it will lose access immediately.", + "keys.revoked": "Key revoked", + "keys.rotated": "Key rotated", + "keys.tokenOnce": "Token shown once", + "keys.showAll": "Show all users", + "keys.own": "My keys", + + "settings.title": "Settings", + "settings.subtitle": "Language, session and service details.", + "settings.language": "Interface language", + "settings.languageMeta": "The account locale is the default; the choice here overrides it for this service.", + "settings.storage": "Storage backend", + "settings.auth": "Authentication", + "settings.authDisabled": "Disabled (local development)", + "settings.about": "About", + "settings.aboutText": "Gnexus Book is the canonical knowledge base for documented infrastructure.", + + "confirm.yes": "Yes", + "confirm.no": "No", + + "errors.loadFailed": "Failed to load data", + "errors.saveFailed": "Failed to save", + "errors.unauthorized": "Session expired. Sign in again.", + "errors.actionFailed": "Action failed", +}; diff --git a/ui/src/i18n/messages/ru.js b/ui/src/i18n/messages/ru.js new file mode 100644 index 0000000..3cfbae9 --- /dev/null +++ b/ui/src/i18n/messages/ru.js @@ -0,0 +1,185 @@ +export default { + "app.title": "Gnexus Book", + "app.kicker": "База знаний", + "app.subtitle": "Консоль поддержки документации инфраструктуры", + + "nav.menu": "Меню", + "nav.docs": "Документы", + "nav.inventory": "Инвентарь", + "nav.changes": "Изменения", + "nav.status": "Состояние", + "nav.keys": "MCP-ключи", + "nav.settings": "Настройки", + "nav.logout": "Выйти", + + "auth.title": "Войти", + "auth.subtitle": "Gnexus Book использует единый вход gnexus-auth.", + "auth.loginText": "Войдите через gnexus-auth, чтобы читать и поддерживать базу знаний.", + "auth.login": "Войти", + "auth.notConfigured": "Аутентификация на этом сервере не настроена.", + "auth.account": "Учётная запись", + "auth.logoutConfirm": "Выйти", + "auth.logoutConfirmText": "Завершить эту сессию?", + "auth.loggedOut": "Вы вышли", + "auth.denied": "Вход отменён или отклонён.", + "auth.recheck": "Проверить сессию", + "auth.localeAuto": "Авто", + "auth.disabled": "Аутентификация отключена", + + "common.refresh": "Обновить", + "common.retry": "Повторить", + "common.loading": "Загрузка", + "common.error": "Ошибка", + "common.cancel": "Отмена", + "common.confirm": "Подтвердить", + "common.copy": "Копировать", + "common.copied": "Скопировано", + "common.close": "Закрыть", + "common.none": "Нет", + "common.unknown": "Неизвестно", + "common.actions": "Действия", + "common.status": "Статус", + "common.type": "Тип", + "common.summary": "Сводка", + "common.reason": "Причина", + "common.target": "Цель", + "common.content": "Содержимое", + "common.name": "Название", + "common.consumer": "Потребитель", + "common.token": "Токен", + "common.created": "Создан", + "common.lastUsed": "Последнее использование", + "common.revoked": "Отозван", + "common.stale": "Устарел", + "common.raw": "Исходный", + "common.json": "JSON", + "common.history": "История", + "common.diff": "Разница", + "common.version": "Версия", + "common.apply": "Применить", + "common.rotate": "Перевыпустить", + "common.revoke": "Отозвать", + "common.create": "Создать", + "common.save": "Сохранить", + "common.saved": "Сохранено", + "common.selected": "Выбрано", + "common.current": "Текущая", + "common.issues": "Проблемы", + "common.issueCount": "{n} проблем", + "common.code": "Код", + "common.path": "Путь", + "common.message": "Сообщение", + "common.severity": "Важность", + "common.details": "Подробности", + "common.owner": "Владелец", + "common.language": "Язык", + "common.filter": "Фильтр", + "common.showAll": "Показать всех пользователей", + "common.role": "Роль", + "common.scopes": "Права", + "common.preview": "Предпросмотр", + + "docs.title": "Документы", + "docs.subtitle": "Просмотр, поиск и версии базы знаний.", + "docs.searchPlaceholder": "Поиск документов", + "docs.noDocs": "Документы не загружены", + "docs.noResults": "По этому запросу ничего не найдено.", + "docs.select": "Выберите документ, чтобы посмотреть метаданные и текст.", + "docs.frontmatter": "Frontmatter", + "docs.body": "Текст", + "docs.versions": "Версии", + "docs.noHistory": "История версий доступна в режиме базы данных.", + "docs.diffTitle": "Разница версий", + "docs.noDiff": "Между выбранными версиями нет различий.", + "docs.restore": "Восстановить", + "docs.restoreConfirm": "Восстановить версию", + "docs.restoreConfirmText": "Создать новую версию из версии {version}?", + "docs.restored": "Версия восстановлена", + "docs.proposalTitle": "Предложить изменение документа", + "docs.proposalMeta": "Создаёт черновик changeset", + "docs.targetPlaceholder": "10-systems/example.md", + "docs.contentPlaceholder": "Полное содержимое Markdown, включая frontmatter", + "docs.submit": "Создать черновик", + "docs.proposalCreated": "Черновик changeset создан", + "docs.compare": "Сравнить с предыдущей", + "docs.currentVersion": "Текущая версия", + "docs.previousVersion": "Предыдущая версия", + + "inventory.title": "Инвентарь", + "inventory.subtitle": "Структурированные факты о хостах, сервисах и сетях.", + "inventory.selectType": "Выберите тип инвентаря.", + "inventory.selectRecord": "Выберите запись, чтобы посмотреть её JSON.", + "inventory.rawView": "Исходный", + "inventory.jsonView": "JSON", + "inventory.noRecords": "Этот тип инвентаря пуст.", + "inventory.noTypes": "Типы инвентаря не загружены.", + "inventory.recordCount": "{n} записей", + "inventory.filterPlaceholder": "Фильтр записей", + "inventory.rawNotice": "Исходный вывод генерируется из записей базы данных и может отличаться от исходного форматирования YAML.", + + "changes.title": "Изменения", + "changes.subtitle": "Черновики changeset, результаты проверки и публикация.", + "changes.noChanges": "Изменений пока нет.", + "changes.apply": "Применить", + "changes.applyConfirm": "Применить changeset", + "changes.applyConfirmText": "Применить этот changeset и проверить базу данных?", + "changes.applied": "Changeset применён", + "changes.validation": "Проверка", + "changes.noValidation": "Ещё не применён", + "changes.select": "Выберите changeset, чтобы посмотреть его.", + "changes.draft": "Черновик", + "changes.pending": "Ожидает", + "changes.rejected": "Отклонён", + "changes.appliedStatus": "Применён", + + "status.title": "Состояние", + "status.subtitle": "Проверка, актуальность и состояние хранилища.", + "status.validation": "Проверка", + "status.freshness": "Актуальность", + "status.noIssues": "Проблем нет.", + "status.issueCount": "{n} проблем", + "status.documents": "Документы", + "status.healthy": "В норме", + "status.issues": "Проблемы", + "status.storage": "Хранилище", + + "keys.title": "MCP-ключи", + "keys.subtitle": "Персональные ключи для агентов, подключающихся через streamable HTTP.", + "keys.notConfigured": "Настройте gnexus-auth, чтобы управлять персональными MCP-ключами.", + "keys.noKeys": "Ключи ещё не выдавались.", + "keys.createTitle": "Выдать ключ", + "keys.createMeta": "Открытый текст показывается один раз", + "keys.consumer": "Потребитель", + "keys.name": "Название ключа", + "keys.create": "Выдать ключ", + "keys.issuedTitle": "Новый MCP-ключ", + "keys.issuedText": "Скопируйте токен сейчас. Больше он не будет показан.", + "keys.copyToken": "Копировать токен", + "keys.rotate": "Перевыпустить", + "keys.revoke": "Отозвать", + "keys.revokeConfirm": "Отозвать ключ", + "keys.revokeConfirmText": "Отозвать этот ключ? Агенты сразу потеряют доступ.", + "keys.revoked": "Ключ отозван", + "keys.rotated": "Ключ перевыпущен", + "keys.tokenOnce": "Токен показан один раз", + "keys.showAll": "Показать всех пользователей", + "keys.own": "Мои ключи", + + "settings.title": "Настройки", + "settings.subtitle": "Язык, сессия и сведения о сервисе.", + "settings.language": "Язык интерфейса", + "settings.languageMeta": "Язык учётной записи используется по умолчанию; выбор здесь перекрывает его для этого сервиса.", + "settings.storage": "Хранилище", + "settings.auth": "Аутентификация", + "settings.authDisabled": "Отключена (локальная разработка)", + "settings.about": "О сервисе", + "settings.aboutText": "Gnexus Book — каноническая база знаний о задокументированной инфраструктуре.", + + "confirm.yes": "Да", + "confirm.no": "Нет", + + "errors.loadFailed": "Не удалось загрузить данные", + "errors.saveFailed": "Не удалось сохранить", + "errors.unauthorized": "Сессия истекла. Войдите снова.", + "errors.actionFailed": "Действие не выполнено", +}; diff --git a/ui/src/i18n/messages/uk.js b/ui/src/i18n/messages/uk.js new file mode 100644 index 0000000..ff1ad9b --- /dev/null +++ b/ui/src/i18n/messages/uk.js @@ -0,0 +1,185 @@ +export default { + "app.title": "Gnexus Book", + "app.kicker": "База знань", + "app.subtitle": "Консоль підтримки документації інфраструктури", + + "nav.menu": "Меню", + "nav.docs": "Документи", + "nav.inventory": "Інвентар", + "nav.changes": "Зміни", + "nav.status": "Стан", + "nav.keys": "MCP-ключі", + "nav.settings": "Налаштування", + "nav.logout": "Вийти", + + "auth.title": "Увійти", + "auth.subtitle": "Gnexus Book використовує єдиний вхід gnexus-auth.", + "auth.loginText": "Увійдіть через gnexus-auth, щоб читати та підтримувати базу знань.", + "auth.login": "Увійти", + "auth.notConfigured": "Автентифікацію на цьому сервері не налаштовано.", + "auth.account": "Обліковий запис", + "auth.logoutConfirm": "Вийти", + "auth.logoutConfirmText": "Завершити цей сеанс?", + "auth.loggedOut": "Ви вийшли", + "auth.denied": "Вхід скасовано або відхилено.", + "auth.recheck": "Перевірити сеанс", + "auth.localeAuto": "Авто", + "auth.disabled": "Автентифікація вимкнена", + + "common.refresh": "Оновити", + "common.retry": "Повторити", + "common.loading": "Завантаження", + "common.error": "Помилка", + "common.cancel": "Скасувати", + "common.confirm": "Підтвердити", + "common.copy": "Копіювати", + "common.copied": "Скопійовано", + "common.close": "Закрити", + "common.none": "Немає", + "common.unknown": "Невідомо", + "common.actions": "Дії", + "common.status": "Статус", + "common.type": "Тип", + "common.summary": "Підсумок", + "common.reason": "Причина", + "common.target": "Ціль", + "common.content": "Вміст", + "common.name": "Назва", + "common.consumer": "Споживач", + "common.token": "Токен", + "common.created": "Створено", + "common.lastUsed": "Останнє використання", + "common.revoked": "Відкликано", + "common.stale": "Застарілий", + "common.raw": "Сирий", + "common.json": "JSON", + "common.history": "Історія", + "common.diff": "Різниця", + "common.version": "Версія", + "common.apply": "Застосувати", + "common.rotate": "Перевипустити", + "common.revoke": "Відкликати", + "common.create": "Створити", + "common.save": "Зберегти", + "common.saved": "Збережено", + "common.selected": "Вибрано", + "common.current": "Поточний", + "common.issues": "Проблеми", + "common.issueCount": "{n} проблем", + "common.code": "Код", + "common.path": "Шлях", + "common.message": "Повідомлення", + "common.severity": "Серйозність", + "common.details": "Деталі", + "common.owner": "Власник", + "common.language": "Мова", + "common.filter": "Фільтр", + "common.showAll": "Показати всі", + "common.role": "Роль", + "common.scopes": "Дозволи", + "common.preview": "Попередній перегляд", + + "docs.title": "Документи", + "docs.subtitle": "Перегляд, пошук і версії бази знань.", + "docs.searchPlaceholder": "Пошук документів", + "docs.noDocs": "Документи не завантажено", + "docs.noResults": "За цим запитом нічого не знайдено.", + "docs.select": "Виберіть документ, щоб переглянути метадані та текст.", + "docs.frontmatter": "Frontmatter", + "docs.body": "Тіло", + "docs.versions": "Версії", + "docs.noHistory": "Історія версій доступна в режимі бази даних.", + "docs.diffTitle": "Різниця версій", + "docs.noDiff": "Між вибраними версіями немає відмінностей.", + "docs.restore": "Відновити", + "docs.restoreConfirm": "Відновити версію", + "docs.restoreConfirmText": "Створити нову версію з версії {version}?", + "docs.restored": "Версію відновлено", + "docs.proposalTitle": "Запропонувати зміну документа", + "docs.proposalMeta": "Створює чернетку changeset", + "docs.targetPlaceholder": "10-systems/example.md", + "docs.contentPlaceholder": "Повний Markdown-вміст, включно з frontmatter", + "docs.submit": "Створити чернетку", + "docs.proposalCreated": "Чернетку changeset створено", + "docs.compare": "Порівняти з попередньою", + "docs.currentVersion": "Поточна версія", + "docs.previousVersion": "Попередня версія", + + "inventory.title": "Інвентар", + "inventory.subtitle": "Структуровані факти про хости, сервіси та мережі.", + "inventory.selectType": "Виберіть тип інвентарю.", + "inventory.selectRecord": "Виберіть запис, щоб переглянути його JSON.", + "inventory.rawView": "Сирий", + "inventory.jsonView": "JSON", + "inventory.noRecords": "Цей тип інвентарю порожній.", + "inventory.noTypes": "Типи інвентарю не завантажено.", + "inventory.recordCount": "{n} записів", + "inventory.filterPlaceholder": "Фільтр записів", + "inventory.rawNotice": "Сирий вивід генерується з записів бази даних і може відрізнятися від початкового форматування YAML.", + + "changes.title": "Зміни", + "changes.subtitle": "Чернетки changeset, результати перевірки та публікація.", + "changes.noChanges": "Змін ще немає.", + "changes.apply": "Застосувати", + "changes.applyConfirm": "Застосувати changeset", + "changes.applyConfirmText": "Застосувати цей changeset і перевірити базу даних?", + "changes.applied": "Changeset застосовано", + "changes.validation": "Перевірка", + "changes.noValidation": "Ще не застосовано", + "changes.select": "Виберіть changeset, щоб переглянути його.", + "changes.draft": "Чернетка", + "changes.pending": "Очікує", + "changes.rejected": "Відхилено", + "changes.appliedStatus": "Застосовано", + + "status.title": "Стан", + "status.subtitle": "Перевірка, актуальність і стан сховища.", + "status.validation": "Перевірка", + "status.freshness": "Актуальність", + "status.noIssues": "Проблем немає.", + "status.issueCount": "{n} проблем", + "status.documents": "Документи", + "status.healthy": "У нормі", + "status.issues": "Проблеми", + "status.storage": "Сховище", + + "keys.title": "MCP-ключі", + "keys.subtitle": "Персональні ключі для агентів, що підключаються через streamable HTTP.", + "keys.notConfigured": "Налаштуйте gnexus-auth, щоб керувати персональними MCP-ключами.", + "keys.noKeys": "Ключів ще не видано.", + "keys.createTitle": "Видати ключ", + "keys.createMeta": "Відкритий текст показується один раз", + "keys.consumer": "Споживач", + "keys.name": "Назва ключа", + "keys.create": "Видати ключ", + "keys.issuedTitle": "Новий MCP-ключ", + "keys.issuedText": "Скопіюйте токен зараз. Більше він не показуватиметься.", + "keys.copyToken": "Копіювати токен", + "keys.rotate": "Перевипустити", + "keys.revoke": "Відкликати", + "keys.revokeConfirm": "Відкликати ключ", + "keys.revokeConfirmText": "Відкликати цей ключ? Агенти негайно втратять доступ.", + "keys.revoked": "Ключ відкликано", + "keys.rotated": "Ключ перевипущено", + "keys.tokenOnce": "Токен показано один раз", + "keys.showAll": "Показати всіх користувачів", + "keys.own": "Мої ключі", + + "settings.title": "Налаштування", + "settings.subtitle": "Мова, сеанс і відомості про сервіс.", + "settings.language": "Мова інтерфейсу", + "settings.languageMeta": "Мова облікового запису є типовою; вибір тут перекриває її для цього сервісу.", + "settings.storage": "Сховище", + "settings.auth": "Автентифікація", + "settings.authDisabled": "Вимкнено (локальна розробка)", + "settings.about": "Про сервіс", + "settings.aboutText": "Gnexus Book — канонічна база знань про задокументовану інфраструктуру.", + + "confirm.yes": "Так", + "confirm.no": "Ні", + + "errors.loadFailed": "Не вдалося завантажити дані", + "errors.saveFailed": "Не вдалося зберегти", + "errors.unauthorized": "Сеанс завершився. Увійдіть знову.", + "errors.actionFailed": "Дія не вдалася", +}; diff --git a/ui/src/main.js b/ui/src/main.js index 3d4f8af..bf5696f 100644 --- a/ui/src/main.js +++ b/ui/src/main.js @@ -1,677 +1,1425 @@ -import { createApp, computed, onMounted, ref } from "vue"; +import { computed, createApp, onMounted, reactive, ref, watch } from "vue"; import "gnexus-ui-kit/dist/css/kit.css"; import "gnexus-ui-kit/dist/assets/fonts/phosphor-icons/src/css/icons.css"; import { + GnAlert, GnBadge, GnButton, + GnCard, + GnConfirmDialog, GnDescriptionList, GnEmptyState, GnInput, GnMetricCard, GnPageHeader, - GnTabs, + GnSearchField, + GnToastProvider, GnToolbar, - GnToastProvider + GnUserCard, + useToast } from "gnexus-ui-kit/vue"; +import { + locale, + localeOptions, + savedLocale, + setLocale, + t +} from "./i18n/index.js"; import "./styles.css"; -const apiGet = async (path) => { - const response = await fetch(`/api${path}`); - if (!response.ok) { - throw new Error(`${path} returned ${response.status}`); - } - return response.json(); +const encodePath = path => + String(path || "") + .split("/") + .map(encodeURIComponent) + .join("/"); + +const pretty = value => + typeof value === "string" ? value : JSON.stringify(value ?? null, null, 2); + +const defaultDocTemplate = () => { + const today = new Date().toISOString().slice(0, 10); + return `---\nowner: gmikcon\nstatus: draft\nlast_reviewed: ${today}\nreview_interval: 30d\nconfidence: medium\nsource_of_truth: manual\n---\n\n# New document\n\n`; }; -const apiPost = async (path, payload = null) => { - const response = await fetch(`/api${path}`, { - method: "POST", - headers: payload ? { "Content-Type": "application/json" } : undefined, - body: payload ? JSON.stringify(payload) : undefined - }); - if (!response.ok) { - const text = await response.text(); - throw new Error(`${path} returned ${response.status}: ${text}`); - } - return response.json(); +const IssueList = { + components: { GnBadge }, + props: { + issues: { type: Array, default: () => [] } + }, + setup() { + return { t }; + }, + template: ` +
+

{{ t('status.noIssues') }}

+
+
+ {{ issue.severity }} + {{ issue.code }} + {{ issue.path }} +
+

{{ issue.message }}

+
+
+ ` }; const AppScreen = { components: { + GnAlert, GnBadge, GnButton, + GnCard, + GnConfirmDialog, GnDescriptionList, GnEmptyState, GnInput, GnMetricCard, GnPageHeader, - GnTabs, - GnToolbar + GnSearchField, + GnToolbar, + GnUserCard, + IssueList }, setup() { - const activeTab = ref("docs"); - const loading = ref(true); - const error = ref(""); - const health = ref(null); - const validation = ref(null); - const freshness = ref(null); + const toast = useToast(); + + const booting = ref(true); + const authEnabled = ref(false); + const user = ref(null); + const localeOverride = ref(null); + const storage = ref("unknown"); + const healthStatus = ref("unknown"); + const pageError = ref(""); + const activePage = ref("docs"); + const drawerOpen = ref(false); + const docs = ref([]); + const docQuery = ref(""); + const searchResults = ref([]); + const searching = ref(false); const selectedDocPath = ref(""); const selectedDoc = ref(null); const docLoading = ref(false); const docError = ref(""); + const docHistory = ref([]); + const historyError = ref(""); + const docDiff = ref(""); + const diffError = ref(""); + const proposal = reactive({ + target: "10-systems/example.md", + summary: "", + reason: "", + content: defaultDocTemplate() + }); + const proposalRunning = ref(false); + const inventoryTypes = ref([]); - const selectedInventoryType = ref(""); + const inventoryType = ref(""); + const inventoryRecords = ref([]); + const inventoryFilter = ref(""); + const selectedInventoryId = ref(""); + const inventoryRaw = ref(false); + const inventoryRawText = ref(""); const inventoryLoading = ref(false); const inventoryError = ref(""); - const inventoryRecords = ref([]); - const selectedInventoryId = ref(""); + const changes = ref([]); const selectedChangeId = ref(""); const selectedChange = ref(null); const changeLoading = ref(false); - const changeApplying = ref(false); const changeError = ref(""); - const proposalSummary = ref(""); - const proposalTarget = ref("10-systems/new-document.md"); - const proposalReason = ref(""); - const proposalContent = ref( - "---\nowner: gmikcon\nstatus: draft\nlast_reviewed: 2026-05-09\nreview_interval: 90d\nconfidence: medium\nsource_of_truth: manual\n---\n\n# New Document\n\n" - ); - const proposalRunning = ref(false); - const proposalError = ref(""); - const gitStatus = ref(null); - const selectedCommitFiles = ref([]); - const commitSummary = ref(""); - const commitDetails = ref(""); - const commitRunning = ref(false); - const commitError = ref(""); - const commitResult = ref(null); + const applyingChange = ref(false); - const tabs = [ - { id: "docs", label: "Docs", icon: "ph-files" }, - { id: "inventory", label: "Inventory", icon: "ph-database" }, - { id: "changes", label: "Changes", icon: "ph-git-pull-request" }, - { id: "git", label: "Git", icon: "ph-git-branch" } - ]; + const validation = ref(null); + const freshness = ref(null); - const validationVariant = computed(() => - validation.value?.status === "ok" ? "success" : "danger" - ); + const keys = ref([]); + const keysShowAll = ref(false); + const keysLoading = ref(false); + const keysError = ref(""); + const issuedToken = ref(""); + const issuedKey = ref(null); + const keyForm = reactive({ consumer: "claude-code", name: "" }); - const freshnessVariant = computed(() => - freshness.value?.status === "ok" ? "success" : "danger" - ); - - const overview = computed(() => [ - { key: "repo", term: "Repository", value: health.value?.repo_root || "unknown" }, - { key: "validation", term: "Validation", value: validation.value?.status || "unknown" }, - { key: "freshness", term: "Freshness", value: freshness.value?.status || "unknown" } - ]); - - const selectedDocFrontmatterJson = computed(() => { - if (!selectedDoc.value?.frontmatter) { - return ""; - } - return JSON.stringify(selectedDoc.value.frontmatter, null, 2); + const confirmState = reactive({ + open: false, + title: "", + message: "", + confirmText: "", + variant: "warning", + action: null }); - const loadDoc = async (path) => { + let searchTimer = null; + + const userDisplayName = computed( + () => + user.value?.display_name || + user.value?.email || + user.value?.user_id || + "" + ); + const userInitials = computed(() => { + const source = userDisplayName.value || "?"; + return source + .split(/\s+/) + .slice(0, 2) + .map(part => part[0]) + .join("") + .toUpperCase() + .slice(0, 2); + }); + const isAuthenticated = computed( + () => !authEnabled.value || Boolean(user.value) + ); + const canWrite = computed( + () => !authEnabled.value || Boolean(user.value) + ); + const isAdmin = computed(() => user.value?.system_role === "admin"); + const storageIsDb = computed(() => storage.value === "db"); + + const navItems = computed(() => [ + { id: "docs", label: t("nav.docs"), icon: "ph-files" }, + { id: "inventory", label: t("nav.inventory"), icon: "ph-database" }, + { id: "changes", label: t("nav.changes"), icon: "ph-git-pull-request" }, + { id: "status", label: t("nav.status"), icon: "ph-heartbeat" }, + ...(authEnabled.value && user.value + ? [{ id: "keys", label: t("nav.keys"), icon: "ph-key" }] + : []), + { id: "settings", label: t("nav.settings"), icon: "ph-sliders" } + ]); + + const pageMeta = computed( + () => + ({ + docs: { title: t("docs.title"), subtitle: t("docs.subtitle") }, + inventory: { + title: t("inventory.title"), + subtitle: t("inventory.subtitle") + }, + changes: { + title: t("changes.title"), + subtitle: t("changes.subtitle") + }, + status: { title: t("status.title"), subtitle: t("status.subtitle") }, + keys: { title: t("keys.title"), subtitle: t("keys.subtitle") }, + settings: { + title: t("settings.title"), + subtitle: t("settings.subtitle") + } + })[activePage.value] || { + title: t("app.title"), + subtitle: t("app.subtitle") + } + ); + const pageTitle = computed(() => pageMeta.value.title); + const pageSubtitle = computed(() => pageMeta.value.subtitle); + const activeLocaleLabel = computed( + () => + (localeOptions.find(option => option.value === locale.value) || localeOptions[0]) + .label + ); + const settingsItems = computed(() => [ + { + key: "storage", + term: t("settings.storage"), + value: storage.value || t("common.unknown") + }, + { + key: "health", + term: t("common.status"), + value: healthStatus.value || t("common.unknown") + }, + { + key: "auth", + term: t("settings.auth"), + value: authEnabled.value ? t("auth.title") : t("settings.authDisabled") + }, + { + key: "account", + term: t("auth.account"), + value: user.value + ? `${userDisplayName.value} · ${user.value.email || user.value.user_id}` + : t("common.none") + }, + { + key: "language", + term: t("settings.language"), + value: activeLocaleLabel.value + } + ]); + + const filteredInventory = computed(() => { + const query = inventoryFilter.value.trim().toLowerCase(); + if (!query) return inventoryRecords.value; + return inventoryRecords.value.filter(item => + [item.id, item.name, item.fqdn, item.host] + .filter(Boolean) + .some(value => String(value).toLowerCase().includes(query)) + ); + }); + const selectedInventoryRecord = computed( + () => + inventoryRecords.value.find( + item => item.id === selectedInventoryId.value + ) || null + ); + const inventoryDisplay = computed(() => { + if (inventoryRaw.value) return inventoryRawText.value; + return selectedInventoryRecord.value + ? pretty(selectedInventoryRecord.value) + : ""; + }); + + const formatDate = value => { + if (!value) return "—"; + const date = new Date(value); + return Number.isNaN(date.getTime()) + ? String(value) + : date.toLocaleString(locale.value); + }; + const statusLabel = status => + ({ + draft: t("changes.draft"), + pending: t("changes.pending"), + applied: t("changes.appliedStatus"), + rejected: t("changes.rejected") + })[status] || status; + const changeStatusVariant = status => + status === "applied" + ? "success" + : status === "rejected" + ? "danger" + : "secondary"; + const isLatestVersion = versionNo => { + if (!docHistory.value.length) return false; + const latest = Math.max( + ...docHistory.value.map(version => version.version_no) + ); + return versionNo === latest; + }; + + async function request(path, options = {}) { + const response = await fetch(`/api${path}`, { + credentials: "same-origin", + ...options + }); + if (response.status === 401) { + user.value = null; + throw new Error(t("errors.unauthorized")); + } + if (response.status === 204) return null; + if (!response.ok) { + const text = await response.text(); + let detail = text; + try { + const data = JSON.parse(text); + detail = data.detail || data.error || text; + } catch { + /* keep text */ + } + throw new Error(`${response.status}: ${detail}`); + } + const contentType = response.headers.get("content-type") || ""; + return contentType.includes("application/json") + ? response.json() + : response.text(); + } + const apiGet = path => request(path); + const apiSend = (path, method, body) => + request(path, { + method, + headers: body ? { "Content-Type": "application/json" } : undefined, + body: body ? JSON.stringify(body) : undefined + }); + + async function loadMe() { + booting.value = true; + pageError.value = ""; + try { + const response = await fetch("/api/me", { + credentials: "same-origin" + }); + if (!response.ok) { + throw new Error(`/me ${response.status}`); + } + const data = await response.json(); + authEnabled.value = Boolean(data.auth_enabled); + user.value = data.user || null; + localeOverride.value = data.locale || null; + if (data.user && data.locale_effective) { + setLocale(data.locale_effective); + } else if (!data.user) { + setLocale(savedLocale() || data.locale_effective || "en"); + } + + const params = new URLSearchParams(window.location.search); + if (params.get("auth_error")) { + pageError.value = t("auth.denied"); + window.history.replaceState({}, "", window.location.pathname); + } + } catch (error) { + pageError.value = + error instanceof Error ? error.message : t("errors.loadFailed"); + } finally { + booting.value = false; + } + + if (isAuthenticated.value) { + await loadAll(); + } + } + + async function loadAll() { + pageError.value = ""; + const results = await Promise.allSettled([ + apiGet("/health"), + apiGet("/docs"), + apiGet("/inventory"), + apiGet("/changes"), + apiGet("/validate"), + apiGet("/health/freshness"), + authEnabled.value && user.value + ? apiGet("/mcp-keys") + : Promise.resolve(null) + ]); + const [health, docsResult, inventoryResult, changesResult, validationResult, freshnessResult, keysResult] = + results; + + if (health.status === "fulfilled") { + storage.value = health.value?.storage || "unknown"; + healthStatus.value = health.value?.status || "unknown"; + } + if (docsResult.status === "fulfilled") { + docs.value = docsResult.value || []; + if ( + selectedDocPath.value && + docs.value.some(doc => doc.path === selectedDocPath.value) + ) { + await loadDoc(selectedDocPath.value); + } else if (docs.value.length) { + await loadDoc(docs.value[0].path); + } + } + if (inventoryResult.status === "fulfilled") { + inventoryTypes.value = inventoryResult.value || []; + if ( + inventoryType.value && + inventoryTypes.value.includes(inventoryType.value) + ) { + await loadInventoryType(inventoryType.value); + } else if (inventoryTypes.value.length) { + await loadInventoryType(inventoryTypes.value[0]); + } + } + if (changesResult.status === "fulfilled") { + changes.value = changesResult.value || []; + if ( + selectedChangeId.value && + changes.value.some(change => change.id === selectedChangeId.value) + ) { + await loadChange(selectedChangeId.value); + } else if (changes.value.length) { + await loadChange(changes.value[0].id); + } else { + selectedChangeId.value = ""; + selectedChange.value = null; + } + } + if (validationResult.status === "fulfilled") { + validation.value = validationResult.value; + } + if (freshnessResult.status === "fulfilled") { + freshness.value = freshnessResult.value; + } + if (keysResult.status === "fulfilled" && keysResult.value) { + keys.value = keysResult.value.items || []; + } + + const failed = results.find(result => result.status === "rejected"); + if (failed) { + pageError.value = + failed.reason?.message || t("errors.loadFailed"); + } + } + + async function loadDoc(path) { + if (!path) return; + if (docQuery.value) docQuery.value = ""; selectedDocPath.value = path; selectedDoc.value = null; docLoading.value = true; docError.value = ""; + docHistory.value = []; + historyError.value = ""; + docDiff.value = ""; + diffError.value = ""; try { - selectedDoc.value = await apiGet(`/docs/read?path=${encodeURIComponent(path)}`); - } catch (caught) { - docError.value = caught instanceof Error ? caught.message : `Failed to load document ${path}`; + selectedDoc.value = await apiGet( + `/docs/read?path=${encodeURIComponent(path)}` + ); + if (storageIsDb.value) { + try { + docHistory.value = await apiGet( + `/documents/${encodePath(path)}/history` + ); + } catch { + historyError.value = t("docs.noHistory"); + } + } else { + historyError.value = t("docs.noHistory"); + } + } catch (error) { + docError.value = + error instanceof Error ? error.message : t("errors.loadFailed"); } finally { docLoading.value = false; } - }; + } - const selectedInventoryRecord = computed(() => { - if (!selectedInventoryId.value) { - return null; + async function requestDiff(fromVersion, toVersion) { + docDiff.value = ""; + diffError.value = ""; + if (!selectedDocPath.value) return; + try { + const data = await apiGet( + `/documents/${encodePath(selectedDocPath.value)}/diff?from=${fromVersion}&to=${toVersion}` + ); + docDiff.value = data.diff || ""; + if (!docDiff.value) diffError.value = t("docs.noDiff"); + } catch (error) { + diffError.value = + error instanceof Error ? error.message : t("errors.loadFailed"); } - return inventoryRecords.value.find((item) => item?.id === selectedInventoryId.value) || null; - }); + } - const selectedInventoryRecordJson = computed(() => { - if (!selectedInventoryRecord.value) { - return ""; - } - return JSON.stringify(selectedInventoryRecord.value, null, 2); - }); + async function loadDiffFrom(versionNo) { + const latest = docHistory.value.length + ? Math.max(...docHistory.value.map(version => version.version_no)) + : versionNo; + await requestDiff(versionNo, latest); + } - const inventoryRecordTitle = (item) => item?.name || item?.fqdn || item?.id || "unknown"; + async function loadLatestDiff() { + if (!docHistory.value.length) return; + const latest = Math.max( + ...docHistory.value.map(version => version.version_no) + ); + await requestDiff(Math.max(1, latest - 1), latest); + } - const selectedChangeJson = computed(() => { - if (!selectedChange.value) { - return ""; - } - return JSON.stringify(selectedChange.value, null, 2); - }); + function restoreVersion(versionNo) { + askConfirm({ + title: t("docs.restoreConfirm"), + message: t("docs.restoreConfirmText", { version: versionNo }), + confirmText: t("docs.restore"), + variant: "warning", + action: async () => { + try { + await apiSend( + `/documents/${encodePath(selectedDocPath.value)}/restore/${versionNo}?summary=${encodeURIComponent( + `${t("docs.restoreConfirm")} ${versionNo}` + )}`, + "POST" + ); + toast.success({ title: t("docs.restored") }); + await loadDoc(selectedDocPath.value); + await refreshChanges(); + } catch (error) { + toast.danger({ + title: t("errors.actionFailed"), + text: error instanceof Error ? error.message : t("errors.actionFailed") + }); + } + } + }); + } - const changeStatusVariant = (status) => { - if (status === "applied") { - return "success"; - } - if (status === "rejected") { - return "danger"; - } - return "secondary"; - }; - - const isCommittablePath = (path) => { - if (!path) { - return false; - } - const denied = [ - ".codex", - ".git", - ".pytest_cache", - ".ruff_cache", - ".venv", - "__pycache__", - "gnexus_book_server.egg-info", - "node_modules" - ]; - return !path.split("/").some((part) => denied.includes(part)); - }; - - const committableEntries = computed(() => - (gitStatus.value?.entries || []).filter((entry) => isCommittablePath(entry.path)) - ); - - const commitCanRun = computed( - () => commitSummary.value.trim().length > 0 && selectedCommitFiles.value.length > 0 && !commitRunning.value - ); - - const syncCommitSelection = (gitData) => { - const allowed = (gitData?.entries || []) - .map((entry) => entry.path) - .filter((path) => isCommittablePath(path)); - selectedCommitFiles.value = selectedCommitFiles.value.filter((path) => allowed.includes(path)); - if (!selectedCommitFiles.value.length) { - selectedCommitFiles.value = allowed; - } - }; - - const toggleCommitFile = (path) => { - if (!isCommittablePath(path)) { + async function submitProposal() { + if ( + !proposal.summary.trim() || + !proposal.target.trim() || + !proposal.content.trim() + ) { + toast.warning({ + title: t("common.error"), + text: t("docs.proposalMeta") + }); return; } - if (selectedCommitFiles.value.includes(path)) { - selectedCommitFiles.value = selectedCommitFiles.value.filter((item) => item !== path); - } else { - selectedCommitFiles.value = [...selectedCommitFiles.value, path]; + proposalRunning.value = true; + try { + const created = await apiSend("/changes", "POST", { + kind: "doc", + target: proposal.target.trim(), + summary: proposal.summary.trim(), + reason: proposal.reason.trim(), + payload: { content: proposal.content } + }); + toast.success({ + title: t("docs.proposalCreated"), + text: created.target || created.id + }); + proposal.summary = ""; + proposal.reason = ""; + activePage.value = "changes"; + drawerOpen.value = false; + await refreshChanges(); + await loadChange(created.id); + } catch (error) { + toast.danger({ + title: t("errors.actionFailed"), + text: error instanceof Error ? error.message : t("errors.actionFailed") + }); + } finally { + proposalRunning.value = false; } - }; + } - const loadInventoryType = async (type) => { - selectedInventoryType.value = type; + async function refreshChanges() { + try { + changes.value = await apiGet("/changes"); + if ( + selectedChangeId.value && + changes.value.some(change => change.id === selectedChangeId.value) + ) { + await loadChange(selectedChangeId.value); + } else if (changes.value.length) { + await loadChange(changes.value[0].id); + } else { + selectedChangeId.value = ""; + selectedChange.value = null; + } + } catch (error) { + changeError.value = + error instanceof Error ? error.message : t("errors.loadFailed"); + } + } + + async function loadChange(id) { + selectedChangeId.value = id; + changeLoading.value = true; + changeError.value = ""; + try { + selectedChange.value = await apiGet( + `/changes/${encodeURIComponent(id)}` + ); + } catch (error) { + selectedChange.value = null; + changeError.value = + error instanceof Error ? error.message : t("errors.loadFailed"); + } finally { + changeLoading.value = false; + } + } + + function applyChange(change) { + if (!change) return; + askConfirm({ + title: t("changes.applyConfirm"), + message: t("changes.applyConfirmText"), + confirmText: t("changes.apply"), + variant: "success", + action: async () => { + applyingChange.value = true; + try { + await apiSend( + `/changes/${encodeURIComponent(change.id)}/apply`, + "POST" + ); + toast.success({ title: t("changes.applied") }); + await refreshChanges(); + await refreshStatus(); + } catch (error) { + toast.danger({ + title: t("errors.actionFailed"), + text: error instanceof Error ? error.message : t("errors.actionFailed") + }); + } finally { + applyingChange.value = false; + } + } + }); + } + + async function refreshStatus() { + const results = await Promise.allSettled([ + apiGet("/validate"), + apiGet("/health/freshness") + ]); + if (results[0].status === "fulfilled") validation.value = results[0].value; + if (results[1].status === "fulfilled") freshness.value = results[1].value; + } + + async function loadInventoryType(type) { + if (!type) return; + inventoryType.value = type; selectedInventoryId.value = ""; inventoryLoading.value = true; inventoryError.value = ""; try { - const records = await apiGet(`/inventory/${type}`); - inventoryRecords.value = Array.isArray(records) ? records : []; + inventoryRecords.value = (await apiGet(`/inventory/${encodeURIComponent(type)}`)) || []; selectedInventoryId.value = inventoryRecords.value[0]?.id || ""; - } catch (caught) { + if (inventoryRaw.value) await refreshInventoryRaw(); + } catch (error) { inventoryRecords.value = []; inventoryError.value = - caught instanceof Error ? caught.message : `Failed to load inventory ${type}`; + error instanceof Error ? error.message : t("errors.loadFailed"); } finally { inventoryLoading.value = false; } - }; + } - const selectInventoryRecord = (item) => { - selectedInventoryId.value = item?.id || ""; - }; - - const loadChange = async (id) => { - selectedChangeId.value = id; - selectedChange.value = null; - changeLoading.value = true; - changeError.value = ""; - try { - selectedChange.value = await apiGet(`/changes/${encodeURIComponent(id)}`); - } catch (caught) { - changeError.value = caught instanceof Error ? caught.message : `Failed to load change ${id}`; - } finally { - changeLoading.value = false; - } - }; - - const applySelectedChange = async () => { - if (!selectedChangeId.value) { + async function refreshInventoryRaw() { + if (!inventoryType.value) { + inventoryRawText.value = ""; return; } - changeApplying.value = true; - changeError.value = ""; try { - selectedChange.value = await apiPost(`/changes/${encodeURIComponent(selectedChangeId.value)}/apply`); - const [changesData, validationData, freshnessData, gitData] = await Promise.all([ - apiGet("/changes"), - apiGet("/validate"), - apiGet("/health/freshness"), - apiGet("/git/status") - ]); - changes.value = changesData; - validation.value = validationData; - freshness.value = freshnessData; - gitStatus.value = gitData; - syncCommitSelection(gitData); - } catch (caught) { - changeError.value = caught instanceof Error ? caught.message : "Failed to apply change"; - } finally { - changeApplying.value = false; + const data = await apiGet( + `/inventory/${encodeURIComponent(inventoryType.value)}?raw=true` + ); + inventoryRawText.value = data.raw || ""; + } catch (error) { + inventoryError.value = + error instanceof Error ? error.message : t("errors.loadFailed"); + inventoryRaw.value = false; } - }; + } - const proposeDocChange = async () => { - if (!proposalSummary.value.trim() || !proposalTarget.value.trim() || !proposalContent.value.trim()) { - proposalError.value = "Summary, target, and content are required"; + async function toggleInventoryRaw() { + inventoryRaw.value = !inventoryRaw.value; + if (inventoryRaw.value) { + await refreshInventoryRaw(); + } + } + + async function loadKeys() { + if (!user.value) return; + keysLoading.value = true; + keysError.value = ""; + try { + const data = await apiGet( + `/mcp-keys${keysShowAll.value ? "?all=true" : ""}` + ); + keys.value = data.items || []; + } catch (error) { + keysError.value = + error instanceof Error ? error.message : t("errors.loadFailed"); + } finally { + keysLoading.value = false; + } + } + + async function createKey() { + if (!keyForm.consumer.trim()) { + toast.warning({ title: t("common.error"), text: t("keys.consumer") }); return; } - proposalRunning.value = true; - proposalError.value = ""; + keysLoading.value = true; + keysError.value = ""; try { - const created = await apiPost("/changes", { - kind: "doc", - target: proposalTarget.value.trim(), - summary: proposalSummary.value.trim(), - reason: proposalReason.value.trim(), - payload: { - content: proposalContent.value + const data = await apiSend("/mcp-keys", "POST", { + consumer: keyForm.consumer.trim(), + name: keyForm.name.trim() + }); + issuedToken.value = data.token; + issuedKey.value = data; + keyForm.name = ""; + toast.success({ title: t("keys.issuedTitle") }); + await loadKeys(); + } catch (error) { + keysError.value = + error instanceof Error ? error.message : t("errors.actionFailed"); + } finally { + keysLoading.value = false; + } + } + + function rotateKey(key) { + askConfirm({ + title: t("keys.rotate"), + message: t("keys.issuedText"), + confirmText: t("keys.rotate"), + variant: "warning", + action: async () => { + try { + const data = await apiSend( + `/mcp-keys/${encodeURIComponent(key.key_id)}/rotate`, + "POST" + ); + issuedToken.value = data.token; + issuedKey.value = data; + toast.success({ title: t("keys.rotated") }); + await loadKeys(); + } catch (error) { + toast.danger({ + title: t("errors.actionFailed"), + text: error instanceof Error ? error.message : t("errors.actionFailed") + }); } - }); - changes.value = await apiGet("/changes"); - await loadChange(created.id); - proposalSummary.value = ""; - proposalReason.value = ""; - } catch (caught) { - proposalError.value = caught instanceof Error ? caught.message : "Failed to propose change"; - } finally { - proposalRunning.value = false; - } - }; + } + }); + } - const commitSelectedFiles = async () => { - if (!commitCanRun.value) { + function revokeKey(key) { + askConfirm({ + title: t("keys.revokeConfirm"), + message: t("keys.revokeConfirmText"), + confirmText: t("keys.revoke"), + variant: "danger", + action: async () => { + try { + await apiSend( + `/mcp-keys/${encodeURIComponent(key.key_id)}`, + "DELETE" + ); + toast.success({ title: t("keys.revoked") }); + await loadKeys(); + } catch (error) { + toast.danger({ + title: t("errors.actionFailed"), + text: error instanceof Error ? error.message : t("errors.actionFailed") + }); + } + } + }); + } + + async function copyToken() { + try { + await navigator.clipboard.writeText(issuedToken.value); + toast.success({ title: t("common.copied") }); + } catch { + toast.danger({ title: t("errors.actionFailed") }); + } + } + + function dismissIssued() { + issuedToken.value = ""; + issuedKey.value = null; + } + + async function toggleAllKeys() { + if (!isAdmin.value) return; + keysShowAll.value = !keysShowAll.value; + await loadKeys(); + } + + async function changeLocale(value) { + if (!authEnabled.value || !user.value) { + setLocale(value); + localeOverride.value = null; + toast.success({ title: t("common.saved") }); return; } - commitRunning.value = true; - commitError.value = ""; - commitResult.value = null; try { - commitResult.value = await apiPost("/commit", { - summary: commitSummary.value.trim(), - details: commitDetails.value.trim(), - files: selectedCommitFiles.value + if (value === "auto") { + await apiSend("/me", "PATCH", { locale: "" }); + const data = await apiGet("/me"); + user.value = data.user; + localeOverride.value = null; + setLocale(data.locale_effective || "en"); + } else { + await apiSend("/me", "PATCH", { locale: value }); + localeOverride.value = value; + setLocale(value); + } + toast.success({ title: t("common.saved") }); + } catch (error) { + toast.danger({ + title: t("errors.saveFailed"), + text: error instanceof Error ? error.message : t("errors.saveFailed") }); - commitSummary.value = ""; - commitDetails.value = ""; - const [gitData, validationData] = await Promise.all([ - apiGet("/git/status"), - apiGet("/validate") - ]); - gitStatus.value = gitData; - validation.value = validationData; - syncCommitSelection(gitData); - } catch (caught) { - commitError.value = caught instanceof Error ? caught.message : "Commit failed"; - } finally { - commitRunning.value = false; } - }; + } - const load = async () => { - loading.value = true; - error.value = ""; - try { - const [ - healthData, - validationData, - freshnessData, - docsData, - inventoryData, - changesData, - gitData - ] = await Promise.all([ - apiGet("/health"), - apiGet("/validate"), - apiGet("/health/freshness"), - apiGet("/docs"), - apiGet("/inventory"), - apiGet("/changes"), - apiGet("/git/status") - ]); - health.value = healthData; - validation.value = validationData; - freshness.value = freshnessData; - docs.value = docsData; - inventoryTypes.value = inventoryData; - changes.value = changesData; - gitStatus.value = gitData; - syncCommitSelection(gitData); - if (!selectedChangeId.value && changesData.length) { - await loadChange(changesData[0].id); + function login() { + window.location.assign("/api/auth/login"); + } + + function logout() { + askConfirm({ + title: t("auth.logoutConfirm"), + message: t("auth.logoutConfirmText"), + confirmText: t("nav.logout"), + variant: "danger", + action: async () => { + try { + await apiSend("/auth/logout", "POST"); + } catch { + /* the local session is cleared regardless */ + } + user.value = null; + localeOverride.value = null; + activePage.value = "docs"; + toast.info({ title: t("auth.loggedOut") }); } - if (!selectedDocPath.value && docsData.length) { - await loadDoc(docsData[0].path); - } - if (!selectedInventoryType.value && inventoryData.length) { - await loadInventoryType(inventoryData[0]); - } - } catch (caught) { - error.value = caught instanceof Error ? caught.message : "Failed to load API data"; - } finally { - loading.value = false; + }); + } + + function askConfirm({ title, message, confirmText, variant, action }) { + confirmState.title = title || ""; + confirmState.message = message || ""; + confirmState.confirmText = confirmText || ""; + confirmState.variant = variant || "warning"; + confirmState.action = action || null; + confirmState.open = true; + } + + function runConfirm() { + const action = confirmState.action; + confirmState.action = null; + if (action) action(); + } + + function clearConfirm() { + confirmState.action = null; + } + + function go(page) { + activePage.value = page; + drawerOpen.value = false; + if (page === "keys") loadKeys(); + if (page === "status") refreshStatus(); + } + + async function refreshAll() { + await loadMe(); + } + + watch(docQuery, value => { + window.clearTimeout(searchTimer); + const query = value.trim(); + if (!query) { + searchResults.value = []; + searching.value = false; + return; } - }; + searching.value = true; + searchTimer = window.setTimeout(async () => { + try { + searchResults.value = await apiGet( + `/search?q=${encodeURIComponent(query)}` + ); + } catch (error) { + toast.danger({ + title: t("errors.loadFailed"), + text: error instanceof Error ? error.message : t("errors.loadFailed") + }); + } finally { + searching.value = false; + } + }, 300); + }); - onMounted(load); + onMounted(loadMe); return { - activeTab, - applySelectedChange, - changeApplying, + activeLocaleLabel, + activePage, + applyingChange, + applyChange, + authEnabled, + booting, + canWrite, changeError, changeLoading, - changeStatusVariant, changes, - commitCanRun, - commitDetails, - commitError, - commitResult, - commitRunning, - commitSelectedFiles, - commitSummary, - committableEntries, + changeStatusVariant, + clearConfirm, + confirmState, + copyToken, + createKey, + diffError, + dismissIssued, + docDiff, docError, + docHistory, docLoading, + docQuery, docs, - error, + drawerOpen, + filteredInventory, + formatDate, freshness, - freshnessVariant, - gitStatus, + go, + healthStatus, + historyError, + inventoryDisplay, inventoryError, + inventoryFilter, inventoryLoading, - inventoryRecordTitle, + inventoryRaw, inventoryRecords, + inventoryType, inventoryTypes, - load, + isAdmin, + isLatestVersion, + issuedKey, + issuedToken, + keyForm, + keys, + keysError, + keysLoading, + keysShowAll, + loadDiffFrom, loadDoc, loadInventoryType, - loading, - overview, - proposalContent, - proposalError, - proposalReason, + loadKeys, + loadLatestDiff, + locale, + localeOptions, + localeOverride, + login, + logout, + navItems, + pageError, + pageSubtitle, + pageTitle, + pretty, + proposal, proposalRunning, - proposalSummary, - proposalTarget, - proposeDocChange, - selectedInventoryId, - selectedInventoryRecord, - selectedInventoryRecordJson, - selectedInventoryType, - selectedDoc, - selectedDocFrontmatterJson, - selectedDocPath, + refreshAll, + restoreVersion, + revokeKey, + rotateKey, + runConfirm, + searchResults, + searching, selectedChange, selectedChangeId, - selectedChangeJson, - selectedCommitFiles, - selectInventoryRecord, - loadChange, - toggleCommitFile, - isCommittablePath, - tabs, - validation, - validationVariant + selectedDoc, + selectedDocPath, + selectedInventoryId, + selectedInventoryRecord, + setActiveLocale: changeLocale, + settingsItems, + statusLabel, + storage, + storageIsDb, + submitProposal, + t, + toast, + toggleAllKeys, + toggleInventoryRaw, + user, + userDisplayName, + userInitials, + validation }; }, template: ` -
- - - +
+
+

{{ t('common.loading') }}…

+
-
- - - +
+ + +

{{ t('auth.loginText') }}

+ {{ pageError }} +
+ {{ t('auth.login') }} + {{ t('auth.recheck') }} +
+
-
- - - - -
{{ error }}
-
+
+ +
-
- - +
- - - - - - +
+ +
+
+ + +
+ + + + {{ changeError }} + +
+ +
{{ pretty(selectedChange) }}
+
+ +

{{ t('changes.noValidation') }}

+ +
+
+
+
+
+ +
+
+ + + +
+
+ + + + + + +
+
+ +
+ {{ t('keys.notConfigured') }} +
+ +

{{ t('keys.createMeta') }}

+
+ + +
+ {{ t('keys.create') }} + {{ keysShowAll ? t('keys.own') : t('keys.showAll') }} +
+
+ + {{ t('keys.issuedTitle') }} +

{{ t('keys.issuedText') }}

+

{{ issuedKey.consumer }} · …{{ issuedKey.token_hint }}

+ {{ issuedToken }} +
+ {{ t('keys.copyToken') }} + {{ t('common.close') }} +
+
+ {{ keysError }} +
+ + + +
+
+
+ {{ key.name }} + {{ key.consumer }} · {{ key.role || t('common.unknown') }} · {{ (key.scopes || []).join(', ') }} · …{{ key.token_hint }} + {{ t('common.created') }}: {{ formatDate(key.created_at) }} · {{ t('common.lastUsed') }}: {{ formatDate(key.last_used_at) }} +
+ {{ t('common.revoked') }} + {{ t('common.stale') }} +
+
+
+ {{ t('keys.rotate') }} + {{ t('keys.revoke') }} +
+
+
+
+
+
+ +
+
+ +

{{ t('settings.languageMeta') }}

+
+ {{ t('auth.localeAuto') }} + {{ option.label }} +
+
+ + +
+ {{ t('nav.logout') }} +
+
+
+
+
+ +
` }; diff --git a/ui/src/styles.css b/ui/src/styles.css index 75fdad1..8d1e27f 100644 --- a/ui/src/styles.css +++ b/ui/src/styles.css @@ -1,99 +1,172 @@ -body { - margin: 0; - background: #16161e; - color: #c0caf5; +html, +body, +#app { + min-height: 100%; } -#app { +body { + margin: 0; + background: var(--gn-surface-page); + color: var(--gn-color-text-light); + font-family: var(--gn-font-family-base); +} + +.gnb-app { min-height: 100vh; } -.gnb-shell { - width: min(100% - 48px, 1380px); - max-width: none; +.gnb-boot, +.gnb-gate { + max-width: 760px; margin: 0 auto; - padding: 24px 0 56px; + padding: 32px; } -.gnb-shell > .page-header, -.gnb-shell > .section { - width: 100%; +.gnb-boot { + color: var(--gn-color-text-medium); } -.gnb-shell .page-header { +.gnb-shell { display: grid; - grid-template-columns: minmax(0, 1fr) auto; - align-items: center; - gap: 24px; + grid-template-columns: 260px minmax(0, 1fr); + min-height: 100vh; } -.gnb-shell .page-header-actions, -.gnb-shell .toolbar > .toolbar-group:last-child { +.gnb-sidebar { + position: sticky; + top: 0; + height: 100vh; display: flex; - flex-wrap: wrap; - justify-content: flex-end; - gap: 8px; + flex-direction: column; + gap: 16px; + padding: 16px; + border-right: 1px solid var(--gn-border-color-base); + background: var(--gn-surface-panel); } -.gnb-shell .btn { - white-space: nowrap; +.gnb-brand { + display: flex; + gap: 12px; + align-items: center; + padding: 8px; } -.gnb-shell .btn.with-icon { - min-width: 150px; -} - -.gnb-shell .tabs { - max-width: 100%; - overflow-x: auto; - padding-bottom: 2px; -} - -.gnb-shell .description-list { - max-width: none; -} - -.gnb-shell .toolbar { - margin-bottom: 12px; -} - -.gnb-shell .tabs-panels { - width: 100%; -} - -.gnb-status { +.gnb-brand-mark { + width: 42px; + height: 42px; display: grid; - grid-template-columns: repeat(3, minmax(0, 1fr)); - gap: 48px; - justify-items: center; - margin: 24px 0; + place-items: center; + background: var(--gn-color-accent); + color: var(--gn-color-black); + font-weight: var(--gn-font-weight-bold); +} + +.gnb-brand-copy { + display: flex; + flex-direction: column; + gap: 2px; +} + +.gnb-brand-copy small { + color: var(--gn-color-text-medium); +} + +.gnb-nav, +.gnb-sidebar-footer { + display: flex; + flex-direction: column; + gap: 4px; +} + +.gnb-sidebar-footer { + margin-top: auto; + padding-top: 12px; + border-top: 1px solid var(--gn-border-color-base); +} + +.gnb-nav-item { + display: flex; + align-items: center; + gap: 10px; + width: 100%; + padding: 10px 12px; + border: 1px solid transparent; + background: transparent; + color: inherit; + font: inherit; + text-align: left; + cursor: pointer; +} + +.gnb-nav-item:hover { + border-color: var(--gn-border-color-base); +} + +.gnb-nav-item.is-active { + border-color: var(--gn-color-accent); + background: var(--gn-surface-panel-strong); +} + +.gnb-main { + min-width: 0; + padding: 24px 32px 48px; +} + +.gnb-page { + display: flex; + flex-direction: column; + gap: 20px; + margin-top: 20px; +} + +.gnb-split { + display: grid; + grid-template-columns: minmax(220px, 320px) minmax(0, 1fr); + gap: 16px; + align-items: start; +} + +.gnb-detail, +.gnb-doc, +.gnb-change-detail { + display: flex; + flex-direction: column; + gap: 16px; + min-width: 0; } .gnb-list { - display: grid; + display: flex; + flex-direction: column; gap: 8px; + min-width: 0; +} + +.gnb-panel { + padding: 12px; + border: 1px solid var(--gn-border-color-base); + background: var(--gn-surface-panel); +} + +.gnb-list-body { + display: flex; + flex-direction: column; + gap: 4px; + max-height: 70vh; + overflow: auto; } .gnb-row { - display: grid; - grid-template-columns: minmax(160px, 280px) minmax(0, 1fr); - gap: 16px; - align-items: center; - padding: 12px 0; - border-bottom: 2px solid rgba(192, 202, 245, 0.24); -} - -.gnb-row span { - overflow-wrap: anywhere; - color: #a9b1d6; + display: flex; + flex-direction: column; + gap: 4px; + padding: 10px 12px; + border: 1px solid var(--gn-border-color-base); + background: var(--gn-surface-panel); } .gnb-row-button { - width: 100%; - border: 0; - border-bottom: 2px solid rgba(192, 202, 245, 0.24); - background: transparent; - color: #c0caf5; + color: inherit; font: inherit; text-align: left; cursor: pointer; @@ -101,182 +174,224 @@ .gnb-row-button:hover, .gnb-row-button.is-active { - background: rgba(122, 162, 247, 0.16); + border-color: var(--gn-color-accent); } -.gnb-list > .gnb-row-button { - display: grid; - grid-template-columns: 1fr; - gap: 8px; - min-width: 0; - padding: 12px 15px; +.gnb-row-button.is-active { + background: var(--gn-surface-panel-strong); } -.gnb-list > .gnb-row-button strong, -.gnb-list > .gnb-row-button span { - min-width: 0; - overflow-wrap: anywhere; +.gnb-row span, +.gnb-row small, +.gnb-muted { + color: var(--gn-color-text-medium); } -.gnb-inventory, -.gnb-docs, -.gnb-changes, -.gnb-git { - display: grid; - grid-template-columns: minmax(280px, 380px) minmax(0, 1fr); - gap: 24px; - align-items: start; +.gnb-row span { + font-size: var(--gn-font-size-sm); + word-break: break-word; } -.gnb-detail { - min-width: 0; -} - -.gnb-detail-grid { - display: grid; - grid-template-columns: minmax(240px, 340px) minmax(0, 1fr); - gap: 16px; - align-items: start; -} - -.gnb-json { - min-height: 320px; - max-height: 70vh; - overflow: auto; - margin: 0; - padding: 16px; - border: 2px solid rgba(192, 202, 245, 0.24); - border-left-width: 6px; - background: #1f2335; - color: #c0caf5; - font-size: 13px; - line-height: 1.5; -} - -.gnb-json-small { - min-height: 120px; - max-height: 240px; -} - -.gnb-doc-detail { - display: grid; - gap: 20px; -} - -.gnb-doc-detail h3 { - margin: 0 0 8px; - font-size: 14px; -} - -.gnb-markdown { - min-height: 360px; - max-height: 70vh; - overflow: auto; - margin: 0; - padding: 16px; - border: 2px solid rgba(192, 202, 245, 0.24); - border-left-width: 6px; - background: #1f2335; - color: #c0caf5; - font-size: 14px; - line-height: 1.6; - white-space: pre-wrap; - overflow-wrap: normal; -} - -.gnb-checkbox-row { - grid-template-columns: 24px 48px minmax(0, 1fr); -} - -.gnb-checkbox-row input { - width: 16px; - height: 16px; -} - -.gnb-checkbox-row.is-disabled { - opacity: 0.52; -} - -.gnb-commit { - display: grid; - gap: 16px; - min-width: 0; -} - -.gnb-changes-workspace { - display: grid; - gap: 24px; -} - -.gnb-proposal { - display: grid; - gap: 16px; - padding-top: 8px; +.gnb-lead { + max-width: 60ch; + color: var(--gn-color-text-medium); } .gnb-actions { display: flex; flex-wrap: wrap; - justify-content: flex-start; gap: 8px; + align-items: center; + margin-top: 8px; } -.gnb-form-grid { - display: grid; - grid-template-columns: repeat(2, minmax(0, 1fr)); - gap: 16px; +.gnb-badges { + display: flex; + flex-wrap: wrap; + gap: 8px; + align-items: center; +} + +.gnb-form { + display: flex; + flex-direction: column; + gap: 12px; + margin-top: 8px; } .gnb-field { - display: grid; + display: flex; + flex-direction: column; gap: 6px; } -.gnb-field span { - font-size: 13px; - font-weight: 600; +.gnb-field > span { + color: var(--gn-color-text-medium); + font-size: var(--gn-font-size-sm); } -.gnb-field textarea { +.gnb-textarea { width: 100%; - box-sizing: border-box; + min-height: 220px; resize: vertical; +} + +.gnb-pre { + margin: 0; + max-height: 460px; + padding: 12px; + overflow: auto; + border: 1px solid var(--gn-border-color-base); + background: var(--gn-surface-panel-muted); + color: var(--gn-color-text-light); + font-family: var(--gn-font-family-base); + font-size: var(--gn-font-size-sm); + white-space: pre-wrap; + word-break: break-word; +} + +.gnb-history { + display: flex; + flex-direction: column; + gap: 6px; +} + +.gnb-history-row { + display: flex; + gap: 8px; + align-items: center; +} + +.gnb-history-row .gnb-row-button { + flex: 1; +} + +.gnb-diff { + display: flex; + flex-direction: column; + gap: 8px; + margin-top: 12px; +} + +.gnb-issues { + display: flex; + flex-direction: column; + gap: 10px; + margin-top: 8px; +} + +.gnb-issue { padding: 10px 12px; - border: 2px solid #c0caf5; - border-bottom-width: 6px; - background: rgba(192, 202, 245, 0.045); - color: #c0caf5; - font: inherit; + border: 1px solid var(--gn-border-color-base); + background: var(--gn-surface-panel-muted); } -.gnb-error { - margin-top: 16px; - color: #f7768e; +.gnb-issue p { + margin: 6px 0 0; + color: var(--gn-color-text-medium); } -@media (max-width: 760px) { +.gnb-issue code, +.gnb-token { + color: var(--gn-color-accent); + font-family: var(--gn-font-family-base); + word-break: break-all; +} + +.gnb-token { + display: block; + margin: 8px 0; + padding: 8px; + border: 1px solid var(--gn-border-color-base); + background: var(--gn-color-black); +} + +.gnb-metrics { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(200px, 1fr)); + gap: 16px; +} + +.gnb-inventory-detail { + grid-template-columns: minmax(200px, 280px) minmax(0, 1fr); +} + +.gnb-keys { + display: flex; + flex-direction: column; + gap: 8px; + margin-top: 8px; +} + +.gnb-key-row { + display: flex; + gap: 12px; + align-items: flex-start; + justify-content: space-between; + padding: 10px 12px; + border: 1px solid var(--gn-border-color-base); + background: var(--gn-surface-panel-muted); +} + +.gnb-key-copy { + display: flex; + flex-direction: column; + gap: 4px; + min-width: 0; +} + +.gnb-language-actions { + margin-top: 12px; +} + +.gnb-mobile-menu { + display: none; +} + +.gnb-backdrop { + display: none; +} + +@media (max-width: 1000px) { .gnb-shell { - width: min(100% - 24px, 1380px); - padding: 16px 0 40px; - } - - .gnb-shell .page-header { grid-template-columns: 1fr; } - .gnb-shell .page-header-actions, - .gnb-shell .toolbar > .toolbar-group:last-child { - justify-content: flex-start; + .gnb-sidebar { + position: fixed; + inset: 0 auto 0 0; + z-index: 40; + width: min(84vw, 300px); + transform: translateX(-100%); + transition: transform var(--gn-motion-base) var(--gn-motion-ease); } - .gnb-status, - .gnb-row, - .gnb-docs, - .gnb-changes, - .gnb-git, - .gnb-inventory, - .gnb-detail-grid, - .gnb-form-grid { + .gnb-sidebar.is-open { + transform: translateX(0); + } + + .gnb-backdrop { + position: fixed; + inset: 0; + z-index: 30; + display: block; + background: rgb(0 0 0 / 55%); + } + + .gnb-main { + padding: 16px; + } + + .gnb-mobile-menu { + display: inline-flex; + } + + .gnb-split, + .gnb-inventory-detail { grid-template-columns: 1fr; } + + .gnb-list-body { + max-height: none; + } } diff --git a/ui/vite.config.js b/ui/vite.config.js index 40603c0..e613d18 100644 --- a/ui/vite.config.js +++ b/ui/vite.config.js @@ -57,6 +57,14 @@ target: "http://127.0.0.1:3005", changeOrigin: true, rewrite: (path) => path.replace(/^\/api/, "") + }, + "/auth": { + target: "http://127.0.0.1:3005", + changeOrigin: true + }, + "/webhooks": { + target: "http://127.0.0.1:3005", + changeOrigin: true } } }