b6fbf7a921
- Dockerfile with multi-stage build (Node 22 Alpine, sodium-native) - docker-compose.yml with health check for easy self-hosting - README with setup guide, API reference, and project overview - Architecture docs (data flow, component breakdown, protocol constants) - Security model docs (threat model, crypto primitives, self-hosting checklist) - GitHub Actions CI pipeline (test, typecheck, Docker smoke test, extension builds) - GitHub Actions release pipeline (GHCR push, extension zip artifacts) - CONTRIBUTING.md with dev setup and code style guidelines Co-Authored-By: Paperclip <noreply@paperclip.ing>
77 lines
1.7 KiB
Markdown
77 lines
1.7 KiB
Markdown
# Contributing to CookieBridge
|
|
|
|
## Getting Started
|
|
|
|
1. Fork and clone the repository.
|
|
2. Install dependencies: `npm install`
|
|
3. Start the dev server: `npm run dev`
|
|
4. Run tests: `npm test`
|
|
|
|
## Development Setup
|
|
|
|
**Prerequisites:**
|
|
- Node.js 22+
|
|
- npm
|
|
|
|
**Relay server:**
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev # Starts with file watching on :8080
|
|
npm test # Run test suite
|
|
npm run typecheck # Type checking only
|
|
```
|
|
|
|
**Extension:**
|
|
|
|
```bash
|
|
cd extension
|
|
npm install
|
|
node esbuild.config.mjs --browser=chrome
|
|
```
|
|
|
|
Load the unpacked extension from `extension/build/chrome/` in your browser.
|
|
|
|
## Making Changes
|
|
|
|
1. Create a branch from `main`.
|
|
2. Make focused, small commits. Each commit should do one thing.
|
|
3. Run `npm test` and `npm run typecheck` before pushing.
|
|
4. Open a pull request against `main`.
|
|
|
|
## Code Style
|
|
|
|
- TypeScript strict mode everywhere.
|
|
- No frameworks on the server — use Node.js built-ins where possible.
|
|
- Use libsodium for all cryptographic operations. No `crypto.subtle` or OpenSSL.
|
|
- Keep dependencies minimal.
|
|
|
|
## Testing
|
|
|
|
Tests use Vitest. Run with `npm test`.
|
|
|
|
- `tests/crypto.test.ts` — Encryption and signing primitives.
|
|
- `tests/pairing.test.ts` — Device pairing flow.
|
|
- `tests/conflict.test.ts` — LWW conflict resolution.
|
|
- `tests/integration.test.ts` — Full server integration tests.
|
|
|
|
Add tests for new features. Integration tests should start a real server instance.
|
|
|
|
## Commit Messages
|
|
|
|
Use clear, imperative commit messages:
|
|
|
|
```
|
|
feat: add cookie expiry sync support
|
|
fix: handle WebSocket reconnect on network change
|
|
docs: update self-hosting guide
|
|
```
|
|
|
|
## Reporting Issues
|
|
|
|
Open an issue with:
|
|
- What you expected to happen.
|
|
- What actually happened.
|
|
- Steps to reproduce.
|
|
- Browser and OS version (for extension issues).
|