Files

Test / test (push) Has been cancelled

Details

docs: M-Hard 9-11 — README, examples, CI, benchmarks, migration guide

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>

2026-04-10 17:58:30 +02:00

1.8 KiB

Raw Blame History

Contributing to Shade

Thanks for considering a contribution. Shade is a security-critical library, so the bar for changes is high but the process is straightforward.

Development setup

git clone https://github.com/Sterister/Shade
cd Shade
bun install
bun test --recursive

All tests should pass before you submit a change.

Running with PostgreSQL

The PostgreSQL backend tests are skipped by default. To run them:

docker run -d --name shade-test-pg -e POSTGRES_PASSWORD=test -p 5999:5432 postgres:16-alpine
SHADE_TEST_PG_URL=postgres://postgres:test@localhost:5999/postgres bun test --recursive

Running benchmarks

bun run bench/run.ts

Results are written to bench/results.md.

Code style

TypeScript strict mode
No any except at storage boundaries
TSDoc on all public APIs
Tests for every new feature
Constant-time comparisons for any operation involving secret data

Security disclosure

For security vulnerabilities, see SECURITY.md. Please do NOT open public issues for security bugs.

Commit conventions

Use clear, descriptive commit messages. Conventional Commits style is encouraged but not required:

feat(core): add identity rotation
fix(server): handle empty prekey replenishment
docs: update threat model

Pull requests

Fork the repo
Create a feature branch
Make your changes with tests
Run bun test --recursive and ensure all pass
Open a PR with a clear description

What gets accepted

Bug fixes (always welcome)
New tests for existing functionality
Documentation improvements
New storage backends
Performance improvements that don't compromise security

What needs discussion first

Changes to the wire format (breaking)
Changes to cryptographic primitives
Removing existing API surface
Changes to error codes

1.8 KiB Raw Blame History