StarPunk/docs/decisions/ADR-022-indieauth-token-exchange-compliance.md

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
• IndieAuth W3C TR Section 6.3.1
• PKCE RFC 7636 (not part of IndieAuth spec)