Sterister
75008b623a
Some checks failed
Test / test (push) Has been cancelled
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>
77 lines
1.8 KiB
Markdown
77 lines
1.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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](./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
|
|
|
|
1. Fork the repo
|
|
2. Create a feature branch
|
|
3. Make your changes with tests
|
|
4. Run `bun test --recursive` and ensure all pass
|
|
5. 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
|