diff --git a/10-systems/applications/gnexus-book.md b/10-systems/applications/gnexus-book.md index 369a810..6190a1c 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-09-05 +last_reviewed: 2026-09-24 review_interval: 30d confidence: high source_of_truth: ssh-host-verified @@ -38,6 +38,14 @@ 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. +Poisoned-pending protection (since 2026-09-24, commit c77bcb1): + +- 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. + For agent-facing MCP usage rules, see [../../90-maintenance/agent-mcp-usage.md](../../90-maintenance/agent-mcp-usage.md). No raw credentials are documented here. diff --git a/90-maintenance/pending-changes/20260924054348-7f5637f4.json b/90-maintenance/pending-changes/20260924054348-7f5637f4.json new file mode 100644 index 0000000..92c58d7 --- /dev/null +++ b/90-maintenance/pending-changes/20260924054348-7f5637f4.json @@ -0,0 +1,19 @@ +{ + "id": "20260924054348-7f5637f4", + "kind": "doc", + "target": "10-systems/applications/gnexus-book.md", + "summary": "Document poisoned-pending protection: validate-before-write, full rollback on failed apply, delete_pending_change tool, corrupt-JSON tolerance", + "reason": "Задача gntodo #3: задокументирована новая защита от отравленных pending-changes (validate-before-write, полный rollback, delete_pending_change, устойчивость к corrupt JSON). Коммит c77bcb1 на gnbook.", + "payload": { + "content": "---\nowner: gmikcon\nstatus: active\nlast_reviewed: 2026-09-24\nreview_interval: 30d\nconfidence: high\nsource_of_truth: ssh-host-verified\n---\n\n# Gnexus Book\n\nGnexus Book is the canonical infrastructure knowledge base and maintenance API for the personal digital and server infrastructure.\n\n## Deployment\n\n- Runs as KVM VM `gnbook` (192.168.1.170) on hypervisor `hp-proliant-dl380-g6` (192.168.1.130).\n- SSH: `ubuntu` on 192.168.1.170 (credentials in gnexus-creds, secret `gnauth-gnbook-ssh`).\n- Repository path: `/home/ubuntu/gnexus-book` (branch `master`).\n- Source of truth: Markdown, YAML inventory, JSON Schema, and Git history.\n\n## Runtime Components\n\n- Backend: FastAPI under `server/`.\n- Agent interface: MCP server under `server/app/mcp_server.py`.\n- UI: Vue/Vite under `ui/`.\n- UI dependency: `gnexus-ui-kit`.\n\n## Endpoints\n\n- REST API: `http://192.168.1.170:8000/` (uvicorn, openapi at `/openapi.json`).\n- MCP (SSE): `http://192.168.1.170:8001/sse`.\n- UI (LAN): `http://192.168.1.170:80/` (nginx serves the built SPA).\n- Services run as user-level systemd units under `user@1000.service`: `gnexus-book-backend.service` (uvicorn :8000) and `gnexus-book-mcp.service` (MCP server).\n\n## Maintenance Model\n\nAgents should prefer structured inventory changes, validation, pending changes, and local commits through the maintenance API.\n\nPending-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.\n\nPoisoned-pending protection (since 2026-09-24, commit c77bcb1):\n\n- 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.\n- 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).\n- `delete_pending_change` (MCP) / `DELETE /changes/{id}` (REST): deletes pending or corrupt records; applied records are refused (409).\n- `list_pending_changes` tolerates corrupt JSON files and reports them with status `corrupt`; corrupt records can be deleted but not applied.\n- `update_doc` cleans up its own pending JSON automatically if apply or commit fails.\n\nFor agent-facing MCP usage rules, see [../../90-maintenance/agent-mcp-usage.md](../../90-maintenance/agent-mcp-usage.md).\n\nNo raw credentials are documented here." + }, + "status": "applied", + "created_at": "2026-09-24T05:43:48Z", + "updated_at": "2026-09-24T05:43:49Z", + "applied_at": "2026-09-24T05:43:49Z", + "validation": { + "status": "ok", + "issue_count": 0, + "issues": [] + } +}