Shade/CHANGELOG.md

Changelog

All notable changes to Shade are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[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)