diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..393e13f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,15 @@ +--- +name: Bug report +about: Report an interoperability, specification, or reference-codec defect +title: "bug: " +--- + +## What happened? + +## Expected behavior + +## Minimal non-sensitive reproducer or vector + +## LEP version and affected component + + diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..da944ef --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Report a security vulnerability privately + url: https://github.com/laststate/protocol/security/policy + about: Follow the security policy instead of opening a public issue. diff --git a/.github/ISSUE_TEMPLATE/proposal.md b/.github/ISSUE_TEMPLATE/proposal.md new file mode 100644 index 0000000..bddc6af --- /dev/null +++ b/.github/ISSUE_TEMPLATE/proposal.md @@ -0,0 +1,13 @@ +--- +name: Protocol proposal +about: Propose a compatible LEP change +title: "proposal: " +--- + +## Problem + +## Proposed wire-format or registry change + +## Compatibility and migration impact + +## Vector and implementation plan diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..b5ad8b7 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +version: 2 +updates: + - package-ecosystem: gomod + directory: /implementations/go + schedule: + interval: weekly + - package-ecosystem: github-actions + directory: / + schedule: + interval: weekly diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..3b3623e --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,17 @@ +## Summary + +## Compatibility + +- [ ] This does not change existing LEP v1 field semantics. +- [ ] This updates the specification and registry before implementation. +- [ ] This adds or updates golden vectors where wire behavior changes. + +## Validation + +- [ ] `cd implementations/go && go vet ./... && go test ./...` +- [ ] `python conformance/runner/run.py` + +## Data handling + +- [ ] This pull request contains no credentials, private keys, production + captures, or personal data. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bc012f4..2847997 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -16,6 +16,9 @@ jobs: with: go-version: '1.22.x' cache-dependency-path: implementations/go/go.sum + - name: Vet reference codec + working-directory: implementations/go + run: go vet ./... - name: Go reference codec working-directory: implementations/go run: go test ./... diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..300125d --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,26 @@ +name: CodeQL + +on: + push: + branches: [main] + pull_request: + branches: [main] + schedule: + - cron: '23 4 * * 1' + +permissions: + contents: read + security-events: write + +jobs: + analyze: + if: github.event.repository.private == false + name: Analyze Go + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: github/codeql-action/init@v3 + with: + languages: go + - uses: github/codeql-action/autobuild@v3 + - uses: github/codeql-action/analyze@v3 diff --git a/.gitignore b/.gitignore index 08d5fa3..991528b 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,13 @@ __pycache__/ *.pyc .DS_Store Thumbs.db +.env +.env.* +!.env.example +*.pem +*.key +*.p12 +*.pfx implementations/go/vendor/ *.exe *.test diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..7374557 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,27 @@ +# Community Code of Conduct + +## Our commitment + +We commit to a welcoming, harassment-free community for everyone, regardless +of age, body size, disability, ethnicity, gender identity or expression, +experience level, nationality, neurodiversity, personal appearance, race, +religion, sexual identity or orientation. + +## Expected behavior + +- Be respectful, constructive, and open to technical disagreement. +- Focus review on evidence, interoperability, and user safety. +- Respect privacy and do not share captures, credentials, or personal data. + +## Unacceptable behavior + +Harassment, discrimination, threats, personal attacks, doxxing, deliberate +disruption, and the disclosure of private information without permission are +not acceptable. + +## Enforcement + +Maintainers may remove comments, reject contributions, or restrict +participation when this policy is violated. To report a concern confidentially, +use the repository's [private reporting channel](https://github.com/laststate/protocol/security/advisories/new). +Reports are handled only by maintainers and shared on a need-to-know basis. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a364c35..aad455b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,29 @@ # Contributing -1. Wire changes go in `spec/` and `registry/` first. -2. Add or update golden vectors under `test-vectors/`. -3. Keep `implementations/go` matching valid vectors. -4. Run `go test ./...` in `implementations/go` and `python conformance/runner/run.py`. +Thanks for improving LEP. By contributing, you agree to follow the +[Code of Conduct](CODE_OF_CONDUCT.md). + +## Before opening a pull request + +1. Discuss a new wire assignment or incompatible proposal in an issue first. +2. Put wire-format changes in `spec/` and `registry/` before implementation. +3. Add or update golden vectors under `test-vectors/`. +4. Keep `implementations/go` matching valid vectors. +5. Do not include device captures, credentials, private keys, or customer data. +6. Run the checks below and describe compatibility impact in the pull request. + +```bash +cd implementations/go && go vet ./... && go test ./... +python conformance/runner/run.py +``` + +## Compatibility expectations + +LEP v1 additions must preserve the fixed header and existing field semantics. +Unknown TLVs are length-skipped; unknown header flag bits are rejected. See +[spec/compatibility.md](spec/compatibility.md) before allocating a type or flag. + +## Reporting a security issue + +Do not use a public issue for vulnerabilities. Follow the +[security policy](SECURITY.md) instead. diff --git a/PUBLICATION.md b/PUBLICATION.md new file mode 100644 index 0000000..e8220a7 --- /dev/null +++ b/PUBLICATION.md @@ -0,0 +1,19 @@ +# Public repository checklist + +Complete these GitHub settings immediately before changing repository +visibility: + +- Enable private vulnerability reporting, Dependabot alerts, secret scanning, + and push protection. +- Enable Code Scanning; the checked-in CodeQL workflow runs automatically once + the repository is public. +- Require pull-request review and successful CI for `main`; restrict direct + pushes and force pushes. +- Confirm that the repository description, topics, default branch, and issue + tracker are intentional and that Actions are limited to trusted workflows. +- Review commit authorship and git history for information that should not be + public. Rewriting published history requires explicit maintainer approval. + +Before the change, run the checks in [CONTRIBUTING.md](CONTRIBUTING.md) from a +fresh clone and verify that [SECURITY.md](SECURITY.md) links to an enabled +private reporting channel. diff --git a/README.md b/README.md index 7b68a53..f7eda2d 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,16 @@ cd implementations/go && go test ./... python conformance/runner/run.py ``` +## Community and security + +- [Contributing guide](CONTRIBUTING.md) +- [Security policy](SECURITY.md) +- [Code of conduct](CODE_OF_CONDUCT.md) +- [Support](SUPPORT.md) + +Maintainers preparing a visibility change should complete the +[publication checklist](PUBLICATION.md). + ## License Apache-2.0 — [`LICENSE`](LICENSE) diff --git a/SECURITY.md b/SECURITY.md index 6c616dd..cfd07cc 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -1,6 +1,25 @@ -# Security +# Security policy + +## Supported versions + +| Version | Supported | +| --- | --- | +| 1.x | Yes | +| Earlier versions | No | + +## Reporting a vulnerability + +Use the repository's [private security advisory form](https://github.com/laststate/protocol/security/advisories/new). +Do not open a public issue or include production captures, credentials, or keys. + +Include the affected version, a minimal reproducer or vector, impact, and any +mitigation. Maintainers aim to acknowledge reports within five business days, +coordinate a fix, and agree on disclosure timing with the reporter. + +## Protocol safety requirements - CRC detects corruption, not adversaries. -- Use HMAC or AEAD for authenticity; verify before parsing TLVs. -- Bound all lengths before allocation. -- Report protocol-security issues privately to the maintainers before public disclosure. +- Use HMAC or AEAD for authenticity and verify it before exposing TLVs. +- Bound all lengths before allocation or decompression. +- Treat unknown TLVs according to the compatibility rules; reject unknown flag + bits and malformed framing. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 0000000..a2b6ea9 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,9 @@ +# Support + +Use GitHub Issues for questions about the published LEP specification, +reference codec, or golden vectors. Include the protocol version, the relevant +TLV or framing detail, and a minimal non-sensitive example where possible. + +For vulnerabilities, follow the [security policy](SECURITY.md). Do not post +credentials, private keys, production captures, or personally identifying data +in issues or pull requests.