# Changelog

All notable changes to Shade are documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [1.0.0] — 2026-04-10

### First production release

Shade implements the Signal Protocol (X3DH + Double Ratchet) as a standalone, audit-friendly E2EE library for TypeScript/Bun.

### Added

#### Core protocol
- **X3DH** key agreement (X25519 + Ed25519, supports asynchronous bundles)
- **Double Ratchet** with forward secrecy and post-compromise recovery
- Skipped message key cache for out-of-order delivery (max 1000 per chain)
- Header-bound AAD on AES-256-GCM encrypts (tampered headers fail decryption)
- Memory zeroization of message keys, chain keys, root keys, and DH private keys after use

#### Storage
- `MemoryStorage` (in-memory, for tests/embedded)
- `SQLiteStorage` (`@shade/storage-sqlite`) — bun:sqlite, WAL mode, crash-safe
- `PostgresStorage` (`@shade/storage-postgres`) — Drizzle, FOR UPDATE SKIP LOCKED
- All backends survive container restarts and SIGKILL
- Identity history with 7-day grace period for rotation

#### Prekey server (`@shade/server`)
- Hono-based REST API with self-authenticated registration (Ed25519 signatures)
- Anonymous bundle fetches (read-only)
- Per-IP and per-identity rate limiting (token bucket)
- Address validation (NFKC normalization, alphanumeric + `:_-.`)
- ±5 minute replay window on signed requests
- Health endpoints (`/health`, `/healthz`, `/ready`)
- Prometheus metrics (`/metrics`)
- Structured JSON logging
- Graceful shutdown on SIGTERM/SIGINT
- Production Dockerfile with non-root user, healthcheck, multi-stage build
- docker-compose.yml example for Dokploy

#### Session manager (`@shade/core`)
- `ShadeSessionManager` high-level API (`encrypt`, `decrypt`, `initSessionFromBundle`)
- `getIdentityFingerprint()` — Signal-style 60-digit safety numbers
- `ensurePreKeyStock()` — auto-replenish when below threshold
- `resetSession()` and `acceptIdentityChange()` for recovery scenarios
- `rotateIdentity()` with archived previous identities

#### Transport (`@shade/transport`)
- `ShadeFetchTransport` — HTTP client for the prekey server with auto-signing
- `ShadeWebSocket` — WebSocket wrapper with transparent encrypt/decrypt

#### Wire format (`@shade/proto`)
- Compact binary encoding (significantly smaller than JSON)
- Length-prefixed byte arrays, big-endian integers
- Version-tagged envelopes for forward compatibility

#### Cryptographic hardening
- `constantTimeEqual` (XOR-accumulator, no early exit)
- `randomUint32` via crypto.getRandomValues (no Math.random)
- Timing-attack regression test
- Constant-time trust verification in all storage backends

#### Errors
- Stable `SHADE_*` error codes
- `errorToHttpStatus` for consistent HTTP mapping
- `toJSON()` for network serialization
- 14 specific error types (Validation, Network, Storage, RateLimit, etc.)

#### Documentation
- README, SECURITY.md, THREAT-MODEL.md
- 5 runnable examples (basic conversation, prekey server, WebSocket tunnel, identity verification, Dokploy deployment)
- Per-package READMEs
- Inline TSDoc throughout

#### Testing
- 195+ tests across all packages
- Crash recovery integration test
- Cross-platform PostgreSQL tests (skip without `SHADE_TEST_PG_URL`)
- CI workflow with PostgreSQL service
- Benchmark suite

### Security properties
- Forward secrecy
- Post-compromise security
- Authenticated identity verification
- Replay protection
- Constant-time secret comparisons
- Memory zeroization (best-effort)