StarPunk/docs/architecture/indieauth-token-verification-diagnosis.md

IndieAuth Token Verification Diagnosis

Executive Summary

The Problem: StarPunk is receiving HTTP 405 Method Not Allowed when verifying tokens with gondulf.thesatelliteoflove.com

The Cause: The gondulf IndieAuth provider does not implement the W3C IndieAuth specification correctly

The Solution: The provider needs to be fixed - StarPunk's implementation is correct

Why We Make GET Requests

You asked: "Why are we making GET requests to these endpoints?"

Answer: Because the W3C IndieAuth specification explicitly requires GET requests for token verification.

The IndieAuth Token Endpoint Dual Purpose

The token endpoint serves two distinct purposes with different HTTP methods:

1. Token Issuance (POST)

   • Client sends authorization code
   • Server returns new access token
   • State-changing operation

2. Token Verification (GET)

   • Resource server sends token in Authorization header
   • Token endpoint returns token metadata
   • Read-only operation

Why This Design Makes Sense

The specification follows RESTful principles:

• GET = Read data (verify a token exists and is valid)
• POST = Create/modify data (issue a new token)

This is similar to how you might:

• GET /users/123 to read user information
• POST /users to create a new user

The Specific Problem

What Should Happen

StarPunk → GET https://gondulf.thesatelliteoflove.com/token
           Authorization: Bearer abc123...

Gondulf  → 200 OK
           {
             "me": "https://thesatelliteoflove.com",
             "client_id": "https://starpunk.example",
             "scope": "create"
           }

What Actually Happens

StarPunk → GET https://gondulf.thesatelliteoflove.com/token
           Authorization: Bearer abc123...

Gondulf  → 405 Method Not Allowed
           (Server doesn't support GET on /token)

Code Analysis

Our Implementation (Correct)

From /home/phil/Projects/starpunk/starpunk/auth_external.py line 425:

def _verify_with_endpoint(endpoint: str, token: str) -> Dict[str, Any]:
    """
    Verify token with the discovered token endpoint

    Makes GET request to endpoint with Authorization header.
    """
    headers = {
        'Authorization': f'Bearer {token}',
        'Accept': 'application/json',
    }

    response = httpx.get(  # ← Correct: Using GET
        endpoint,
        headers=headers,
        timeout=VERIFICATION_TIMEOUT,
        follow_redirects=True,
    )

IndieAuth Spec Reference

From W3C IndieAuth Section 6.3.4:

"If an external endpoint needs to verify that an access token is valid, it MUST make a GET request to the token endpoint containing an HTTP Authorization header with the Bearer Token according to RFC6750."

(Emphasis added)

Why the Provider is Wrong

The gondulf IndieAuth provider appears to:

1. Only implement POST for token issuance
2. Not implement GET for token verification
3. Return 405 for any GET requests to /token

This is only a partial implementation of IndieAuth.

Impact Analysis

What This Breaks

• StarPunk cannot authenticate users through gondulf
• Any other spec-compliant Micropub client would also fail
• The provider is not truly IndieAuth compliant

What This Doesn't Break

• Our code is correct
• We can work with any compliant IndieAuth provider
• The architecture is sound

Solutions

Option 1: Fix the Provider (Recommended)

The gondulf provider needs to:

1. Add GET method support to /token endpoint
2. Verify bearer tokens from Authorization header
3. Return appropriate JSON response

Option 2: Use a Different Provider

Known compliant providers:

• IndieAuth.com
• IndieLogin.com
• Self-hosted IndieAuth servers that implement full spec

Option 3: Work Around (Not Recommended)

We could add a non-compliant mode, but this would:

• Violate the specification
• Encourage bad implementations
• Add unnecessary complexity
• Create security concerns

Summary

Your Question: "Why are we making GET requests to these endpoints?"

Answer: Because that's what the IndieAuth specification requires for token verification. We're doing it right. The gondulf provider is doing it wrong.

Action Required: The gondulf IndieAuth provider needs to implement GET support on their token endpoint to be IndieAuth compliant.

References

1. W3C IndieAuth - Token Verification
2. RFC 6750 - OAuth 2.0 Bearer Token Usage
3. StarPunk Implementation

Contact Information for Provider

If you need to report this to the gondulf provider:

"Your IndieAuth token endpoint at https://gondulf.thesatelliteoflove.com/token returns HTTP 405 Method Not Allowed for GET requests. Per the W3C IndieAuth specification Section 6.3.4, the token endpoint MUST support GET requests with Bearer authentication for token verification. Currently it appears to only support POST for token issuance."