NuklearRabbit
c981aad2a3
Add the new endpoints to contracts/openapi.yaml and docs/05-api-contract.md (return-preview, the four rule-specific data-quality resolution endpoints, search, integration status, scheduled-scan), document the role matrix and the audit before/after exposure in docs/12-security-and-audit.md, document each rule type's actual resolution flow in docs/07-data-quality.md (including the deliberate evidence-fingerprint simplification and the reopened_from/previous_decision recurrence link), document the preview/ commit relationship in docs/08-return-workflow.md, and update README.md's scope/integration-status/quality-gate sections to match what's actually implemented and verified now. Also drops docs/05-api-contract.md's mention of GET /api/v1/system/status, which was never implemented.
79 lines
2.9 KiB
Markdown
79 lines
2.9 KiB
Markdown
# Security and audit
|
|
|
|
## Demo authentication
|
|
|
|
Role buttons may create a session for a seeded demo identity. All API routes still enforce authorization. Demo reset and customer merge require Operations Manager.
|
|
|
|
The browser never treats its own cached copy of the logged-in user as authoritative:
|
|
`AuthContext` re-verifies against `GET /api/v1/demo/session` on every app load (that
|
|
response is `Cache-Control: no-store`, so a stale cached "authenticated" response can't
|
|
survive a logout), and a central 401 listener on the API client clears local auth state
|
|
from any endpoint, not just the session check. `POST /api/v1/demo/logout` and
|
|
`POST /api/v1/demo/reset` both invalidate the session cookie server-side.
|
|
|
|
## Role matrix
|
|
|
|
| Capability | Rental Employee | Operations Manager |
|
|
|---|---|---|
|
|
| Dashboard, fleet, vehicle detail, bookings, booking detail | yes | yes |
|
|
| Register a vehicle return | yes | yes |
|
|
| Knowledge assistant | yes | yes |
|
|
| Data-quality workbench (view, scan, all resolutions) | no | yes |
|
|
| Integrations / automation status and retry | no | yes |
|
|
| Audit trail | no | yes |
|
|
| Demo reset | no | yes |
|
|
|
|
Enforced server-side (every listed manager-only action returns `403` for Rental
|
|
Employee, verified by direct API tests, not just a hidden button) and mirrored in the
|
|
frontend nav (manager-only items are not rendered, not merely disabled) and route guards
|
|
(direct URL access shows a restricted message rather than partial data).
|
|
|
|
## Service authentication
|
|
|
|
Use separate scoped credentials for:
|
|
|
|
- n8n callbacks;
|
|
- MCP Hub provider calls;
|
|
- RAGcore calls.
|
|
|
|
Never reuse browser session secrets.
|
|
|
|
## Sensitive data
|
|
|
|
All data are synthetic, but design as though data were sensitive:
|
|
|
|
- do not log full tokens;
|
|
- avoid logging complete customer payloads;
|
|
- validate and size-limit free-text inputs;
|
|
- escape rendered content;
|
|
- use CSRF protection for cookie sessions or use a secure token model;
|
|
- restrictive CORS;
|
|
- secrets from environment or mounted secret files.
|
|
|
|
## Audit events
|
|
|
|
Required actions:
|
|
|
|
- demo login;
|
|
- return registration;
|
|
- vehicle status change;
|
|
- data-quality issue creation and resolution;
|
|
- customer merge;
|
|
- workflow retry;
|
|
- demo reset;
|
|
- MCP provider request;
|
|
- knowledge question status and source IDs.
|
|
|
|
Audit is append-only through the application. Provide filters by actor, action, entity and correlation ID.
|
|
|
|
`GET /api/v1/audit` (Operations Manager only) returns `before`/`after` for every event
|
|
(the columns already existed but were not serialized until this pass) plus a resolved
|
|
`entity_ref`/`entity_link` for vehicle, booking and data-quality-issue entities (no
|
|
customer link exists — no customer detail route). The UI shows a human-readable
|
|
before/after summary per row by default, with the raw before/after/metadata JSON behind
|
|
a `<details>` disclosure rather than shown unconditionally.
|
|
|
|
## Confirmation
|
|
|
|
No write-capable MCP actions exist in this PoC. Destructive UI actions such as demo reset and customer merge require explicit confirmation.
|