mojoatomic · mojoatomic · Oct 3, 2025 · Oct 3, 2025 · Oct 3, 2025
diff --git a/docs/PROTOCOL-COMPLIANCE-REPORT.md b/docs/PROTOCOL-COMPLIANCE-REPORT.md
@@ -173,7 +173,7 @@ Per Section 7 of the RDCP Protocol Specification:
 
 ### Current Level: Level 2 (Standard)
 
-Per Section 11 of the RDCP Protocol Specification:
+Per Section 12 of the RDCP Protocol Specification:
 
 #### Level 1: Basic (Met)
 - Implements all required endpoints

diff --git a/docs/rdcp-protocol-specification.md b/docs/rdcp-protocol-specification.md
@@ -6,6 +6,10 @@
 
 ---
 
+## Abstract
+
+The Runtime Debug Control Protocol (RDCP) is an HTTP-based protocol that enables dynamic control of debug logging in distributed systems without requiring application restarts or redeployment. RDCP provides standardized endpoints for discovering debug categories, enabling or disabling logging at runtime, monitoring system health, and tracking configuration changes through an audit trail. The protocol supports multiple security levels ranging from basic API key authentication for development environments to enterprise-grade mutual TLS for regulated industries. Multi-tenancy capabilities allow isolated configuration management across organizational boundaries. This specification defines the protocol architecture, message formats, authentication mechanisms, error handling, and compliance requirements for interoperable implementations across programming languages and platforms.
+
 ## 1. Protocol Overview
 
 ### 1.1 Scope
@@ -14,6 +18,13 @@ RDCP defines a standardized HTTP-based protocol for controlling debug logging in
 ### 1.2 Conformance Requirements
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
 
+### 1.3 Terminology
+
+- Debug Category: A named collection of debug instrumentation points that can be collectively enabled or disabled.
+- Tenant: An isolated configuration context, typically representing an organization or customer in a multi-tenant system.
+- Temporary Control: A time-limited debug configuration that automatically expires after a specified duration.
+- Security Level: A tier of authentication and authorization requirements (basic, standard, or enterprise).
+
 ---
 
 ## 2. Protocol Architecture
@@ -447,31 +458,227 @@ When actual metrics are unavailable:
 
 ## 8. Security Considerations
 
-### 8.1 Transport Security
-- Production deployments MUST use HTTPS
-- Development MAY use HTTP on localhost only
+### 8.1 Threat Model
+RDCP controls application behavior and may expose sensitive diagnostic information. The following threats are considered:
+
+In Scope:
+- Unauthorized access to debug controls
+- Information disclosure through debug output
+- Denial of service through resource exhaustion
+- Privilege escalation through scope manipulation
+- Replay attacks using captured credentials
+- Audit trail tampering
+
+Out of Scope:
+- Protection of debug output after it leaves the application
+- Network-level attacks (assumed TLS/mTLS provides transport security)
+- Host-level compromise (operating system security)
+
+### 8.2 Authentication Security
+
+Credential Strength:
+ API keys MUST be cryptographically random with minimum entropy of 128 bits
+- Keys MUST be compared using constant-time comparison to prevent timing attacks
+- Bearer tokens MUST use industry-standard formats (JWT with HS256/RS256, OAuth2)
+- Token validation MUST verify signature, issuer, audience, and expiration
+
+Credential Storage:
+- Servers MUST NOT log credentials in plaintext
+- Clients SHOULD store credentials in secure storage (keychains, vaults)
+- API keys SHOULD be rotatable without service interruption
+
+### 8.3 Authorization and Scopes
+Principle of Least Privilege:
+- Clients SHOULD request minimum necessary scopes
+- Servers MUST validate scopes for each operation
+- Control operations MUST require explicit "control" scope
+- Status/discovery MAY use broader "discovery" scope
+
+Scope Validation:
+- Servers MUST reject operations when required scopes are absent
+- Scope elevation MUST NOT be possible through protocol manipulation
+- Multi-tenant systems MUST enforce tenant isolation in scope validation
+
+### 8.4 Transport Security
+TLS Requirements:
+- Production deployments MUST use TLS; TLS 1.3 is RECOMMENDED
+- TLS 1.2 MAY be used only where TLS 1.3 is unavailable
+- Development MAY use HTTP only on localhost (127.0.0.1/::1)
+- Servers SHOULD use HSTS headers to enforce HTTPS
+
+Certificate Validation:
+- Clients MUST validate server certificates
+- mTLS deployments MUST validate client certificates
+- Certificate pinning MAY be used for enhanced security
+- Self-signed certificates MUST NOT be used in production
+
+### 8.5 Denial of Service Protection
+Rate Limiting:
+- Control endpoints SHOULD limit requests to 60/minute per client
+- Status endpoints MAY allow higher rates (e.g., 600/minute)
+- Rate limits SHOULD be enforced per authenticated identity
+- 429 Too Many Requests response MUST include Retry-After header
+
+Resource Exhaustion:
+- Temporary controls MUST have maximum duration limits (24 hours RECOMMENDED)
+- Server SHOULD limit concurrent temporary controls per tenant
+- Discovery responses SHOULD limit category list size
+- Request timeouts SHOULD be enforced (30 seconds RECOMMENDED)
+
+### 8.6 Replay Attack Prevention
+Request Uniqueness:
+- Clients SHOULD include unique X-RDCP-Request-ID header
+- Servers MAY implement request deduplication (5-minute window RECOMMENDED)
+- Timestamp validation SHOULD reject requests with clock skew >5 minutes
+- Nonces MAY be required for high-security deployments
+
+### 8.7 Audit Trail Security
+Tamper Evidence:
+- Audit logs SHOULD use append-only storage
+- Enterprise deployments SHOULD use cryptographic hashing (e.g., SHA-256)
+- Log entries SHOULD include previous entry hash for chain validation
+- External audit systems MAY be used for compliance requirements
+
+Audit Content:
+- Logs MUST include timestamp, authenticated identity, action, affected categories
+- Logs SHOULD include client IP address and user agent
+- Logs MUST NOT include credentials or sensitive payload data
+- Retention policies SHOULD align with compliance requirements (90 days minimum)
+
+### 8.8 Privacy Considerations
+Personal Information:
+- User identifiers in audit logs constitute PII under GDPR/CCPA
+- Implementations SHOULD provide audit log anonymization options
+- Debug output MAY contain sensitive data; access controls are essential
+- Multi-tenant systems MUST prevent cross-tenant information leakage
+
+Data Minimization:
+- Status endpoints SHOULD NOT expose internal system details unnecessarily
+- Error messages SHOULD NOT leak implementation details
+- Discovery responses SHOULD provide only essential category information
+
+### 8.9 Multi-Tenancy Security
+Tenant Isolation:
+- Tenant ID MUST be validated against authenticated identity
+- Cross-tenant operations MUST be explicitly denied
+- Tenant isolation MUST be enforced at the storage layer
+- Global operations (admin) MUST require elevated privileges
+
+Tenant Context Injection:
+- Servers MUST validate tenant headers match authentication context
+- Clients MUST NOT be able to impersonate other tenants
+- Tenant switching MUST require re-authentication
+
+---
+
+## 9. IANA Considerations
+
+### 9.1 Well-Known URI Registration
+This document registers the following well-known URI in the "Well-Known URIs" registry as defined by RFC 8615:
+
+- URI suffix: rdcp
+- Change controller: IETF
+- Specification document: This document
+- Status: permanent
+- Related information: Used for RDCP protocol discovery. Returns JSON describing RDCP endpoints and capabilities.
+
+### 9.2 Media Type Registration
+Type name: application
+
+Subtype name: vnd.rdcp.v1+json
+
+Required parameters: None
+
+Optional parameters:
+- charset: MUST be UTF-8 if specified
+
+Encoding considerations: binary (JSON text in UTF-8)
+
+Security considerations: See Section 8 of this document
+
+Interoperability considerations: Follows JSON syntax (RFC 8259)
+
+Published specification: This document
+
+Applications that use this media type: Distributed systems using RDCP for debug control
+
+Fragment identifier considerations: None
+
+Additional information:
+- Magic number(s): None
+- File extension(s): .json
+- Macintosh file type code(s): TEXT
+
+Person & email address to contact: [Your Name] <your.email@example.com>
+
+Intended usage: COMMON
+
+Restrictions on usage: None
+
+Author: [Your Name]
+
+Change controller: IETF
+
+### 9.3 Error Code Registry
+IANA is requested to create and maintain a registry titled "RDCP Error Codes" with the following initial entries (aligned with the RDCP specification and schema):
+
+| Error Code | HTTP Status | Description | Reference |
+|------------|-------------|-------------|-----------|
+| RDCP_AUTH_REQUIRED | 401 | Authentication required | Section 3.4 |
+| RDCP_FORBIDDEN | 403 | Insufficient permissions | Section 3.4 |
+| RDCP_MALFORMED_REQUEST | 400 | Malformed request | Section 6.2 |
+| RDCP_CATEGORY_NOT_FOUND | 404 | Category does not exist | Section 6.2 |
+| RDCP_NOT_FOUND | 404 | Resource does not exist | Section 6.2 |
+| RDCP_RATE_LIMITED | 429 | Too many requests | Section 8.5 |
+| RDCP_SERVER_ERROR | 500 | Server error | Section 6.2 |
+| RDCP_UNAVAILABLE | 503 | Service temporarily unavailable | Section 6.2 |
+
+Registration Procedure: Specification Required
 
-### 8.2 Authentication
-- API keys MUST be at least 32 characters
-- Tokens MUST use industry-standard formats (JWT, OAuth2)
-- Authentication MUST use constant-time comparison
+Expert Review: Designated experts should ensure:
+1. Error codes follow naming convention: RDCP_[CONTEXT]_[CONDITION]
+2. HTTP status codes are appropriate for the error type
+3. Descriptions are clear and unambiguous
+4. No conflicts with existing codes
 
-### 8.3 Rate Limiting
-- Implementations SHOULD implement rate limiting
-- Control endpoints SHOULD limit to 60 requests/minute
-- Status endpoints MAY allow higher rates
+Change Procedure: New entries require IETF review or IESG approval
 
-### 8.4 Audit Trail
-When audit trail is enabled:
-- All control operations MUST be logged
-- Logs MUST include timestamp, operator, action, reason
-- Logs SHOULD be tamper-evident
+### 9.4 Authentication Method Registry
+IANA is requested to create and maintain a registry titled "RDCP Authentication Methods":
+
+| Method | Description | Reference |
+|--------|-------------|-----------|
+| api-key | Shared secret API key | Section 3.2 |
+| bearer | JWT or OAuth2 bearer token | Section 3.2 |
+| mtls | Mutual TLS with client certificates | Section 3.2 |
+| hybrid | Combination of mtls + bearer | Section 3.2 |
+
+Registration Procedure: Specification Required
+
+Expert Review: Designated experts should verify:
+1. Method is standards-based or widely adopted
+2. Security properties are documented
+3. Interoperability considerations are addressed
+
+### 9.5 Scope Registry
+IANA is requested to create and maintain a registry titled "RDCP Authorization Scopes":
+
+| Scope | Operations | Description | Reference |
+|-------|------------|-------------|-----------|
+| discovery | GET endpoints | Read system information | Section 3.3 |
+| status | Status/Health | Monitor system state | Section 3.3 |
+| control | POST control | Modify debug settings | Section 3.3 |
+| admin | All operations | Full access + audit trail | Section 3.3 |
+
+Registration Procedure: Specification Required
+
+Expert Review: Review should ensure scopes follow principle of least privilege
 
 ---
 
-## 9. Compatibility
+## 10. Compatibility
 
-### 9.1 Version Negotiation
+### 10.1 Version Negotiation
 
 Clients MUST include protocol version:
 ```http
@@ -483,7 +690,7 @@ Servers MUST respond with:
 Content-Type: application/vnd.rdcp.v1+json
 ```
 
-### 9.2 Backward Compatibility
+### 10.2 Backward Compatibility
 
 Future versions:
 - MUST maintain backward compatibility for 2 major versions
@@ -492,15 +699,15 @@ Future versions:
 
 ---
 
-## 10. Extensibility
+## 11. Extensibility
 
-### 10.1 Custom Categories
+### 11.1 Custom Categories
 
 Implementations MAY add custom debug categories:
 - MUST prefix with `X-` (e.g., `X-CUSTOM-FEATURE`)
 - MUST document in discovery endpoint
 
-### 10.2 Vendor Extensions
+### 11.2 Vendor Extensions
 
 Vendors MAY extend responses with additional fields:
 - MUST prefix with vendor identifier
@@ -519,7 +726,7 @@ Example:
 
 ---
 
-## 11. Compliance Levels
+## 12. Compliance Levels
 
 ### Level 1: Basic
 - Implements all required endpoints
@@ -548,12 +755,22 @@ Example:
 
 ---
 
-## 12. References
+## 13. References
 
+### 13.1 Normative References
 - RFC 2119: Key words for use in RFCs
-- RFC 7231: HTTP/1.1 Semantics and Content
-- RFC 7807: Problem Details for HTTP APIs
+- RFC 8174: Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words
 - RFC 8259: JSON Data Interchange Format
+- RFC 8615: Well-Known Uniform Resource Identifiers (URIs)
+- RFC 3339: Date and Time on the Internet: Timestamps
+- RFC 9110: HTTP Semantics
+- RFC 9112: HTTP/1.1
+- RFC 8446: The Transport Layer Security (TLS) Protocol Version 1.3
+
+### 13.2 Informative References
+- RFC 7807: Problem Details for HTTP APIs
+- RFC 7519: JSON Web Token (JWT)
+- RFC 6749: The OAuth 2.0 Authorization Framework
 
 ---
 
@@ -626,3 +843,34 @@ Use context-specific types:
 ---
 
 *End of RDCP Protocol Specification v1.0*
+
+---
+
+## Appendix D: Authors' Addresses
+
+[Your Name]
+[Your Organization]
+Email: [your.email@example.com]
+URI: https://your-website.com
+
+---
+
+## Appendix E: Acknowledgments
+
+The authors would like to thank contributors and reviewers for their valuable feedback and contributions to this specification.
+
+---
+
+## Status of This Memo (Template)
+
+This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
+
+Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
+
+---
+
+## Copyright Notice (Template)
+
+Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.
+
+This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.
diff --git a/rfc-submission/rdcp-spec.xml b/rfc-submission/rdcp-spec.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<rfc xmlns:xi="http://www.w3.org/2001/XInclude" version="3" ipr="trust200902" submissionType="IETF" category="exp" consensus="false" docName="draft-<author>-rdcp-00">
+<rfc xmlns:xi="http://www.w3.org/2001/XInclude" version="3" ipr="trust200902" submissionType="IETF" category="exp" consensus="false" docName="draft-rdcp-00">
   <front>
     <title abbrev="RDCP v1.0">Runtime Debug Control Protocol (RDCP) v1.0</title>
-    <author fullname="TBD" initials="T." surname="BD">
+<author fullname="TBD Author" initials="T" surname="Author">
       <organization>MojoAtomic</organization>
       <address>
         <email>TBD@example.com</email>