Add tenant-scoped task API authentication for CovenCave and hosted clients

[romgenie]

Local source: coven-github/issues/02-add-tenant-scoped-task-api-authentication.md

Summary

The current task API is suitable for local CovenCave polling, but hosted coven-github needs tenant-scoped authentication and authorization before any task state, memory status, logs, links, or artifacts are exposed.

Current Evidence

• crates/webhook/src/routes.rs exposes GET /api/github/tasks through list_tasks, which returns state.task_store.list().await.
• docs/security.md says each GitHub installation should be treated as a tenant boundary.
• docs/security.md also says the public task API must not return cross-installation data and that the current in-memory /api/github/tasks path is suitable only for local development and Cave polling.
• HOSTED.md and docs/hosted-mvp-plan.md list tenant-scoped task API auth as a launch blocker.

Problem

Task state is sensitive. It can reveal private repository names, issue titles, PR links, branch names, Check Run links, failure output, model/provider errors, and eventually memory or transcript pointers. In hosted mode, a single API endpoint that lists all tasks would create a cross-tenant data exposure risk.

Impact

• A Cave client from one installation could see another installation's task history.
• Internal logs or agent summaries could leak private repository information.
• Operators cannot safely expose task polling to hosted customers.
• Audit, billing, and support boundaries remain ambiguous.

Proposed Design

Add a tenant model keyed by GitHub installation id and repository policy:

• Tenant: installation id, account id/login, allowed repositories, plan, status.
• TenantUser or CaveSession: identity that can view one or more tenant scopes.
• TaskVisibility: installation id, repository id/name, task id, allowed viewer roles.

Protect task APIs with one of these mechanisms:

• internal service token for Cave-to-adapter polling in self-hosted mode;
• signed short-lived Cave session token scoped to one installation/repository;
• hosted control-plane auth that maps a user/org to installation access.

Every task API query should include a tenant scope and enforce it server-side.

Acceptance Criteria

• /api/github/tasks no longer returns all tasks without auth in hosted mode.
• API callers can request only tasks within their authorized installation/repo scope.
• Unit tests prove installation A cannot fetch installation B task data.
• Error responses do not reveal whether inaccessible task ids exist.
• Docs clearly distinguish local unauthenticated development mode from hosted authenticated mode.
• Audit logs record the caller, tenant scope, task id, and result for task API reads.

Test Notes

Create route tests with two installation ids and two task records. Verify a token scoped to installation 1 can list and read only installation 1 tasks. Verify missing/invalid tokens fail closed in hosted mode.

---

Wave 1 grooming

• Size: L · Intra-wave rank: 2 — highest fan-out; the hosted tenancy gate.
• Depends on: Add durable task queue and GitHub delivery idempotency #2. Unblocks: Define hosted memory governance contract between coven-github and coven-code #6, Add installation-scoped familiar routing and repository policy #7, Add usage metering plus tier limits and concurrency controls #15, Build Cave oversight dashboard for task history, routing, usage, and audit #18.
• In scope: tenant model keyed by installation id; server-side scope enforcement on /api/github/tasks read paths; fail-closed in hosted mode; internal-token bypass for self-hosted; audit record per task-API read.
• Out of scope: plan/billing enforcement (Add usage metering plus tier limits and concurrency controls #15), memory governance (Define hosted memory governance contract between coven-github and coven-code #6), routing (Add installation-scoped familiar routing and repository policy #7), dashboard UI (Build Cave oversight dashboard for task history, routing, usage, and audit #18) — this lands the boundary they consume.
• Ready checklist:
  1. Define Tenant (installation id, account, allowed repos, plan, status) + viewer/session identity in crates/server.
  2. Thread a TenantScope through task_store.list() and task-read paths in crates/webhook/src/routes.rs.
  3. Auth extractor: internal service token (self-hosted) vs signed short-lived Cave session token (hosted); fail closed on missing/invalid in hosted mode.
  4. Enforce scope server-side on every task query; return not-found (not forbidden) for out-of-scope ids.
  5. Emit audit record: caller, tenant scope, task id, result.
  6. Mark the hosted auth path implemented in docs/security.md.
• Done when: two-installation route tests prove A can't read B; missing/invalid token fails closed in hosted mode; errors don't reveal id existence; cargo check/clippy/test green.

Owner: Cody (engineering lane) · Approval gate: Val · GitHub assignee: @BunsDev