MuseHub Threat Model

Last updated: 2026-04-07
Author: gabriel

System Overview

MuseHub is the remote server for the Muse version control system. It stores pushed commits, hosts issue tracking and merge proposals, and serves as the hub for multi-agent orchestration via agentception. Two types of principals interact with MuseHub:

• Human users — authenticated via Ed25519 keypairs registered at account creation.
• Agent identities — short-lived Ed25519 keypairs registered programmatically by agentception at runtime, carrying an explicit capability scope and an expiry timestamp.

All communication is over HTTPS. There are no passwords, sessions, or bearer tokens. Every authenticated request carries a per-request Ed25519 signature.

Authentication: MSign

Protocol

Every authenticated request carries:

Authorization: MSign handle="gabriel" ts=1712345678 sig="<base64url>"

The signature covers the canonical message:

METHOD\n
PATH_WITH_QUERY\n
UNIX_TIMESTAMP\n
SHA256_HEX(body_bytes)

The server verifies the signature against the registered public key(s) for the handle. Replay protection: requests are rejected when |server_time - ts| > 30 seconds.

Key properties

Threat mitigations

Identity Hierarchy

gabriel (human, permanent)
  └── agentception-service (service identity, 24h TTL)
        └── agentception-{run_id} (ephemeral agent identity, 2h TTL)

Identity types

Identity lifecycle

1. Registration: POST /api/v1/identities/agents — requires a valid MSign token from the parent identity. Stores public key and scope.
2. Request signing: Agent signs requests with its private key. Server verifies against stored public key.
3. Scope check: require_scope("X") dependency rejects requests where identity.scope is non-null and does not contain "X".
4. Expiry check: _verify_msign rejects requests for identities where expires_at <= now. Checked before signature verification.
5. Revocation: DELETE /api/v1/identities/{handle} — sets deleted_at, immediately visible to all subsequent requests.

Capability Scopes

Scope enforcement is implemented in require_scope() (musehub/auth/request_signing.py). Rules:

• scope = null — human identity; no capability restrictions. All authenticated operations are permitted.
• scope = [...] — agent identity; only listed tokens are permitted. Missing token → HTTP 403.
• Empty scope [] — agent is blocked from every scoped operation.

Scope taxonomy

Who holds which scopes

Human identities carry scope = null and pass all scope checks unconditionally — there are no human-only capabilities. Any operation can be granted to an agent by including the relevant token in its scope list at registration time.

Defence-in-Depth Layers

Layer 1: Bot throttle (ASGI middleware)

BotThrottleMiddleware runs before any route handler. It short-circuits at the ASGI level for known-bad User-Agent patterns (scrapers, scanners). Exempt paths: /healthz, /static/, /mcp, /api/health/.

MSign-authenticated requests bypass the UA check entirely — cryptographic identity supersedes User-Agent heuristics.

Layer 2: Request signing (MSign)

Every route that mutates state requires a valid MSign token. Anonymous access is permitted only for read operations on public repos.

Layer 3: Scope enforcement

Write routes use Depends(require_scope("X")) instead of Depends(require_valid_token). This ensures agent identities are limited to their registered capability set.

Layer 4: Expiry enforcement

_verify_msign checks expires_at before attempting signature verification. An expired identity is rejected even if its private key is still cryptographically valid.

Layer 5: Soft-delete / revocation

deleted_at is checked in every identity lookup. Revoked identities are immediately invisible without requiring key rotation or cache invalidation.

Layer 6: Per-route slowapi rate limits

Routes are rate-limited by IP + identity. Authentication failures do not count against the route limit but are tracked by failure_limiter to detect credential stuffing.

Known Limitations and Future Work

Incident Response

Compromised human key

1. muse auth keygen --hub <hub> — generate a new key.
2. DELETE /api/v1/identities/{handle}/keys/{key_id} — revoke the old key.
3. All subsequent requests using the old key are rejected immediately.

Compromised agent key

1. DELETE /api/v1/identities/{handle} — soft-delete the agent identity. Takes effect immediately.
2. Generate a new ephemeral identity for the next run.

Suspected replay attack

1. Check access logs for duplicate (handle, ts) pairs within the 30-second window.
2. If systematic, reduce REPLAY_WINDOW_SECONDS and rotate the affected identity's key.