likwid/.windsurf/plans/likwid-stabilization-6061c4.md

# Likwid Stabilization Megaplan (6061c4)

Stabilize Likwid into a production-usable system by shipping a coherent admin modular-rule management UX (built-in + WASM), making WASM packages production-grade (including background jobs + SSRF-hardening), and converging authorization on roles/permissions.

## Decisions (confirmed)
- Git history: **linear `main` via squash merges**.
- Demo VPS: **tracks `main`**.
- Modular rules approach: **Hybrid** (built-in DB-backed settings + built-in modules + WASM plugin packages).
- Authz direction: **roles/permissions is authoritative**.
- Phase 1 default instance guidance: `instance_type=multi_community`, `platform_mode=admin_only`.
- `plugin_allow_background_jobs`: **full implementation** (end-to-end semantics, not just a stored flag).
- Registry SSRF hardening: **yes** (DNS-aware; do not rely only on host string / IP-literal checks).
- Community admin UX scope: **full** (plugin policy + WASM packages + built-in plugins in one coherent flow).
- Plan handling: **commit plan to `main`** once approved (plan-first discipline).

## Non-negotiable outcomes (Phase 1)
- Operational reliability + install/upgrade story.
- Admin modular rule management UX.
- WASM third-party plugin packages are production-grade.
- End-user UX consistency (avoid confusing partial configuration states).

## Current state (source-backed highlights)
- Backend exposes community endpoints:
  - `GET/PUT /api/communities/{id}/plugin-policy`
  - `GET/POST/PUT /api/communities/{id}/plugin-packages` (+ `install-registry`)
- WASM runtime exists (wasmtime; fuel + timeout + memory limits).
- WASM outbound HTTP is capability-gated and allowlisted.
- Registry allowlist currently:
  - blocks `localhost`
  - blocks IP-literal loopback/private/link-local/unspecified
  - matches exact host or `*.suffix`
  - **does not** do DNS resolution + post-resolution IP classification.
- Frontend currently does not call `plugin-policy` / `plugin-packages` (community UI covers built-in plugins only).

## Scope boundaries
- No architectural rewrite.
- Minimal, targeted changes per milestone.
- No dependency additions unless clearly required for an explicit acceptance criterion.

## Milestone discipline / verification
- Each milestone lands as a single squash-merge PR to `main`.
- Required verification per milestone:
  - Backend: `cargo check` (and `cargo test` if stable)
  - Frontend: `npm run build`
  - Demo VPS: deploy `main` and run `./scripts/smoke-test.sh demo`

---

## Phase 0 — Baseline + operator invariants (gate)

### Deliverables
- Single authoritative operator workflow for:
  - local dev start/stop
  - demo deploy/update
  - rollback
  - smoke test
- Confirm demo systemd + compose wiring is consistent with docs and scripts.

### Acceptance criteria
- Demo VPS updated to latest `main` and `./scripts/smoke-test.sh demo` passes.

### Verification
- Run smoke test on VPS.

---

## Phase 1 — Admin modular rule management UX (hybrid)

### Goal
One coherent admin flow for:
- community built-in plugins (`plugins` + `community_plugins`)
- community WASM plugin packages (`plugin_packages` + `community_plugin_packages`)
- community plugin policy (`communities.settings` keys)

### Deliverables (frontend)
- Community admin UI adds a “Plugins / Rules” surface that includes:
  - Built-in community plugins management (existing functionality retained).
  - Plugin policy editor (read + update):
    - trust policy
    - install sources
    - registry allowlist
    - trusted publishers
    - outbound HTTP toggle + allowlist
    - background jobs toggle
  - WASM package manager:
    - list installed packages
    - upload package
    - install from registry URL
    - activate/deactivate
    - edit package settings (schema-driven when available; raw JSON fallback)
- Clear error messages for:
  - policy forbids uploads / registry installs
  - signature requirements fail
  - registry allowlist blocks URL

### Deliverables (backend contract hardening)
- Ensure API error responses are stable and actionable for UI (status code + message consistency).
- Ensure event emission for key actions is consistent (`public_events`).

### Acceptance criteria
- As community admin/moderator:
  - can view/update plugin policy
  - can install a WASM package (upload + registry) when policy allows
  - can activate/deactivate packages
  - can edit package settings and receive server-side schema validation errors when invalid

### Verification
- Manual UI walkthrough covering:
  - signed-only policy
  - registry allowlist allow/deny
  - outbound HTTP allowlist allow/deny
  - background jobs on/off behavior (see Phase 2 definition)

---

## Phase 2 — WASM packages production-grade hardening

### 2.1 Background jobs: **full implementation**

#### Proposed semantics (must be implemented consistently)
- `plugin_allow_background_jobs=false` means:
  - WASM plugins must **not** be invoked for cron hooks for that community.
  - Any future “scheduled” behavior for WASM must be gated by the same setting.
- `plugin_allow_background_jobs=true` means:
  - WASM plugins may receive cron hooks they declare in their manifest (e.g. `cron.minute`, `cron.hourly`, `cron.daily`, ...).

#### Implementation outline (expected code touchpoints)
- Resolve where WASM cron hooks are dispatched (currently cron loop exists in `backend/src/main.rs` and invokes `PluginManager::do_wasm_action_for_community`).
- Add a community-settings check (`communities.settings.plugin_allow_background_jobs`) in the WASM cron dispatch path.
- Ensure policy API default behavior is explicit and safe:
  - confirm default is false (current parse default is false).

#### Acceptance criteria
- When `plugin_allow_background_jobs=false`, WASM cron hooks are not executed for that community.
- When `plugin_allow_background_jobs=true`, WASM cron hooks execute normally.

### 2.2 Registry install SSRF hardening (DNS-aware)

#### Goal
Registry install should not be able to reach internal/private addresses via DNS rebinding or private resolution.

#### Deliverables
- Extend registry allowlist enforcement to:
  - resolve DNS for hostname-based registry URLs
  - reject if any resolved IP is loopback/private/link-local/unspecified/unique-local (IPv6)
- Keep existing protections:
  - reject `localhost`
  - reject IP-literal private/loopback
  - enforce allowlist patterns

#### Acceptance criteria
- Registry install is blocked when a hostname resolves to a private/loopback/link-local address.

### 2.3 Registry fetch hardening (timeouts/size caps)

#### Deliverables
- Add explicit timeout and size bounds to registry bundle fetch.
  - Current code path uses `reqwest::get(...)` without explicit timeout/size cap.

#### Acceptance criteria
- Registry fetch cannot hang indefinitely.
- Registry fetch cannot load an unbounded payload.

### 2.4 Operator-visible metadata

#### Deliverables
- UI shows package metadata:
  - publisher
  - sha256
  - signature present
  - source (upload/registry)
  - registry URL
  - manifest-declared hooks + capabilities
  - effective outbound HTTP permission status

---

## Phase 3 — Authz convergence (roles/permissions authoritative)

### Goal
Stop using `community_members.role` as the primary enforcement mechanism for privileged actions.

### Deliverables
- Inventory endpoints that currently use `ensure_admin_or_moderator` style gates.
- Introduce/confirm permissions for:
  - managing plugin policy
  - managing plugin packages
  - managing community plugin settings
- Migrate gates to permission checks consistently.

### Acceptance criteria
- Plugin policy + package management endpoints authorize via roles/permissions.

---

## Phase 4 — Technical debt hotspot inventory + targeted fixes

### Deliverables
- Evidence-backed inventory (file/function-level) of:
  - cross-layer coupling hotspots
  - duplicated policy parsing/enforcement
  - plugin plane confusion (instance defaults vs community plugins vs wasm packages)
  - any unstable areas discovered during Phases 1–3
- Only fix hotspots that block Phase 1–3 acceptance criteria.

---

## Commit plan (after this plan is approved)
- Add this plan into the repo under `.windsurf/plans/` and commit to `main`.
- Implementation starts only after the plan commit lands.