Skip to content

Commit 173a1e2

Browse files
alpha912alpha912
authored
docs(governance): add RFC workflow and compliance notes (#2)
1 parent 29f9295 commit 173a1e2

File tree

7 files changed

+180
-32
lines changed

7 files changed

+180
-32
lines changed

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,11 +83,22 @@ We welcome contributions! See CONTRIBUTING.md for guidelines.
8383
3. Start a discussion in GitHub Discussions
8484
4. Submit RFCs for protocol changes
8585

86+
## 🧭 Governance (Lab Stage)
87+
88+
- RFC workflow: `docs/governance/rfc-process.md`
89+
- RFC index: `rfcs/README.md`
90+
8691
## 📚 Resources
8792

8893
Public resources are still being assembled. For now, use GitHub Discussions and
8994
the repository documentation.
9095

96+
- Specification: `SPECIFICATION.md`
97+
- API reference: `openapi.json`
98+
- Security guide: `docs/security-guide.md`
99+
- Threat model: `docs/compliance/threat-model.md`
100+
- DPIA lite: `docs/compliance/dpia-lite.md`
101+
91102
## 🎯 Roadmap
92103

93104
### v0.1.1 (Current)

‎docs/compliance/dpia-lite.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# DPIA Lite (Lab Baseline)
2+
3+
This DPIA-lite is a **lab-only baseline** for early-stage evaluation. It does
4+
not imply production readiness or pilot deployment.
5+
6+
## Data categories
7+
- **Protocol payloads**: MaterialDNA, Offer, Match, Transfer (non-PII).
8+
- **Interest submissions**: optional contact data (name, email, organization).
9+
10+
## Purpose
11+
Enable lab validation of protocol flows and collect early interest from
12+
potential collaborators.
13+
14+
## Legal basis (lab stage)
15+
Consent for optional contact data; legitimate interest for aggregate analytics.
16+
17+
## Data minimization
18+
- Avoid personal data in protocol payloads.
19+
- Collect only optional contact data required for follow-up.
20+
- Support opt-in for public listing.
21+
22+
## Retention
23+
Retain lab data only as long as needed for validation; delete on request.
24+
25+
## Security measures
26+
- TLS for transport.
27+
- Request size limits and rate limiting.
28+
- Audit logging of submissions and events.
29+
30+
## Risks and mitigations
31+
- **Risk**: accidental exposure of contact data.
32+
**Mitigation**: optional email visibility and redaction.
33+
- **Risk**: over-collection.
34+
**Mitigation**: strict schema and minimization policy.
35+
36+
## Review cadence
37+
Reassess before any pilot or production deployment.

‎docs/compliance/threat-model.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Threat Model (Lab Baseline)
2+
3+
This threat model is a **lab-only baseline** for the LOOP protocol. It is not a
4+
production security assessment.
5+
6+
## System boundaries
7+
- **LOOP Node API** (lab demo): handles MaterialDNA, Offer, Match, Transfer.
8+
- **Event log**: immutable audit trail for lab events.
9+
- **Public interest registry**: optional contact data.
10+
11+
## Assets
12+
- Protocol payloads (MaterialDNA, Offer, Match, Transfer)
13+
- Event logs and timestamps
14+
- Optional contact data (interest submissions)
15+
16+
## Threats (STRIDE-lite)
17+
18+
| Threat | Example | Mitigation (lab) |
19+
| --- | --- | --- |
20+
| Spoofing | Fake node identity | Mutual TLS / signed requests (future), allowlist in lab |
21+
| Tampering | Offer payload modified | Schema validation, server-side logging |
22+
| Repudiation | Deny match acceptance | Immutable event log with timestamps |
23+
| Information disclosure | PII leaks | Data minimization, redact logs |
24+
| Denial of service | Flood endpoints | Rate limits, request size limits |
25+
| Elevation of privilege | Abuse admin endpoints | Auth scaffolding (future), least privilege |
26+
27+
## Residual risk (lab stage)
28+
Risks remain due to the early TRL level and the absence of production-grade
29+
identity, key management, and audit tooling. This document should be revisited
30+
before any pilot deployments.

‎docs/governance/rfc-process.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# RFC Process (v0.1)
2+
3+
This RFC process is a lightweight governance workflow for the LOOP protocol
4+
while the project remains in **lab-only, low-TRL** stage. It is intended to
5+
create clear, reviewable decisions without implying production readiness.
6+
7+
## Goals
8+
- Make protocol changes transparent and traceable.
9+
- Capture rationale, alternatives, and security/privacy impacts.
10+
- Keep the process lightweight for early-stage iteration.
11+
12+
## Scope
13+
Applies to:
14+
- Protocol schema changes
15+
- API surface changes
16+
- Node interoperability rules
17+
- Governance and security requirements
18+
19+
## RFC states
20+
1. **Draft** – Authoring and internal review.
21+
2. **Discussion** – Open for comments (target: 10 business days).
22+
3. **Accepted / Rejected** – Decision documented with rationale.
23+
4. **Implemented** – Linked to merged PRs and release notes.
24+
5. **Superseded** – Replaced by a newer RFC.
25+
26+
## How to submit
27+
1. Copy `rfcs/template.md` → `rfcs/NNNN-title.md`.
28+
2. Fill in all required sections.
29+
3. Open a PR with the RFC for review.
30+
4. The PI or designated reviewer approves or rejects the RFC.
31+
32+
## Decision rules (lab stage)
33+
- Favor reversible changes.
34+
- Require explicit notes on security/privacy impact.
35+
- Document any breaking changes and migration steps.
36+
37+
## Record keeping
38+
Accepted RFCs are indexed in `rfcs/README.md` and referenced from the changelog.

‎rfcs/0001-rfc-process.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# RFC-0001: RFC Process (v0.1)
2+
3+
## Summary
4+
Establish a lightweight RFC workflow for the LOOP protocol during lab-only
5+
development to document decisions and ensure traceability.
6+
7+
## Motivation
8+
We need a consistent process for evolving schemas and interoperability rules
9+
without implying production readiness. A minimal RFC flow provides clarity for
10+
reviewers (including EC stakeholders) while keeping iteration lightweight.
11+
12+
## Proposal
13+
Adopt the process defined in `docs/governance/rfc-process.md` with the states:
14+
Draft → Discussion → Accepted/Rejected → Implemented → Superseded.
15+
16+
## Security & Privacy
17+
Each RFC must include security and privacy impact notes. No PII should be added
18+
to protocol payloads.
19+
20+
## Backwards Compatibility
21+
RFCs must explicitly state if changes are breaking and include migration notes.
22+
23+
## Implementation Plan
24+
1. Add RFC docs and templates.
25+
2. Require RFC links for schema/API changes.
26+
3. Track accepted RFCs in the changelog.
27+
28+
## Alternatives Considered
29+
- No formal process (rejected: lacks traceability).
30+
- Heavy governance workflow (rejected: too slow for lab stage).
31+
32+
## Open Questions
33+
None for v0.1.

‎rfcs/README.md‎

Lines changed: 6 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,9 @@
1-
# RFCs
1+
# RFC Index
22

3-
RFCs capture proposed protocol changes. Use the template in `rfcs/0000-template.md`.
3+
This directory contains LOOP Protocol Request for Comments (RFCs).
44

5-
## Lifecycle
6-
1. Draft
7-
2. Review
8-
3. Accepted (or Rejected)
9-
4. Implemented
5+
## Active
6+
- RFC-0001: RFC process (v0.1)
107

11-
## Naming
12-
- Use a four-digit prefix (e.g., `0001-`)
13-
- Use kebab-case for the title
14-
15-
## Submission checklist
16-
- Clear problem statement and motivation
17-
- Backwards compatibility analysis
18-
- Security and privacy considerations
19-
- Open questions noted
20-
21-
## How to Cite
22-
23-
If you reference this repository, please cite:
24-
Alphin Tom. "LOOP Protocol RFCs." LocalLoop, GitHub repository, 2025-2026. https://github.com/local-loop-io/loop-protocol
25-
26-
```bibtex
27-
@misc{localloop_protocol_rfcs_2025,
28-
author = {Alphin Tom},
29-
title = {LOOP Protocol RFCs},
30-
year = {2025},
31-
howpublished = {GitHub repository},
32-
url = {https://github.com/local-loop-io/loop-protocol},
33-
note = {Accessed 2025-12-19}
34-
}
35-
```
8+
## How to submit
9+
Use `rfcs/template.md` to create a new RFC and open a PR.

‎rfcs/template.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# RFC-XXXX: Title
2+
3+
## Summary
4+
Short description of the change.
5+
6+
## Motivation
7+
Why is this needed? What problem does it solve?
8+
9+
## Proposal
10+
Describe the change in detail (schemas, flows, APIs).
11+
12+
## Security & Privacy
13+
List potential risks and mitigations (STRIDE-lite).
14+
15+
## Backwards Compatibility
16+
State if this is breaking. Provide migration notes if needed.
17+
18+
## Implementation Plan
19+
Steps and milestones to deliver.
20+
21+
## Alternatives Considered
22+
Briefly note other options and why they were rejected.
23+
24+
## Open Questions
25+
Outstanding items to resolve.

0 commit comments

Comments
 (0)