# ADR-022: IndieAuth Token Exchange Compliance

## Status
Accepted

## Context
StarPunk's IndieAuth implementation is failing to authenticate with certain providers (specifically gondulf.thesatelliteoflove.com) during the token exchange phase. The provider is rejecting our token exchange requests with a "missing grant_type" error.

Our current implementation sends:
- `code`
- `client_id`
- `redirect_uri`
- `code_verifier` (for PKCE)

But does NOT include `grant_type=authorization_code`.

## Decision
StarPunk MUST include `grant_type=authorization_code` in all token exchange requests to be compliant with both OAuth 2.0 RFC 6749 and IndieAuth specifications.

## Rationale

### OAuth 2.0 RFC 6749 Compliance
RFC 6749 Section 4.1.3 explicitly states that `grant_type` is a REQUIRED parameter with the value MUST be set to "authorization_code" for the authorization code grant flow.

### IndieAuth Specification
While the IndieAuth specification (W3C TR) doesn't use explicit RFC 2119 language (MUST/REQUIRED) for the grant_type parameter, it:
1. Lists `grant_type=authorization_code` as part of the token request parameters in Section 6.3.1
2. Shows it in all examples (Example 12)
3. States that IndieAuth "builds upon the OAuth 2.0 [RFC6749] Framework"

Since IndieAuth builds on OAuth 2.0, and OAuth 2.0 requires this parameter, IndieAuth implementations should include it.

### Provider Compliance
The provider (gondulf.thesatelliteoflove.com) is **correctly following the specifications** by requiring the `grant_type` parameter.

## Consequences

### Positive
- Full compliance with OAuth 2.0 RFC 6749
- Compatibility with all spec-compliant IndieAuth providers
- Clear, standard-compliant token exchange requests

### Negative
- Requires immediate code change to add the missing parameter
- May reveal other non-compliant providers that don't check for this parameter

## Implementation Requirements

The token exchange request MUST include these parameters:
```
grant_type=authorization_code  # REQUIRED by OAuth 2.0
code={authorization_code}      # REQUIRED
client_id={client_url}         # REQUIRED
redirect_uri={redirect_url}    # REQUIRED if used in initial request
me={user_profile_url}          # REQUIRED by IndieAuth (extension to OAuth)
```

### Note on PKCE
The `code_verifier` parameter currently being sent is NOT part of the IndieAuth specification. IndieAuth does not mention PKCE (RFC 7636) support. However:
- Including it shouldn't break compliant providers (they should ignore unknown parameters)
- It provides additional security for public clients
- Consider making PKCE optional or detecting provider support

## Alternatives Considered

### Alternative 1: Argue for Optional grant_type
**Rejected**: While IndieAuth could theoretically make grant_type optional since there's only one grant type, this would break compatibility with OAuth 2.0 compliant libraries and providers.

### Alternative 2: Provider-specific workarounds
**Rejected**: Creating provider-specific code paths would violate the principle of standards compliance and create maintenance burden.

## Recommendation

**Immediate Action Required**:
1. Add `grant_type=authorization_code` to all token exchange requests
2. Maintain the existing parameters
3. Consider making PKCE optional or auto-detecting provider support

**StarPunk is at fault** - the implementation is missing a required OAuth 2.0 parameter that IndieAuth inherits.

## References
- [OAuth 2.0 RFC 6749 Section 4.1.3](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1.3)
- [IndieAuth W3C TR Section 6.3.1](https://www.w3.org/TR/indieauth/#token-request)
- [PKCE RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636) (not part of IndieAuth spec)