From 2a2a14b4e97061d9529babfa6fd6d7f363d6c6d1 Mon Sep 17 00:00:00 2001 From: alpha912 Date: Sat, 20 Dec 2025 21:08:50 +0000 Subject: [PATCH] docs(governance): add RFC workflow and compliance notes --- README.md | 11 ++++++++++ docs/compliance/dpia-lite.md | 37 ++++++++++++++++++++++++++++++++ docs/compliance/threat-model.md | 30 ++++++++++++++++++++++++++ docs/governance/rfc-process.md | 38 +++++++++++++++++++++++++++++++++ rfcs/0001-rfc-process.md | 33 ++++++++++++++++++++++++++++ rfcs/README.md | 38 ++++++--------------------------- rfcs/template.md | 25 ++++++++++++++++++++++ 7 files changed, 180 insertions(+), 32 deletions(-) create mode 100644 docs/compliance/dpia-lite.md create mode 100644 docs/compliance/threat-model.md create mode 100644 docs/governance/rfc-process.md create mode 100644 rfcs/0001-rfc-process.md create mode 100644 rfcs/template.md diff --git a/README.md b/README.md index 35dc4b5..0fdeaa2 100644 --- a/README.md +++ b/README.md @@ -83,11 +83,22 @@ We welcome contributions! See CONTRIBUTING.md for guidelines. 3. Start a discussion in GitHub Discussions 4. Submit RFCs for protocol changes +## 🧭 Governance (Lab Stage) + +- RFC workflow: `docs/governance/rfc-process.md` +- RFC index: `rfcs/README.md` + ## 📚 Resources Public resources are still being assembled. For now, use GitHub Discussions and the repository documentation. +- Specification: `SPECIFICATION.md` +- API reference: `openapi.json` +- Security guide: `docs/security-guide.md` +- Threat model: `docs/compliance/threat-model.md` +- DPIA lite: `docs/compliance/dpia-lite.md` + ## 🎯 Roadmap ### v0.1.1 (Current) diff --git a/docs/compliance/dpia-lite.md b/docs/compliance/dpia-lite.md new file mode 100644 index 0000000..b21c9cc --- /dev/null +++ b/docs/compliance/dpia-lite.md @@ -0,0 +1,37 @@ +# DPIA Lite (Lab Baseline) + +This DPIA-lite is a **lab-only baseline** for early-stage evaluation. It does +not imply production readiness or pilot deployment. + +## Data categories +- **Protocol payloads**: MaterialDNA, Offer, Match, Transfer (non-PII). +- **Interest submissions**: optional contact data (name, email, organization). + +## Purpose +Enable lab validation of protocol flows and collect early interest from +potential collaborators. + +## Legal basis (lab stage) +Consent for optional contact data; legitimate interest for aggregate analytics. + +## Data minimization +- Avoid personal data in protocol payloads. +- Collect only optional contact data required for follow-up. +- Support opt-in for public listing. + +## Retention +Retain lab data only as long as needed for validation; delete on request. + +## Security measures +- TLS for transport. +- Request size limits and rate limiting. +- Audit logging of submissions and events. + +## Risks and mitigations +- **Risk**: accidental exposure of contact data. + **Mitigation**: optional email visibility and redaction. +- **Risk**: over-collection. + **Mitigation**: strict schema and minimization policy. + +## Review cadence +Reassess before any pilot or production deployment. diff --git a/docs/compliance/threat-model.md b/docs/compliance/threat-model.md new file mode 100644 index 0000000..f8de45a --- /dev/null +++ b/docs/compliance/threat-model.md @@ -0,0 +1,30 @@ +# Threat Model (Lab Baseline) + +This threat model is a **lab-only baseline** for the LOOP protocol. It is not a +production security assessment. + +## System boundaries +- **LOOP Node API** (lab demo): handles MaterialDNA, Offer, Match, Transfer. +- **Event log**: immutable audit trail for lab events. +- **Public interest registry**: optional contact data. + +## Assets +- Protocol payloads (MaterialDNA, Offer, Match, Transfer) +- Event logs and timestamps +- Optional contact data (interest submissions) + +## Threats (STRIDE-lite) + +| Threat | Example | Mitigation (lab) | +| --- | --- | --- | +| Spoofing | Fake node identity | Mutual TLS / signed requests (future), allowlist in lab | +| Tampering | Offer payload modified | Schema validation, server-side logging | +| Repudiation | Deny match acceptance | Immutable event log with timestamps | +| Information disclosure | PII leaks | Data minimization, redact logs | +| Denial of service | Flood endpoints | Rate limits, request size limits | +| Elevation of privilege | Abuse admin endpoints | Auth scaffolding (future), least privilege | + +## Residual risk (lab stage) +Risks remain due to the early TRL level and the absence of production-grade +identity, key management, and audit tooling. This document should be revisited +before any pilot deployments. diff --git a/docs/governance/rfc-process.md b/docs/governance/rfc-process.md new file mode 100644 index 0000000..0173aa0 --- /dev/null +++ b/docs/governance/rfc-process.md @@ -0,0 +1,38 @@ +# RFC Process (v0.1) + +This RFC process is a lightweight governance workflow for the LOOP protocol +while the project remains in **lab-only, low-TRL** stage. It is intended to +create clear, reviewable decisions without implying production readiness. + +## Goals +- Make protocol changes transparent and traceable. +- Capture rationale, alternatives, and security/privacy impacts. +- Keep the process lightweight for early-stage iteration. + +## Scope +Applies to: +- Protocol schema changes +- API surface changes +- Node interoperability rules +- Governance and security requirements + +## RFC states +1. **Draft** – Authoring and internal review. +2. **Discussion** – Open for comments (target: 10 business days). +3. **Accepted / Rejected** – Decision documented with rationale. +4. **Implemented** – Linked to merged PRs and release notes. +5. **Superseded** – Replaced by a newer RFC. + +## How to submit +1. Copy `rfcs/template.md` → `rfcs/NNNN-title.md`. +2. Fill in all required sections. +3. Open a PR with the RFC for review. +4. The PI or designated reviewer approves or rejects the RFC. + +## Decision rules (lab stage) +- Favor reversible changes. +- Require explicit notes on security/privacy impact. +- Document any breaking changes and migration steps. + +## Record keeping +Accepted RFCs are indexed in `rfcs/README.md` and referenced from the changelog. diff --git a/rfcs/0001-rfc-process.md b/rfcs/0001-rfc-process.md new file mode 100644 index 0000000..ababbfb --- /dev/null +++ b/rfcs/0001-rfc-process.md @@ -0,0 +1,33 @@ +# RFC-0001: RFC Process (v0.1) + +## Summary +Establish a lightweight RFC workflow for the LOOP protocol during lab-only +development to document decisions and ensure traceability. + +## Motivation +We need a consistent process for evolving schemas and interoperability rules +without implying production readiness. A minimal RFC flow provides clarity for +reviewers (including EC stakeholders) while keeping iteration lightweight. + +## Proposal +Adopt the process defined in `docs/governance/rfc-process.md` with the states: +Draft → Discussion → Accepted/Rejected → Implemented → Superseded. + +## Security & Privacy +Each RFC must include security and privacy impact notes. No PII should be added +to protocol payloads. + +## Backwards Compatibility +RFCs must explicitly state if changes are breaking and include migration notes. + +## Implementation Plan +1. Add RFC docs and templates. +2. Require RFC links for schema/API changes. +3. Track accepted RFCs in the changelog. + +## Alternatives Considered +- No formal process (rejected: lacks traceability). +- Heavy governance workflow (rejected: too slow for lab stage). + +## Open Questions +None for v0.1. diff --git a/rfcs/README.md b/rfcs/README.md index 75a8171..2e4e680 100644 --- a/rfcs/README.md +++ b/rfcs/README.md @@ -1,35 +1,9 @@ -# RFCs +# RFC Index -RFCs capture proposed protocol changes. Use the template in `rfcs/0000-template.md`. +This directory contains LOOP Protocol Request for Comments (RFCs). -## Lifecycle -1. Draft -2. Review -3. Accepted (or Rejected) -4. Implemented +## Active +- RFC-0001: RFC process (v0.1) -## Naming -- Use a four-digit prefix (e.g., `0001-`) -- Use kebab-case for the title - -## Submission checklist -- Clear problem statement and motivation -- Backwards compatibility analysis -- Security and privacy considerations -- Open questions noted - -## How to Cite - -If you reference this repository, please cite: -Alphin Tom. "LOOP Protocol RFCs." LocalLoop, GitHub repository, 2025-2026. https://github.com/local-loop-io/loop-protocol - -```bibtex -@misc{localloop_protocol_rfcs_2025, - author = {Alphin Tom}, - title = {LOOP Protocol RFCs}, - year = {2025}, - howpublished = {GitHub repository}, - url = {https://github.com/local-loop-io/loop-protocol}, - note = {Accessed 2025-12-19} -} -``` +## How to submit +Use `rfcs/template.md` to create a new RFC and open a PR. diff --git a/rfcs/template.md b/rfcs/template.md new file mode 100644 index 0000000..f09a59a --- /dev/null +++ b/rfcs/template.md @@ -0,0 +1,25 @@ +# RFC-XXXX: Title + +## Summary +Short description of the change. + +## Motivation +Why is this needed? What problem does it solve? + +## Proposal +Describe the change in detail (schemas, flows, APIs). + +## Security & Privacy +List potential risks and mitigations (STRIDE-lite). + +## Backwards Compatibility +State if this is breaking. Provide migration notes if needed. + +## Implementation Plan +Steps and milestones to deliver. + +## Alternatives Considered +Briefly note other options and why they were rejected. + +## Open Questions +Outstanding items to resolve.