diff --git a/docs/plans/destructive-tools-opt-in.md b/docs/plans/destructive-tools-opt-in.md new file mode 100644 index 000000000..86de27dd4 --- /dev/null +++ b/docs/plans/destructive-tools-opt-in.md @@ -0,0 +1,373 @@ +# Destructive-Tools Opt-In — per-Space + +_Drafted 2026-04-23. Status: **spec**, nicht implementiert. Bau-Trigger: das erste Tool mit `policyHint: 'destructive'` landet in `@mana/tool-registry`._ + +Erweitert das M1-Policy-Gate (`evaluatePolicy()` in `@mana/tool-registry`) um eine persistente per-Space-Whitelist, die entscheidet, welche destruktiven Tools die KI in welchem Space wirklich ausführen darf. Bis das hier gebaut ist, lehnt der Gate jeden destruktiven Call ab (`reason: 'destructive-not-allowed'`), was für `POLICY_MODE=log-only` okay ist, aber `enforce` de facto blockiert. + +**Hintergrund:** +- [`docs/plans/agent-loop-improvements-m1.md`](./agent-loop-improvements-m1.md) — M1+M2-Implementierung, inkl. der aktuellen `settingsFor()`-Hardcoding-Stelle (`services/mana-mcp/src/mcp-adapter.ts`) +- [`docs/reports/mana-agent-improvements-from-claude-code.md`](../reports/mana-agent-improvements-from-claude-code.md) — Claude-Code-Referenz für das Muster (pro-User im Original, hier pro-Space) +- [`docs/plans/space-scoped-data-model.md`](./space-scoped-data-model.md) — die Space-Semantik, an die wir andocken + +## Ziel in einem Satz + +Jeder Space trägt eine kleine, Server-authoritative Policy-Konfiguration, die pro destruktivem Tool sagt „darf die KI in diesem Space", geschützt durch Role-Gating, sichtbar im Audit-Log, bearbeitbar in einer Settings-Seite pro Space. + +## Nicht-Ziele + +- **Per-User** oder **per-Member-innerhalb-Space**. Alle Members eines Spaces teilen die gleiche Policy. Wenn Alice etwas erlaubt, gilt das auch für Bob — ist eine Eigenschaft des Spaces, nicht der Person. +- **Zeitbasierte Permissions** (nur für 24h erlaubt). Später erwägen; heute nicht. +- **Per-Tool-Rate-Limits per Space**. Die Registry hat einen globalen 30/min/User-Default; per-Space-Override ist YAGNI. +- **Tools ausserhalb MCP/mana-ai**. Native App-Buttons (User klickt „Habit löschen") brauchen keine Tool-Policy — das ist User-Intent, nicht AI-Intent. +- **Automatische Migration von existierenden Spaces**. Alle Spaces starten mit leerer Whitelist; User enablet explizit. +- **Registry-Einträge ohne `policyHint: 'destructive'` einschließen**. Writes/Reads bleiben über die bestehende agent.policy gesteuert (per-Mission). + +## Entscheidungen (gesetzt) + +| Frage | Entscheidung | Warum | +|---|---|---| +| Scope | **Per-Space** | User-Entscheidung. Passt zum Space-scoped-data-model; Destructive-Rechte auf Arbeits-Spaces können strenger sein als auf Private-Spaces. | +| Authority | **Server-authoritative**, nicht Local-First | Security-relevant, Multi-Device-Konsistenz muss sofort greifen. Nicht in Dexie. | +| Storage | Eigene Tabelle `mana_spaces.space_policy_preferences`, **nicht** JSON-Column auf `spaces` | Typisiert, indexierbar, Migrations-freundlich, Audit-Trail natürlicher. | +| Sync | **Nur** Server-Read; keine Dexie-Replik | Write nur via JWT-gated API; Frontend ruft direkt. Cache im mana-mcp-Adapter. | +| Role-Gating | Nur Space-Owner + `admin`-Role-Members dürfen ändern; alle Members dürfen lesen | Minimales Privilegien-Prinzip. Matcht wie andere Space-Settings gehandhabt werden. | +| Default | `[]` — nichts erlaubt, bei neuen und bestehenden Spaces | Sicher by default. User muss explizit opt-in. | +| Toggle-Granularität | Pro Tool, nicht global | Setzt Claude-Code-Pattern um (1:1-Mapping Tool ↔ Permission). Master-Toggle kann später dazu. | +| Confirm-Flow | Explizite Checkbox „Ich verstehe dass diese Tool unwiderruflich löscht" vor Speichern | Anti-Click-Through. | +| Cache-TTL | 30 s in mana-mcp | Gleiches Pattern wie `MasterKeyClient`. Kurz genug für schnelle Reaktion auf Revoke, lang genug für Tool-Burst-Calls in einer Session. | + +## Architektur + +``` + apps/mana/apps/web — /s/:spaceId/settings/ai-policy + │ HTTP (PUT) + ▼ + ┌─────────────────────────────────────┐ + │ apps/api (Hono/Bun, :3060) │ + │ /api/v1/spaces/:id/policy │ + │ - GET (any member) │ + │ - PUT (owner + admin only) │ + │ → role-check │ + │ → write to mana_spaces. │ + │ space_policy_preferences │ + │ → write audit row │ + └────────────────┬─────────────────────┘ + │ + ▼ + Postgres (mana_spaces schema) + │ + │ read (GET /internal/spaces/:id/policy) + ▼ + ┌─────────────────────────────────────┐ + │ services/mana-mcp (:3069) │ + │ SpacePolicyClient (like │ + │ MasterKeyClient — TTL cache) │ + │ settingsFor(user, spaceId) │ + └──────────────────┬──────────────────┘ + ▼ + evaluatePolicy() + (destructive check reads + userSettings.allowDestructive) +``` + +## Storage + +### `mana_spaces.space_policy_preferences` + +```sql +CREATE TABLE mana_spaces.space_policy_preferences ( + space_id uuid PRIMARY KEY REFERENCES mana_spaces.spaces(id) ON DELETE CASCADE, + allow_destructive text[] NOT NULL DEFAULT '{}', + updated_at timestamptz NOT NULL DEFAULT now(), + updated_by uuid NOT NULL REFERENCES auth.users(id), + schema_version integer NOT NULL DEFAULT 1 +); + +CREATE INDEX space_policy_preferences_updated_at_idx + ON mana_spaces.space_policy_preferences(updated_at DESC); +``` + +**RLS:** +```sql +ALTER TABLE mana_spaces.space_policy_preferences ENABLE ROW LEVEL SECURITY; + +-- Members can SELECT +CREATE POLICY spp_member_read ON mana_spaces.space_policy_preferences + FOR SELECT USING ( + space_id IN ( + SELECT space_id FROM mana_spaces.space_members + WHERE user_id = app.current_user_id() + ) + ); + +-- Only owner + admin role can UPDATE / INSERT / DELETE +CREATE POLICY spp_admin_write ON mana_spaces.space_policy_preferences + FOR ALL USING ( + space_id IN ( + SELECT space_id FROM mana_spaces.space_members + WHERE user_id = app.current_user_id() + AND role IN ('owner', 'admin') + ) + ); +``` + +### `mana_spaces.space_policy_audit` + +Append-only. Jede Änderung ein Row. + +```sql +CREATE TABLE mana_spaces.space_policy_audit ( + id uuid PRIMARY KEY DEFAULT gen_random_uuid(), + space_id uuid NOT NULL REFERENCES mana_spaces.spaces(id) ON DELETE CASCADE, + actor_id uuid NOT NULL REFERENCES auth.users(id), + action text NOT NULL CHECK (action IN ('added', 'removed')), + tool_name text NOT NULL, + at timestamptz NOT NULL DEFAULT now() +); + +CREATE INDEX space_policy_audit_space_idx + ON mana_spaces.space_policy_audit(space_id, at DESC); +``` + +**RLS:** +```sql +ALTER TABLE mana_spaces.space_policy_audit ENABLE ROW LEVEL SECURITY; + +-- Members can read audit for their spaces +CREATE POLICY spa_member_read ON mana_spaces.space_policy_audit + FOR SELECT USING ( + space_id IN ( + SELECT space_id FROM mana_spaces.space_members + WHERE user_id = app.current_user_id() + ) + ); + +-- Writes only from the service role (the PUT endpoint issues these +-- inside the same withUser transaction as the preferences write). +-- No direct client writes — ever. +``` + +**Retention**: keine — DSGVO-relevant wenn Audit-Dauer; 3 Jahre scheint eine vernünftige Balance für EU-Hosting. Entscheidung offen, siehe §Offene Fragen. + +## API (apps/api) + +Routes in `apps/api/src/modules/spaces/policy-routes.ts`: + +### `GET /api/v1/spaces/:spaceId/policy` + +JWT-gated. Any member of the space. + +```ts +Response 200: +{ + spaceId: string; + allowDestructive: string[]; // Tool-Namen, z.B. ['habits.delete', 'notes.delete'] + updatedAt: string; // ISO 8601 + updatedBy: string; // userId +} +``` + +Wenn für den Space noch keine Row existiert: implizit `{ allowDestructive: [] }` mit `updatedAt: null`. Das Frontend rendert das identisch zu „leer". + +### `PUT /api/v1/spaces/:spaceId/policy` + +JWT-gated. **Role-Check**: nur `owner` + `admin`. 403 sonst. + +```ts +Request: +{ + allowDestructive: string[]; // vollständige neue Liste (nicht delta!) + acknowledged: true; // UI-Anti-Clickthrough — muss true sein wenn neue Tools hinzugefügt werden +} + +Response 200: +{ spaceId, allowDestructive, updatedAt, updatedBy } +``` + +**Validation** (Zod schema): +- `allowDestructive` max 50 Einträge +- Jeder Eintrag matcht `^[a-z_]+\.[a-z_]+$` (module.verb) +- **Wichtig**: jeder Name wird gegen den Tool-Registry-Bestand geprüft. Unbekannte Tools → 400. Verhindert "vorab-genehmigte" Tool-Namen die später plötzlich live gehen und dann Destructive sind. +- Jeder Eintrag muss `policyHint: 'destructive'` haben (nicht-destruktive landen hier nicht — sichergestellt durch registry-lookup). +- `acknowledged: true` verpflichtend wenn die resultierende Liste strictly größer ist als die bestehende (neue Tools dazu). + +**Side-Effects** (in einer Transaktion): +1. Upsert in `space_policy_preferences` +2. Diff gegen alte Liste → ein `space_policy_audit`-Row pro `added` und `removed` + +### `GET /api/v1/spaces/:spaceId/policy/audit?limit=50` + +JWT-gated. Member-read. Paginiert (cursor via `at < ?`). + +```ts +Response 200: +{ + entries: Array<{ + id, spaceId, actorId, actorDisplayName, action: 'added'|'removed', toolName, at + }>; + nextCursor?: string; +} +``` + +### `GET /internal/spaces/:spaceId/policy` + +Service-to-service. `X-Service-Key`-gated. Used by mana-mcp's `SpacePolicyClient`. Identisches Response-Shape wie der User-facing GET. **Kein** Role-Check — interne Services dürfen Policy für jeden Space lesen. + +## Consumer-Wiring (mana-mcp) + +### Neuer Client: `services/mana-mcp/src/space-policy-client.ts` + +Gleiches Muster wie `MasterKeyClient`: TTL-Cache, per-space-keyed (nicht per-user — die Policy ist space-bound). + +```ts +export interface SpacePolicy { + allowDestructive: readonly string[]; +} + +export class SpacePolicyClient { + private cache = new Map(); + private static TTL_MS = 30_000; + + constructor(private opts: { apiUrl: string; serviceKey: string }) {} + + async getPolicy(spaceId: string): Promise { + const hit = this.cache.get(spaceId); + if (hit && Date.now() - hit.fetchedAt < SpacePolicyClient.TTL_MS) { + return hit.policy; + } + const res = await fetch( + `${this.opts.apiUrl}/internal/spaces/${encodeURIComponent(spaceId)}/policy`, + { headers: { 'X-Service-Key': this.opts.serviceKey } } + ); + if (!res.ok) { + // Fail-CLOSED — deny destructive by default if we can't reach apps-api. + // This is the correct security default; the UI will show stale state + // for 30s after enforcement comes back online, which is acceptable. + return { allowDestructive: [] }; + } + const body = await res.json(); + const policy: SpacePolicy = { allowDestructive: body.allowDestructive ?? [] }; + this.cache.set(spaceId, { policy, fetchedAt: Date.now() }); + return policy; + } +} +``` + +### Integration in `mcp-adapter.ts` + +`settingsFor()` wird async und nimmt die space-id: + +```ts +const spacePolicyClient = new SpacePolicyClient({ + apiUrl: process.env.MANA_API_URL, + serviceKey: process.env.MANA_SERVICE_KEY, +}); + +async function settingsFor(user: VerifiedUser): Promise { + const policy = await spacePolicyClient.getPolicy(user.spaceId); + return { allowDestructive: policy.allowDestructive }; +} +``` + +`invoke()` wird leicht umgestellt (async settings-fetch vor dem Gate), ansonsten unverändert. + +### Integration in `mana-ai` + +`services/mana-ai/src/cron/tick.ts`'s `onToolCall` ist heute nur ein Recorder — Tool-Execution passiert client-side via Sync-Staging. Für den Server-Runner ist `allowDestructive` daher nicht sicherheitsrelevant (Plans werden eh vom Client-Side-Executor gegen seine eigene agent.policy geprüft). + +**ABER** wenn die Tool-Registry mana-ai komplett absorbiert (M4 aus dem Personas-Plan), wird mana-ai selbst Tools ausführen. Dann gleicher Pattern wie mana-mcp: `SpacePolicyClient` injizieren, `settingsFor(mission.spaceId)` aufrufen, in Mission-State cachen über die Tick-Dauer. + +## UI (webapp) + +Neue Route: `/s/:spaceSlug/settings/ai-policy` — embedded in die Space-Settings-Area. + +### Komponentenbaum + +``` + + +
+

KI-Aktionen in diesem Space

+

+ Standardmäßig darf die KI keine Daten unwiderruflich löschen. + Aktivieren bedeutet: wenn du der KI "lösche X" sagst, passiert das + ohne Papierkorb. Du kannst das jederzeit widerrufen. +

+ +
+ + +``` + +### Destructive-Tool-Karten + +Jedes Tool kriegt eine Karte mit: +- Tool-Name (z. B. `habits.delete`) +- Description aus der Registry +- **Toggle** (ein/aus) +- **Affected-data-hint** — "Betrifft: Gewohnheiten in diesem Space" (abgeleitet aus `spec.encryptedFields?.table` oder dem Modul-Namen) +- Für neu-aktivierte Tools: das Save-Button-Modal mit der Pflicht-Checkbox „Ich verstehe, dass das nicht rückgängig gemacht werden kann". + +### Audit-Log-Abschnitt + +Tabelle mit `at | actor | action | tool`. Pagination-Button "Ältere anzeigen". Niemand kann Einträge löschen (append-only). + +### Zugriffs-Gating + +`AuthGate` + `SpaceMemberGate` + zusätzlich: nur wenn Member-Role ∈ {`owner`, `admin`} ist die Toggle-UI interaktiv. Sonst: Read-only mit Hinweis "Nur Space-Admins können Einstellungen ändern". + +## Audit + Safety + +- **Diff-based Audit**: beim PUT wird altes vs. neues `allowDestructive` verglichen; ein Audit-Row pro `added` und `removed`. Keine Löschungen oder Updates an Audit-Rows — immutable. +- **Acknowledgement enforced at API**: der `acknowledged: true` Flag wird geprüft bevor Add-Diff durchrutscht. Frontend kann nicht "vergessen" das Modal zu zeigen und trotzdem den Request absetzen. +- **Fail-closed bei Cache-Miss + API-Error**: Wenn mana-mcp apps-api nicht erreichen kann, wird destructive geblockt. Lieber eine 30s-Lücke mit "deny" als eine 30s-Lücke mit "allow". +- **Kein Self-Gating**: ein Space-Owner kann für seinen eigenen Space aktivieren ohne Second-Approval. Begründung: der Owner trägt bereits die Verantwortung für alle Daten im Space. Pairing-Reviews sind für Production-Deploys, nicht für Consumer-Apps. +- **Revoke wirkt schnell**: 30s max bis zum Cache-Ablauf. Für schnelleren Revoke kann später ein In-Memory-Pub/Sub via Redis geschaltet werden (nicht MVP). + +## Metriken + +Erweiterung der bestehenden `mana_mcp_policy_decisions_total`: + +- `reason="destructive-not-allowed"` bleibt das gleiche. Dashboards müssen nicht geändert werden. +- **Neu**: `mana_api_space_policy_changes_total{action="added"|"removed"}` — zählt User-initiierte Änderungen. Pattern zur Anomalieerkennung (z. B. plötzlicher Flip von deny → allow für einen Space in dem das vorher nie aktiv war). + +## Rollout-Reihenfolge + +1. **Migration** — `space_policy_preferences` + `space_policy_audit` Tabellen, RLS-Policies, Indexes. `pnpm db:push`. +2. **apps-api endpoints** — GET/PUT/GET-audit + interner GET. Zod-schemas. Registry-lookup für unknown-tool-Validation. Integration-tests. +3. **mana-mcp SpacePolicyClient** — TTL-cache, fail-closed. Unit-tests. +4. **mana-mcp settingsFor() umstellen** auf async + space-policy. Integration-test: Space mit `allowDestructive: ['habits.delete']` → Gate lässt durch; Space ohne → Gate blockiert. +5. **UI** — `/s/:space/settings/ai-policy` + Audit-Sektion. Acknowledgement-Modal. +6. **Metrik** — Counter in apps-api; Grafana-Panel unter dem bestehenden "Policy Gate"-Block in `agent-loop.json`. +7. **Doku-Update** — `services/mana-mcp/CLAUDE.md` §Policy gate um den Per-Space-Hinweis erweitern; Link auf diesen Plan. + +## Tests + +- **apps-api** — GET (member, non-member=403), PUT (owner ok, member=403, unknown-tool=400, missing-acknowledged-on-add=400), audit-row correctness, concurrent-write LWW behaviour. +- **SpacePolicyClient** — cache hit vs miss, TTL expiry, API-error fail-closed, per-space cache separation. +- **mana-mcp integration** — End-to-End: mock apps-api, MCP call zu destructive tool, mit/ohne opt-in. +- **UI** — role-gate rendering, acknowledgement modal, audit list pagination. +- **RLS** — Postgres-level test: member read, admin write, non-member blocked, direct audit insert blocked. + +## Offene Fragen + +1. **Audit-Retention**: 3 Jahre? DSGVO sagt "so lange wie nötig" — für Security-Audit ist 3 Jahre defensiv, aber da sind wir auch beim Compliance-Overhead. Entscheidung zum Bau-Zeitpunkt. +2. **Pub/Sub für sofortigen Revoke-Effekt**: heute 30s TTL. Falls wir Hot-Revoke-Szenarios haben (Ex-Admin, kompromittierter Account), lohnt Redis-Pub/Sub? Würde ich später schalten, nicht MVP. +3. **Quorum-Mode für Shared-Spaces**: Bei einem 10-Person-Team-Space — soll eine einzelne Admin-Stimme reichen um Destructive zu enablen? Oder N-of-M? Heute: Einzelperson reicht. Falls später Team-Spaces populär werden, `require_unanimous` oder `require_n_of_admins` als Space-Setting. +4. **Welche Member-Role entscheidet**: `owner` + `admin` ist die Annahme. Falls es eine eigene `policy-manager`-Role gibt, ist das spezifischer. Noch unklar was die final Role-Hierarchie in space_members ist. + +## Wann diesen Plan aktivieren + +Trigger: **Pull-Request der das erste Tool mit `policyHint: 'destructive'` in `packages/mana-tool-registry/src/modules/*.ts` registriert** — entweder als eigenständiger PR oder als Teil einer Feature-PR. Dieser PR sollte NICHT mergen bis die Schritte 1-4 aus §Rollout durch sind, sonst blockiert der Gate in `enforce`-Mode alle User von dem neuen Tool. + +Empfohlener Workflow, wenn der Trigger-PR kommt: +1. Diesen Plan re-checken gegen aktuelle Repo-Realität (`space_members`-Shape, apps-api-Konventionen) +2. Schritte 1-4 als eigener Stack landen (kann parallel zum Trigger-PR laufen) +3. UI (5) + Metrik (6) + Doku (7) im selben Stack +4. Trigger-PR erst danach mergen +5. In den docs/plans diesen Plan als "shipped" markieren und den Trigger-PR referenzieren