StarPunk/docs/decisions/ADR-036-indieauth-token-verification-method.md

ADR-036: IndieAuth Token Verification Method Diagnosis

Status

Accepted

Context

StarPunk is experiencing HTTP 405 Method Not Allowed errors when verifying tokens with the external IndieAuth provider (gondulf.thesatelliteoflove.com). The user questioned "why are we making GET requests to these endpoints?"

Error from logs:

[2025-11-25 03:29:50] WARNING: Token verification failed:
  Verification failed: Unexpected response: HTTP 405

Investigation Results

What the IndieAuth Spec Says

According to the W3C IndieAuth specification (Section 6.3.4 - Token Verification):

• Token verification MUST use a GET request to the token endpoint
• The request must include an Authorization header with Bearer token format
• This is explicitly different from token issuance, which uses POST

What Our Code Does

Our implementation in starpunk/auth_external.py (line 425):

• Correctly uses GET for token verification
• Correctly sends Authorization: Bearer header
• Correctly follows the IndieAuth specification

Why the 405 Error Occurs

HTTP 405 Method Not Allowed means the server doesn't support the HTTP method (GET) for the requested resource. This indicates that the gondulf IndieAuth provider is not implementing the IndieAuth specification correctly.

Decision

Our implementation is correct. We are making GET requests because:

1. The IndieAuth spec explicitly requires GET for token verification
2. This distinguishes verification (GET) from token issuance (POST)
3. This is a standard pattern in OAuth-like protocols

Rationale

Why GET for Verification?

The IndieAuth spec uses different HTTP methods for different operations:

• POST for state-changing operations (issuing tokens, revoking tokens)
• GET for read-only operations (verifying tokens)

This follows RESTful principles where:

• GET is idempotent and safe (doesn't modify server state)
• POST creates or modifies resources

The Problem

The gondulf IndieAuth provider appears to only support POST on its token endpoint, not implementing the full IndieAuth specification which requires both:

• POST for token issuance (Section 6.3)
• GET for token verification (Section 6.3.4)

Consequences

Immediate Impact

• StarPunk cannot verify tokens with gondulf.thesatelliteoflove.com
• The provider needs to be fixed to support GET requests for verification
• Our code is correct and should NOT be changed

Potential Solutions

1. Provider Fix (Recommended): The gondulf IndieAuth provider should implement GET support for token verification per spec
2. Provider Switch: Use a compliant IndieAuth provider that fully implements the specification
3. Non-Compliant Mode (Not Recommended): Add a workaround to use POST for verification with non-compliant providers

Alternatives Considered

Alternative 1: Use POST for Verification

• Rejected: Violates IndieAuth specification
• Would make StarPunk non-compliant
• Would create confusion about proper IndieAuth implementation

Alternative 2: Support Both GET and POST

• Rejected: Adds complexity without benefit
• The spec is clear: GET is required
• Supporting non-standard behavior encourages poor implementations

Alternative 3: Document Provider Requirements

• Accepted as Additional Action: We should clearly document that StarPunk requires IndieAuth providers that fully implement the W3C specification

Technical Details

Correct Token Verification Flow

Client → GET /token
         Authorization: Bearer {token}

Server → 200 OK
         {
           "me": "https://user.example.net/",
           "client_id": "https://app.example.com/",
           "scope": "create update"
         }

What Gondulf Is Doing Wrong

Client → GET /token
         Authorization: Bearer {token}

Server → 405 Method Not Allowed
         (Server only accepts POST)

References

• W3C IndieAuth Specification - Token Verification
• W3C IndieAuth Specification - Token Endpoint
• StarPunk Implementation: /home/phil/Projects/starpunk/starpunk/auth_external.py

Recommendation

1. Contact the gondulf IndieAuth provider maintainer and inform them their implementation is non-compliant
2. Provide them with the W3C spec reference showing GET is required for verification
3. Do NOT modify StarPunk's code - it is correct
4. Consider adding a note in our documentation about provider compliance requirements