Sterister
75008b623a
M-Hard 9: Documentation + examples - README.md, SECURITY.md, THREAT-MODEL.md - 5 runnable examples: basic conversation, prekey server, WebSocket tunnel, identity verification, Dokploy deployment M-Hard 10: CI + publishing + benchmarks - GitHub Actions: test workflow with PostgreSQL service container - GitHub Actions: publish workflow for npm releases on git tags - Benchmark suite (bench/run.ts) with markdown output - LICENSE (MIT), CHANGELOG.md, CONTRIBUTING.md M-Hard 11: Migration guide - MIGRATION.md with three-phase rollout strategy - Concrete examples for replacing static AES tunnels - Concrete examples for per-device push notification migration - Sections for Orchestrator and Nova migrations Benchmark highlights: - AES-256-GCM: ~100K ops/sec - Encrypt+decrypt roundtrip: ~17K ops/sec - X3DH handshake: ~165 ops/sec (hardware acceleration limited) - Compute fingerprint: ~76K ops/sec All 11 M-Hard milestones complete. 193 tests passing, 0 failures. Shade is production-ready. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2.2 KiB
Security Policy
Reporting a Vulnerability
If you discover a security vulnerability in Shade, please report it privately by emailing the maintainer rather than opening a public issue. We take all reports seriously and will respond within 48 hours.
When reporting, please include:
- A description of the vulnerability
- Steps to reproduce
- Affected versions
- Potential impact
- Any suggested mitigation
What's in scope
Shade aims to provide:
- Confidentiality of message contents (only sender and intended recipient can read)
- Forward secrecy (past messages stay safe if a key is compromised later)
- Post-compromise security (future messages re-secure after compromise)
- Authentication of identity keys (signed prekey verification, replay protection)
Vulnerabilities in any of these guarantees are in scope and high priority.
What's out of scope
Shade does NOT protect against:
- A compromised endpoint (if your device is rooted, the attacker can read messages directly)
- Metadata leakage (the prekey server sees who fetches whose bundle and when)
- Traffic analysis (encrypted message sizes and timing are visible)
- A malicious prekey server distributing fake bundles (mitigation: verify safety numbers out-of-band)
- Loss of user identity verification (if users don't compare fingerprints, MITM is possible at session establishment)
These are documented in THREAT-MODEL.md.
Identity verification recommendation
When using Shade, you should provide users with a way to compare safety numbers out-of-band (in person, over a video call, or through a separate trusted channel) before treating a session as fully verified. The getIdentityFingerprint() API returns a 60-digit number formatted in 12 groups, designed for human comparison.
Cryptographic primitives
Shade uses well-established primitives:
- X25519 for Diffie-Hellman key agreement (via @noble/curves)
- Ed25519 for digital signatures (via @noble/curves)
- AES-256-GCM for symmetric encryption (via Web Crypto SubtleCrypto)
- HKDF-SHA256 for key derivation (via Web Crypto SubtleCrypto)
- HMAC-SHA256 for chain key advancement (via Web Crypto SubtleCrypto)
These match the Signal Protocol specification.