Gondulf/docs/decisions/ADR-012-client-id-validation-compliance.md

ADR-012: Client ID Validation Compliance

Date: 2025-11-24

Status

Accepted

Context

During pre-release compliance review, we discovered that Gondulf's client_id validation is not fully compliant with the W3C IndieAuth specification Section 3.2. The current implementation in normalize_client_id() only performs basic HTTPS validation and port normalization, missing several critical requirements:

Non-compliance issues identified:

1. Rejects HTTP URLs even for localhost (spec allows HTTP for loopback addresses)
2. Accepts fragments in URLs (spec explicitly forbids fragments)
3. Accepts username/password in URLs (spec forbids user info components)
4. Accepts non-loopback IP addresses (spec only allows 127.0.0.1 and [::1])
5. Accepts path traversal segments (. and ..)
6. Does not normalize hostnames to lowercase
7. Does not ensure path component exists

These violations could lead to:

• Legitimate local development clients being rejected (HTTP localhost)
• Security vulnerabilities (credential exposure, path traversal)
• Interoperability issues with compliant IndieAuth clients
• Confusion about client identity (fragments, case sensitivity)

Decision

We will implement complete W3C IndieAuth specification compliance for client_id validation by:

1. Separating validation from normalization: Create a new validate_client_id() function that performs all specification checks, separate from the normalization logic.

2. Supporting HTTP for localhost: Allow HTTP scheme for localhost, 127.0.0.1, and [::1] to support local development while maintaining HTTPS requirement for production domains.

3. Rejecting non-compliant URLs: Explicitly reject URLs with fragments, credentials, non-loopback IPs, and path traversal segments.

4. Providing specific error messages: Return detailed error messages for each validation failure to help developers understand what needs to be fixed.

5. Maintaining backward compatibility: The stricter validation only rejects URLs that were already non-compliant with the specification. Valid client_ids continue to work.

Consequences

Positive Consequences

1. Full specification compliance: Gondulf will correctly handle all client_ids as defined by W3C IndieAuth specification.

2. Improved security: Rejecting credentials, path traversal, and non-loopback IPs prevents potential security vulnerabilities.

3. Better developer experience: Clear error messages help developers quickly fix client_id issues.

4. Local development support: HTTP localhost support enables easier local testing and development.

5. Interoperability: Any compliant IndieAuth client will work with Gondulf.

Negative Consequences

1. Breaking change for non-compliant clients: Clients using non-compliant client_ids (e.g., with fragments or credentials) will be rejected. However, these were already violating the specification.

2. Slightly more complex validation: The validation logic is more comprehensive, but this complexity is contained within well-documented functions.

3. Additional testing burden: More test cases are needed to cover all validation rules.

Implementation Notes

• The validation logic is implemented as a pure function with no side effects
• Normalization happens after validation to ensure only valid client_ids are normalized
• Both authorization and token endpoints use the same validation logic
• Error messages follow OAuth 2.0 error response format

This decision ensures Gondulf is a fully compliant IndieAuth server that can interoperate with any specification-compliant client while maintaining security and providing a good developer experience.