# 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](./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.