docs: rewrite README and docs for the full-access design, generate tool inventory
This commit is contained in:
Latte committed
1 parent
68bd8700dc
commit
7c7cfc05ff
13 files changed
+1693
-1026
No files matched your search
+33
-62
@@ -1,74 +1,45 @@
|
||||
# Roadmap
|
||||
|
||||
## High-Level Evolution Plan
|
||||
Where the project stands and what is deliberately not planned. Design decisions are in
|
||||
[docs/adr](adr/0001-full-access-by-default.md).
|
||||
|
||||
1. Hardened read-only gateway baseline.
|
||||
2. Policy-driven authorization and observability.
|
||||
3. Controlled write-mode rollout.
|
||||
4. Automation and event-driven workflows.
|
||||
5. Continuous hardening and enterprise controls.
|
||||
6. Dual transport (HTTP/OAuth + local stdio) on a shared core, with safe
|
||||
full-API coverage and resource-type-aware authorization (0.2.0).
|
||||
## 1.0.0
|
||||
|
||||
## Threat Model Updates
|
||||
1.0.0 is a breaking rebuild of 0.x:
|
||||
|
||||
- Primary threats: credential theft, over-permissioned automation, prompt injection via repo data, policy bypass, audit tampering.
|
||||
- Secondary threats: denial-of-service, misconfiguration drift, unsafe deployment defaults.
|
||||
- one tool per operation of the pinned Gitea 28.1.0 swagger (537) plus `gitea_api_request`;
|
||||
- stdio and streamable HTTP on the official `mcp` SDK;
|
||||
- admin-token mode and per-user OAuth with dynamic client registration;
|
||||
- a `setup` command, a generated tool inventory and a docs drift check in CI;
|
||||
- live-Gitea integration tests and MCP smoke tests in CI.
|
||||
|
||||
## Security Model
|
||||
The gates that 0.x used to restrict a shared service token (write opt-in, a policy file, per-resource
|
||||
checks) are gone, together with the old web adapter and its extras (ADR 0001, 0006). All tool names
|
||||
changed to `gitea_<domain>_<action>`.
|
||||
|
||||
- API key authentication + auth failure throttling.
|
||||
- Per-IP and per-token request rate limits.
|
||||
- Secret detection and outbound sanitization.
|
||||
- Tamper-evident audit logs with integrity verification.
|
||||
- No production stack-trace disclosure.
|
||||
## Known limits
|
||||
|
||||
## Policy Model
|
||||
- Tool list size. 538 tools is a lot for clients without tool search. Use `TOOLSETS`,
|
||||
`READ_ONLY` and `DISABLED_TOOLS` for a slim profile. How claude.ai and Mistral Le Chat cope
|
||||
with the full list is to be confirmed against the real clients.
|
||||
- Gitea has no queue management, no instance configuration writes and no instance-wide OAuth
|
||||
application endpoints, so there are no tools for them.
|
||||
- The catalog follows one pinned swagger. A newer Gitea needs a re-pin and regeneration, and
|
||||
`gitea_api_request` covers the gap in the meantime.
|
||||
- Some operations need state that is hard to reproduce in CI (a registered runner executing a
|
||||
job, a reachable remote for mirrors and migrations, uploaded packages). The integration sweep
|
||||
calls every tool, and asserts Gitea's documented response where a full happy path is not
|
||||
reproducible.
|
||||
- In OAuth mode the server holds per-user Gitea tokens, encrypted at rest. That store is the most
|
||||
sensitive asset after the admin token.
|
||||
|
||||
- YAML policy with global and per-repository allow/deny rules.
|
||||
- Optional path restrictions for file-oriented tools.
|
||||
- Default write deny.
|
||||
- Write-mode repository whitelist enforcement.
|
||||
## Not planned
|
||||
|
||||
## Capability Matrix Concept
|
||||
- A policy engine or per-repository allow lists inside the server. Restrict with the token's
|
||||
scopes, per-user OAuth and the tool filters.
|
||||
- Metrics endpoints, webhook ingest and scheduled jobs. This is an API bridge.
|
||||
- Scraping the Gitea web UI for features the API lacks.
|
||||
|
||||
- `Read` capabilities: enabled by default but policy-filtered.
|
||||
- `Write` capabilities: disabled by default, policy + whitelist gated.
|
||||
- `Automation` capabilities: disabled by default, policy-controlled.
|
||||
## Possible later work
|
||||
|
||||
## Audit Log Design
|
||||
|
||||
- JSON lines.
|
||||
- `prev_hash` + `entry_hash` chain.
|
||||
- Correlation/request IDs for traceability.
|
||||
- Validation script for chain integrity.
|
||||
|
||||
## Write-Mode Architecture
|
||||
|
||||
- Separate write tool set with strict schemas.
|
||||
- Global toggle (`WRITE_MODE`) + per-repo whitelist.
|
||||
- Policy engine still authoritative.
|
||||
- No merge, branch deletion, or force push endpoints.
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
- Non-root container runtime.
|
||||
- Read-only filesystem where practical.
|
||||
- Explicit opt-in for insecure bind.
|
||||
- Separate dev and prod compose profiles.
|
||||
|
||||
## Observability Architecture
|
||||
|
||||
- Structured JSON logs with request correlation.
|
||||
- Prometheus-compatible `/metrics` endpoint.
|
||||
- Tool execution counters and duration aggregates.
|
||||
|
||||
## Risk Analysis
|
||||
|
||||
- Highest risk: write-mode misuse and policy misconfiguration.
|
||||
- Mitigations: deny-by-default, whitelist, audit chain, tests, docs, reviews.
|
||||
|
||||
## Extensibility Notes
|
||||
|
||||
- Add new tools only through schema + policy + docs + tests path.
|
||||
- Keep transport-agnostic execution core for webhook/scheduler integrations.
|
||||
- Re-pinning to newer Gitea releases as they ship.
|
||||
Reference in new issue
Block a user