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](https://www.w3.org/TR/indieauth/#token-verification)
- [W3C IndieAuth Specification - Token Endpoint](https://www.w3.org/TR/indieauth/#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