This document describes the security boundaries coven-github needs for self-hosted operators and the hosted OpenCoven service.

For the companion visual map of the installation, secret, worker, and task-history boundaries, see Architecture Diagrams.

coven-github authenticates as a GitHub App:

• The GitHub App private key signs short-lived JWTs.
• JWTs are exchanged for installation access tokens scoped to a specific installation.
• Installation tokens are used for repository clone, Check Runs, comments, and pull requests.
• User GitHub credentials are never required for worker pushes.

Self-hosted operators are responsible for storing the private key and webhook secret outside the repository. Hosted OpenCoven should store these in managed secret storage and rotate webhook secrets when an installation is reconfigured.

Every webhook request must include X-Hub-Signature-256. The receiver validates the HMAC over the raw request body before parsing JSON. Invalid or missing signatures are rejected before task routing.

Production hosted ingress should also add:

• Delivery ID idempotency with X-GitHub-Delivery.
• Rate limits by installation and repository.
• Structured audit logs for accepted, rejected, and duplicate deliveries.

Workers execute coven-code --headless using a per-task workspace. Current development workers use local directories and enforce task timeouts. Production hosted workers should run each task in an isolated container or sandbox.

flowchart LR
    install[GitHub installation]
    token[Short-lived installation token]
    workspace[Per-task workspace]
    runtime[coven-code process]
    logs[Redacted logs and evidence]
    checks[GitHub Check Run and PR]

    install --> token
    token --> workspace
    workspace --> runtime
    runtime --> logs
    logs --> checks

Worker rules:

• Create one workspace per task.
• Pass only the installation token required for that repository.
• Clean up workspaces after task completion or failure.
• Enforce timeout and retry limits.
• Persist failure states before cleanup.

See Container Isolation for the production isolation target.

The current session brief includes clone auth so coven-code can operate on the repository. The production target is stricter:

• Prefer GIT_ASKPASS or environment-based git auth over embedding tokens in JSON.
• Avoid writing installation tokens to durable task stores.
• Redact tokens in logs, Check Runs, issue comments, PR bodies, and task APIs.
• Refresh installation tokens through a single token manager with cache expiry.

Hosted OpenCoven should treat each GitHub installation as a tenant boundary.

Tenant-scoped data:

• Installation ID and repository list.
• Familiar routing config.
• Task history, status, branch, PR, and Check Run links.
• Optional familiar memory, if enabled by the customer.

The public task API must not return cross-installation data. The current in-memory /api/github/tasks path is suitable for local development and Cave polling, but hosted usage needs tenant-scoped authentication before launch.

OpenCoven's strongest hosted differentiator is familiar identity plus memory. That also makes data boundaries explicit:

• BYOM keys should be installation-scoped or organization-scoped.
• Model routing choices should be visible to operators.
• Cloud familiar memory should be opt-in for hosted customers.
• Retention should be configurable by tier and organization policy.
• PR bodies should disclose the familiar identity and link back to the oversight session.

Before accepting paid hosted customers, the service should have:

• Durable task persistence.
• Delivery idempotency.
• Tenant-scoped task API auth.
• Worker timeout enforcement.
• Containerized or sandboxed worker execution.
• Secret redaction tests.
• A documented data retention policy.