Skip to main content

​
Trust Model

Treeship uses Ed25519 digital signatures to create verifiable attestations.

​
Cryptographic Primitives

ComponentAlgorithmPurpose
SigningEd25519Fast, secure signatures
HashingSHA256Payload and input fingerprinting
EncodingBase64Signature transport

​
What You’re Trusting

​
When Using Treeship API

You trust that:
  • Treeship’s private key is secure
  • Timestamps are accurate
  • Attestations are stored correctly
You don’t need to trust:
  • That attestations haven’t been modified (signatures prove this)
  • That Treeship is telling the truth about verification (you can verify yourself)

​
With Self-Hosting

You control:
  • The signing key
  • The timestamp source
  • The storage

​
Key Management

Treeship uses a single Ed25519 keypair: 
Private Key: Stored securely, never exposed
Public Key: Published at /v1/pubkey, freely distributable
Key ID: First 16 chars of SHA256(public_key_bytes)
The public key can be:
  • Cached locally
  • Mirrored on your own servers
  • Embedded in client applications

​
Signature Verification

Ed25519 signatures guarantee:
  1. Authenticity: Only the private key holder could create this signature
  2. Integrity: Any modification invalidates the signature
  3. Non-repudiation: The signer cannot deny creating the signature

​
Threat Model

​
Protected Against

  • Tampering: Modified attestations fail verification
  • Forgery: Cannot create valid signatures without private key
  • Replay: Each attestation has a unique ID and timestamp

​
Not Protected Against

  • Key Compromise: If private key is stolen, attacker can sign
  • False Claims: Treeship signs what agents claim, not ground truth
  • Timing Attacks: Timestamps are from signing time, not action time

​
Best Practices

  1. Cache the public key locally for offline verification
  2. Verify important attestations independently, not just via API
  3. Monitor your agent feed for unexpected attestations
  4. Use input hashing to link attestations to specific data

​
Self-Hosting

For maximum trust minimization, run your own Treeship instance: 
# Generate your own key
python -c "from treeship_api.signing import KeyPair; print(KeyPair.generate().to_pem().decode())"

# Deploy with your key
TREESHIP_SIGNING_KEY=base64-encoded-pem railway up
See Self-Hosting Guide for details.