# Contributing to PulseProof Sentinel Protocol Thank you for your interest in contributing to **PulseProof Sentinel Protocol**, abbreviated **PPS**. PPS is an experimental authentication protocol. Contributions are welcome across specification, documentation, security analysis, test vectors, and reference implementations. By participating in this project, you agree to follow the [Code of Conduct](CODE_OF_CONDUCT.md). --- ## Project Status | Item | Value | |---|---| | Protocol | PulseProof Sentinel Protocol | | Abbreviation | PPS | | Protocol Version | 1 | | Status | Experimental | | Internet-Draft | [draft-hezami-pulseproof-sentinel](https://datatracker.ietf.org/doc/draft-hezami-pulseproof-sentinel/) | PPS is not audited and is not production-ready. --- ## Ways to Contribute You can contribute by: - reviewing the specification - reporting ambiguities - proposing security improvements - identifying threats or attack vectors - proposing test vectors - implementing SDKs - improving documentation - reviewing CBOR canonicalization rules - reviewing duress and threshold models - comparing PPS with existing standards - improving examples - creating interoperability tests - building demos - reviewing IETF feedback --- ## Repository Layout ```text . ├── README.md ├── SPEC.md ├── SECURITY.md ├── CONTRIBUTING.md ├── CODE_OF_CONDUCT.md ├── CHANGELOG.md ├── docs/ │ ├── README.md │ ├── overview.md │ ├── comparison.md │ ├── threat-model.md │ ├── implementers-guide.md │ ├── faq.md │ ├── ietf.md │ ├── deployment-guide.md │ ├── duress-guide.md │ ├── threshold-guide.md │ └── policy-guide.md ``` Some directories may be added progressively. --- ## Development Setup for Documentation The documentation site can be built with MkDocs Material. Install dependencies: ```bash pip install mkdocs-material ``` Run locally: ```bash mkdocs serve ``` Build: ```bash mkdocs build ``` --- ## Contribution Process ### 1. Open an Issue First For significant changes, open an issue first. This is especially important for: - protocol changes - cryptographic changes - CBOR structure changes - security model changes - duress behavior changes - threshold behavior changes - policy object changes Small documentation fixes may be submitted directly. --- ### 2. Fork and Branch Fork the repository and create a topic branch. Example: ```bash git checkout -b fix/cbor-canonicalization-note ``` --- ### 3. Make Focused Changes Keep pull requests focused. Avoid mixing: - specification changes - documentation changes - implementation changes - formatting changes in a single large pull request unless necessary. --- ### 4. Test Your Changes For specification changes, check: - consistency with `SPEC.md` - consistency with CDDL - consistency with examples - consistency with test vectors - impact on implementers - impact on security considerations For code changes, run relevant tests. For documentation changes, build the documentation site locally. --- ### 5. Submit a Pull Request In your pull request, include: - summary of the change - motivation - related issue number - security impact, if any - implementation impact, if any - whether the change affects interoperability --- ## Specification Contributions Specification changes should preserve: - protocol clarity - implementation feasibility - cryptographic soundness - backward compatibility where possible - clear error handling - clear verification order - technology neutrality When changing the specification, consider updating: ```text SPEC.md docs/overview.md docs/implementers-guide.md docs/threat-model.md CHANGELOG.md ``` --- ## Test Vectors Test vectors are highly valuable. Good test vectors include: - valid single-device Pulse - valid duress Pulse - valid threshold Pulse - expired Pulse - replayed counter - wrong RP hash - wrong nonce - wrong policy hash - wrong context hash - wrong AmountMark - invalid signature - non-canonical CBOR - rotation certificate chain - offline Pulse - Trust Code derivation cases Each test vector should include: ```text description inputs expected output expected error, if invalid ``` --- ## Code Style Follow the standard style for each language. ### PHP - PSR-12 - strict types where possible - use `ext-sodium` or maintained polyfills - avoid manual cryptography ### JavaScript / TypeScript - ESLint - Prettier - TypeScript recommended - avoid Node-only APIs in browser packages unless separated ### Python - Ruff - Black - type hints recommended - use maintained cryptographic libraries ### Go - gofmt - go vet - standard project layout ### Rust - rustfmt - clippy - safe code preferred --- ## Commit Messages Use clear commit messages. Conventional Commits are recommended: ```text feat: add threshold mode example fix: correct Trust Code salt derivation docs: clarify CBOR canonicalization rules security: add duress timing guidance test: add invalid nonce test vector chore: update mkdocs navigation ``` --- ## Pull Request Checklist Before submitting a pull request, check: - [ ] changes are focused - [ ] documentation is updated - [ ] specification consistency is preserved - [ ] CDDL is updated if structures changed - [ ] examples are updated if needed - [ ] test vectors are added if applicable - [ ] no secrets are included - [ ] no private keys are included - [ ] no production credentials are included - [ ] changelog is updated if needed - [ ] documentation builds successfully - [ ] security impact is considered --- ## Security Contributions If you discover a security vulnerability, do not open a public pull request or issue. See [SECURITY.md](SECURITY.md). Security improvements that are not vulnerabilities may be discussed publicly as issues. --- ## Licensing of Contributions Unless otherwise stated: - code contributions are licensed under the Apache License 2.0 - documentation contributions are licensed under CC-BY 4.0 - Internet-Draft text is subject to IETF Trust provisions By submitting a contribution, you agree that it may be distributed under these licenses. If your contribution includes third-party material, clearly identify its license. --- ## IETF Feedback PPS is submitted as an individual Internet-Draft: ```text draft-hezami-pulseproof-sentinel ``` Feedback received through IETF channels may be incorporated into future draft revisions. See [docs/ietf.md](docs/ietf.md). --- ## Questions If you are unsure where to start: 1. Read [docs/overview.md](docs/overview.md). 2. Read [docs/comparison.md](docs/comparison.md). 3. Read [SPEC.md](SPEC.md). 4. Open a discussion or issue with your question. Questions about implementation, security, or protocol design are welcome.