# 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.