Security Architecture¶

This document describes the security architecture of Diogenes for security professionals evaluating the system's threat model, cryptographic design, and trust boundaries.

Design Principles¶

Private keys never leave the client. All signing is performed client-side. The server only receives public keys and signatures. This is enforced at the API level (SC-01) and at the middleware level (the PrivateKeyRejectionMiddleware scans request bodies for private key patterns and rejects them).
Content never reaches the server. Documents are hashed locally. Only the SHA-256 digest is transmitted for verification. This preserves document confidentiality.
Append-only log. The transparency log is append-only and hash-chained. Once an entry is committed, it cannot be altered without breaking the chain. Chain integrity can be verified by any party.
No central authority. Trust is established through a decentralized web of endorsements. There is no certificate authority whose compromise would undermine the entire system.
Defense in depth. Multiple security layers operate independently: cryptographic verification, key status checking, trust assessment, rate limiting, password protection, and temporal anchoring.

Cryptographic Primitives¶

Primitive	Usage	Notes
Ed25519	Key pairs, attestation signatures	Recommended algorithm. Edwards-curve Digital Signature Algorithm.
ECDSA P-256	Key pairs, browser signing	Compatible with Web Crypto API. SHA-256 hash.
RSA-2048	Key pairs (legacy)	Supported for backward compatibility.
SHA-256	Content hashing, fingerprints, log chain	Used throughout for hash computation.
Argon2id	Password hashing	Key passwords hashed with Argon2id before storage.
HMAC-SHA256	JWT signing	JWTs signed with operator key for session management.

Trust Boundaries¶

graph TD
    subgraph Client["Client (Browser / CLI)"]
        KG["Key Generation
(private)"]
        SG["Signing
(private)"]
        CH["Content Hashing
(document stays local)"]
    end
    subgraph Server["Server (API)"]
        SV["Signature Verification"]
        KR["Key Registry
(public keys)"]
        TL["Transparency Log
(append-only)"]
        RL["Rate Limiting"]
        SH["Security Headers
(CSP, HSTS)"]
        PKR["Private Key Rejection"]
    end
    subgraph DB["Database (PostgreSQL)"]
        DATA["Keys, Log Entries,
Endorsements, Auth Challenges"]
    end
    subgraph BTC["Bitcoin (via OpenTimestamps)"]
        TA["Temporal anchoring
of log entries"]
    end
    Client -- "HTTPS
(public keys, signatures, hashes only)" --> Server
    Server --> DB
    DB --> BTC

Authentication Model¶

Challenge-Response¶

Mutating operations (key succession, revocation, endorsement operations) require proof of key possession via a challenge-response protocol:

The server issues a random nonce bound to a specific fingerprint.
The client signs the nonce with their private key.
The server verifies the signature against the registered public key.

Challenges expire (configurable TTL) and are single-use. Replay attacks are prevented by challenge consumption.

JWT Sessions¶

For browser-based portal sessions, a challenge-response exchange produces a JWT with:

30-minute TTL (configurable)
8-hour maximum session duration
Fingerprint binding (JWT is valid only for the authenticated key)
Optional recovery-only flag (limits operations available to recovered keys)

Password Protection¶

Keys can optionally register a password (Argon2id-hashed). When set, the password is required as a second factor for attestation signing and other sensitive operations.

Threat Model¶

Threats Addressed¶

Threat	Mitigation
Server compromise	Private keys never reach the server. Existing signatures remain valid. The append-only log detects tampering via hash chain verification.
Log tampering	Hash chain integrity verification. Temporal anchoring to Bitcoin provides external proof of log state. Merkle tree heads enable efficient audit.
Key theft	Password protection adds a second factor. Key revocation is immediate and logged. Endorser revocation alerts notify the trust network.
Sybil attacks	Endorsement capacity scaling, activation delays, privilege thresholds, and over-capacity discounting prevent trust network gaming.
Replay attacks	Challenge-response nonces are single-use and time-limited. JWTs have short TTLs.
Content leakage	Documents are never uploaded. Only hashes are transmitted.
Rate-based abuse	Per-IP rate limiting with resource-specific thresholds (key registrations, endorsements, attestations, general queries).

Threats Not Addressed (Out of Scope)¶

Threat	Notes
Client-side key theft	Diogenes does not manage private key storage. Key holders are responsible for securing their private keys.
Network-level attacks	HTTPS is enforced in production (HTTPS redirect middleware), but network security is the deployment operator's responsibility.
Quantum computing	Current algorithms (Ed25519, ECDSA, RSA) are not post-quantum resistant. Algorithm agility in the protocol allows future migration.

Security Headers¶

The SecurityHeadersMiddleware sets the following headers on all responses:

Header	Value	Purpose
`X-Content-Type-Options`	`nosniff`	Prevent MIME type sniffing
`X-Frame-Options`	`DENY`	Prevent clickjacking
`Content-Security-Policy`	Strict CSP	Prevent XSS and injection
`Strict-Transport-Security`	`max-age=...`	Enforce HTTPS
`X-XSS-Protection`	`1; mode=block`	Legacy XSS protection

Rate Limiting¶

Resource-specific rate limits are enforced via middleware:

Resource	Default Limit	Purpose
API queries	60/minute per IP	Prevent abuse
Key registrations	10/hour per IP	Limit Sybil key creation
Endorsement offers	50/day per IP	Limit trust network gaming
Attestation events	100/hour per IP	Prevent log flooding

Audit Capabilities¶

Full log export in JSON or CSV with combinable filters (fingerprint, document hash, date range).
Hash chain verification via POST /api/v1/log/verify.
Signed tree heads for Merkle inclusion proofs.
OpenTimestamps proofs for Bitcoin-anchored timestamps.
Audit trail queries with fingerprint and document scope.