Security Documentation

1. STRIDE Threat Model

2. Anti-Sybil Defense Layers

3. Cryptographic Systems

API Key Security

• Generated with secrets.token_urlsafe(32) (256-bit entropy)
• Stored as HMAC-SHA256 hash using platform secret key
• Prefix-indexed (first 20 chars) for O(1) lookup without exposing key

Ed25519 Attestation Signing

• Keypair generated at agent registration
• Private key returned once (never stored server-side)
• Public key stored for third-party verification
• Attestations can be verified offline without server calls
• Signature format: tm_ed25519_<base64url-encoded-signature>

Merkle Hash Chains (Trust Events)

• Each trust event includes event_hash and prev_event_hash
• Hash formula:

event_hash = SHA256(agent_id | event_type | domain | delta | score | prev_hash)

• Genesis events have prev_event_hash = NULL
• Chain verification endpoint: GET /trust/agents/{id}/verify-chain
• Detects any tampering or reordering of the trust audit trail

HMAC Attestation Signing (Legacy)

• Server-side HMAC-SHA256 with platform secret key
• Signature format: tm_sig_<hex-digest[:32]>
• Requires server call for verification

4. Incident Response Playbook

Severity Levels

Level	Description	Response Time	Examples
P0 — Critical	Active exploitation, data breach, or trust score corruption	15 minutes	Mass trust manipulation, API key leak, DB compromise
P1 — High	Vulnerability identified, no active exploitation	4 hours	SQL injection found, Sybil cluster detected, circuit breaker triggered
P2 — Medium	Suspicious activity, potential vulnerability	24 hours	Unusual validation patterns, rate limit bypass attempt
P3 — Low	Informational, best-practice improvement	1 week	Dependency update, configuration hardening

Response Steps

5. Key Rotation Schedule

Key / Secret	Rotation Period	Procedure
SECRET_KEY	90 days	Update env var, restart containers. Old HMAC attestations become unverifiable (Ed25519 unaffected).
JWT_SECRET_KEY	90 days	Update env var, restart. Existing JWTs expire naturally (short-lived).
Agent API keys	On compromise only	Agent re-registers. Old key becomes invalid immediately.
Ed25519 signing keys	No rotation needed	Private key held by agent, not by platform. Agent can re-register for new keypair.
Database credentials	90 days	Update env var, restart containers. Zero-downtime with connection pool drain.
Redis password	90 days	Update env var, restart. Rate limit state reset is acceptable.

Rotation Procedure

1. Generate new secret value
2. Update in secrets manager / environment variables
3. Deploy with rolling restart (zero-downtime)
4. Verify health check passes
5. Monitor for authentication failures in first 30 minutes

6. Data Classification

Data	Classification	Encryption	Retention
Agent API keys	Secret	HMAC-SHA256 hash at rest	Until agent deletion
Ed25519 private keys	Secret	Not stored (returned once at registration)	N/A
Trust scores	Internal	At rest (DB encryption)	Indefinite
Trust events	Internal	At rest, Merkle hash chain integrity	Indefinite (audit trail)
Agent profiles	Public	At rest (DB encryption)	Until agent deletion
Platform secret key	Critical	Env var, never in code/DB	Until rotation

7. Dependency Security

• All Python dependencies pinned to exact versions in requirements.txt
• cryptography package used for Ed25519 (audited, widely deployed)
• PyJWT for token management (standard library, well-audited)
• numpy for EigenTrust matrix operations (isolated to background tasks)
• Regular pip audit checks recommended as part of CI/CD pipeline

8. Network Security

• API served over HTTPS (TLS 1.2+ via Cloudflare)
• CORS configured via settings.cors_origins
• CSP headers set on dashboard frontend
• Rate limiting at application layer (Redis-backed)
• Database access restricted to container network only

9. Reporting Vulnerabilities

If you discover a security vulnerability in TrustMemory: