Agent Provenance in Muse

Overview

Muse is built for the agent-first world. Agents and humans are equal first-class cryptographic principals. Every commit carries structured provenance — who wrote this commit, with which model, using which toolchain, and can that attribution be verified cryptographically?

Principals and trust chains

Human operator (gabriel)
    ↓ provisions at spawn time
Agent (agentception-abc123)
    ↓ signs each commit with its own keypair
CommitRecord.signature  ← Ed25519, embedded public key, offline-verifiable

Trust is established at provisioning time, not commit time. When an agent is spawned, the operator registers its dedicated keypair with MuseHub via POST /api/identities/agent. The server sets spawned_by = operator.handle and stores the trust chain. Every subsequent commit signed by the agent's key carries that chain back to the operator.

Commit-level fields

CommitRecord in muse/core/commits.py carries optional agent provenance fields:

Signing model (format_version 8)

Signatures use Ed25519 (RFC 8032 / FIPS 186-5). The signed input is a SHA-256 digest binding the commit's identity to its authorship claims:

provenance_payload = SHA-256(
    commit_id \0 author \0 agent_id \0 model_id \0 toolchain_id \0 prompt_hash
)

Any post-signing mutation of author, agent_id, model_id, toolchain_id, or prompt_hash is detected by muse verify.

The signer_public_key field embedded in the commit record allows anyone to verify without access to the private key or any external service (offline verification).

Key storage

Human operator key

~/.muse/identity.toml:
    ["localhost:1337"]
    type = "human"
    handle = "gabriel"
    algorithm = "ed25519"
    fingerprint = "sha256:abc123..."
    hd_path = "m/1075233755'/0'/0'/0'/0'/0'"

Agent-dedicated key (HD-derived, in memory)

~/.muse/identity.toml:
    ["localhost:1337#agentception-abc123"]               # compound key
    type = "agent"
    handle = "agentception-abc123"
    algorithm = "ed25519"
    fingerprint = "sha256:def456..."
    hd_path = "m/1075233755'/0'/0'/0'/1'/0'"
    provisioned_by = "gabriel"
    capabilities = ["push", "pull"]

Ephemeral agent key (fd injection)

For short-lived agent runs, agentception derives a 64-byte sub-seed and injects it via a kernel pipe file descriptor — never via an environment variable (env vars are visible in /proc/<pid>/environ and process listings):

r_fd, w_fd = os.pipe()
os.write(w_fd, sub_seed_64_bytes)
os.close(w_fd)
env = {**os.environ, "MUSE_AGENT_KEY_FD": str(r_fd), "MUSE_AGENT_HANDLE": "agentception-abc123"}
subprocess.Popen(["claude-code", ...], env=env, pass_fds=(r_fd,))
os.close(r_fd)

get_signing_identity() reads MUSE_AGENT_KEY_FD first (highest priority), derives the Ed25519 key via SLIP-0010, then falls back to the identity store.

Provisioning a dedicated agent key

On-disk agent key (operator workflow)

# 1. Generate the agent's keypair
muse auth keygen --hub https://localhost:1337 --agent-id agentception-abc123

# 2. Register with MuseHub (stores trust chain: spawned_by = gabriel)
muse auth register --hub https://localhost:1337 \
  --agent-id agentception-abc123 \
  --handle agentception-abc123 \
  --provisioned-by gabriel

# 3. Sign commits as the agent
muse commit -m "feat: add harmony voice" \
  --agent-id agentception-abc123 \
  --model-id claude-sonnet-4-6 \
  --sign

Ephemeral agent key (agentception workflow)

from agentception.services.agent_identity import register_agent_identity

identity = await register_agent_identity(
    run_id="abc123",
    model_id="claude-sonnet-4-6",
    scope=["push:agentception"],
)

# Inject into Claude Code subprocess via pipe fd, not env var
r_fd, w_fd = os.pipe()
os.write(w_fd, identity.sub_seed_bytes)
os.close(w_fd)
env = {**os.environ, "MUSE_AGENT_KEY_FD": str(r_fd), "MUSE_AGENT_HANDLE": identity.handle}
subprocess.Popen(["claude-code", ...], env=env, pass_fds=(r_fd,))
os.close(r_fd)

Signing resolution order (commit time)

get_signing_identity(repo_root, agent_id=...) tries in this order:

1. MUSE_AGENT_KEY_FD — 64-byte sub-seed via pipe fd (only supported env injection)
2. Agent-specific entry "hostname#agent_id" in ~/.muse/identity.toml
3. Human entry "hostname" in ~/.muse/identity.toml (fallback for operators)

Signing and verification API

muse/core/provenance.py provides:

from muse.core.provenance import (
    sign_commit_ed25519, verify_commit_ed25519,
    encode_public_key, sign_commit_record, provenance_payload,
)
from muse.core._types import public_key_fingerprint

# Sign the provenance payload.
payload = provenance_payload(commit_id, agent_id="agentception-abc123", author="gabriel")
sig = sign_commit_ed25519(payload, private_key)

# Embed the public key in the commit for offline verification.
raw_bytes, pub_b64 = encode_public_key(private_key)
fprint = public_key_fingerprint(raw_bytes)

# Verify (offline — no hub required).
assert verify_commit_ed25519(payload, sig, raw_bytes)

# Convenience: sign a commit in one call.
sig, pub_b64, fprint = sign_commit_record(
    commit_id, "agentception-abc123", private_key,
    author="gabriel", model_id="claude-sonnet-4-6",
)

Querying provenance

muse read <ref>                             # human-readable, includes provenance
muse read <ref> --json                      # machine-readable full record
muse log --format json | jq '.[] | .agent_id'
muse shortlog --by agent                    # group commits by agent
muse code lineage "file.py::Symbol"         # provenance chain of a specific symbol
muse verify                                 # verify all Ed25519 signatures in history

Related files