fix: Use authorization endpoint for IndieAuth code verification (v0.9.4)

IndieAuth authentication-only flows should redeem the code at the
authorization endpoint, not the token endpoint. The token endpoint
is only for authorization flows that need access tokens.

- Remove grant_type parameter (only needed for token flows)
- Change endpoint from /token to /authorize
- Update debug logging to reflect code verification flow

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

CHANGELOG.md

@@ -7,6 +7,55 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.4] - 2025-11-22
+
+### Fixed
+- **IndieAuth authentication endpoint correction**: Changed code redemption from token endpoint to authorization endpoint
+  - Per IndieAuth spec: authentication-only flows use `/authorize`, not `/token`
+  - StarPunk only needs identity verification, not access tokens
+  - Removed unnecessary `grant_type` parameter (only needed for token endpoint)
+  - Updated debug logging to reflect "code verification" terminology
+  - Fixes authentication with IndieLogin.com and spec-compliant providers
+
+### Changed
+- Code redemption now POSTs to `/authorize` endpoint instead of `/token`
+- Log messages updated from "token exchange" to "code verification"
+
+## [0.9.3] - 2025-11-22
+
+### Fixed
+- **IndieAuth token exchange missing grant_type**: Added required `grant_type=authorization_code` parameter to token exchange request
+  - OAuth 2.0 spec requires this parameter for authorization code flow
+  - Some IndieAuth providers reject token exchange without this parameter
+  - Fixes authentication failures with spec-compliant IndieAuth providers
+
+## [0.9.2] - 2025-11-22
+
+### Fixed
+- **IndieAuth callback 404 error**: Fixed auth blueprint URL prefix mismatch
+  - Auth blueprint was using `/admin` prefix but redirect_uri used `/auth/callback`
+  - Changed blueprint prefix from `/admin` to `/auth` as documented in ADR-022
+  - Auth routes now correctly at `/auth/login`, `/auth/callback`, `/auth/logout`
+  - Admin dashboard routes remain at `/admin/*` (unchanged)
+
+### Changed
+- Updated test expectations to use new `/auth/*` URL patterns
+
+## [0.9.1] - 2025-11-19
+
+### Fixed
+- **IndieAuth client_id trailing slash**: Added automatic trailing slash normalization to SITE_URL
+  - IndieLogin.com spec requires client_id URLs to have trailing slash for root domains
+  - Fixes "client_id is not registered" authentication errors
+  - Normalizes https://example.com to https://example.com/
+- **Enhanced debug logging**: Added detailed httpx request/response logging for token exchange
+  - Shows exact HTTP method, URL, headers, and body being sent to IndieLogin.com
+  - Helps troubleshoot authentication issues with full visibility
+  - All sensitive data (tokens, verifiers) automatically redacted
+
+### Changed
+- SITE_URL configuration now automatically adds trailing slash if missing
+
 ## [0.9.0] - 2025-11-19
 
 ### Added

docs/decisions/ADR-022-auth-route-prefix-fix.md

@@ -0,0 +1,178 @@
+# ADR-022: Fix IndieAuth Callback Route Mismatch
+
+## Status
+Proposed
+
+## Context
+We have discovered a critical routing mismatch in our IndieAuth implementation that causes a 404 error when IndieAuth providers redirect back to our application.
+
+### The Problem
+The auth blueprint is currently registered with `url_prefix="/admin"` in `/starpunk/routes/auth.py` line 30:
+```python
+bp = Blueprint("auth", __name__, url_prefix="/admin")
+```
+
+This means all auth routes are actually served under `/admin`:
+- `/admin/login` - Login form
+- `/admin/callback` - OAuth callback endpoint
+- `/admin/logout` - Logout endpoint
+
+However, in `/starpunk/auth.py` lines 325 and 414, the redirect_uri sent to IndieAuth providers is:
+```python
+redirect_uri = f"{current_app.config['SITE_URL']}auth/callback"
+```
+
+This mismatch causes IndieAuth providers to redirect users to `/auth/callback`, which doesn't exist, resulting in a 404 error.
+
+### Current Route Structure
+- **Auth Blueprint** (with `/admin` prefix):
+  - `/admin/login` - Login form
+  - `/admin/callback` - OAuth callback
+  - `/admin/logout` - Logout endpoint
+- **Admin Blueprint** (with `/admin` prefix):
+  - `/admin/` - Dashboard
+  - `/admin/new` - Create note
+  - `/admin/edit/<id>` - Edit note
+  - `/admin/delete/<id>` - Delete note
+
+## Decision
+Change the auth blueprint URL prefix from `/admin` to `/auth` to match the redirect_uri being sent to IndieAuth providers.
+
+## Rationale
+
+### 1. Separation of Concerns
+Authentication routes (`/auth/*`) should be semantically separate from administration routes (`/admin/*`). This creates a cleaner architecture where:
+- `/auth/*` handles authentication flows (login, callback, logout)
+- `/admin/*` handles protected administrative functions (dashboard, CRUD operations)
+
+### 2. Standards Compliance
+IndieAuth and OAuth2 conventions typically use `/auth/callback` for OAuth callbacks:
+- Most OAuth documentation and examples use this pattern
+- IndieAuth implementations commonly expect callbacks at `/auth/callback`
+- Follows RESTful URL design principles
+
+### 3. Security Benefits
+Clear separation provides:
+- Easier application of different security policies (rate limiting on auth vs admin)
+- Clearer audit trails and access logs
+- Reduced cognitive load when reviewing security configurations
+- Better principle of least privilege implementation
+
+### 4. Minimal Impact
+Analysis of the codebase shows:
+- No hardcoded URLs to `/admin/login` in external-facing documentation
+- All internal redirects use `url_for('auth.login_form')` which will automatically adjust
+- Templates use named routes: `url_for('auth.login_initiate')`, `url_for('auth.logout')`
+- No stored auth_state data is tied to the URL path
+
+### 5. Future Flexibility
+If we later need public authentication for other features:
+- API token generation could live at `/auth/tokens`
+- OAuth provider functionality could use `/auth/authorize`
+- WebAuthn endpoints could use `/auth/webauthn`
+- All auth-related functionality stays organized under `/auth`
+
+## Consequences
+
+### Positive
+- **Fixes the immediate bug**: IndieAuth callbacks will work correctly
+- **Cleaner architecture**: Proper separation between auth and admin concerns
+- **Standards alignment**: Matches common OAuth/IndieAuth patterns
+- **No breaking changes**: All internal routes use named endpoints
+- **Better organization**: More intuitive URL structure
+
+### Negative
+- **Documentation updates needed**: Must update docs showing `/admin/login` paths
+- **Potential user confusion**: Users who bookmarked `/admin/login` will get 404
+  - Mitigation: Could add a redirect from `/admin/login` to `/auth/login` for transition period
+
+### Migration Requirements
+- No database migrations required
+- No session invalidation needed
+- No configuration changes needed
+- Simply update the blueprint registration
+
+## Alternatives Considered
+
+### Alternative 1: Change redirect_uri to `/admin/callback`
+**Rejected because:**
+- Mixes authentication concerns with administration in URL structure
+- Goes against common OAuth/IndieAuth URL patterns
+- Less intuitive - callbacks aren't "admin" functions
+- Requires changes in two places in `auth.py` (lines 325 and 414)
+
+### Alternative 2: Create a separate `/auth` blueprint just for callback
+**Rejected because:**
+- Splits related authentication logic across multiple blueprints
+- More complex routing configuration
+- Harder to maintain - auth logic spread across files
+- Violates single responsibility principle at module level
+
+### Alternative 3: Use root-level routes (`/login`, `/callback`, `/logout`)
+**Rejected because:**
+- Pollutes the root namespace
+- No logical grouping of related routes
+- Harder to apply auth-specific middleware
+- Less scalable as application grows
+
+### Alternative 4: Keep current structure and add redirect
+**Rejected because:**
+- Doesn't fix the underlying architectural issue
+- Adds unnecessary HTTP redirect overhead
+- Makes debugging more complex
+- Band-aid solution rather than proper fix
+
+## Implementation
+
+### Required Change
+Update line 30 in `/home/phil/Projects/starpunk/starpunk/routes/auth.py`:
+```python
+# From:
+bp = Blueprint("auth", __name__, url_prefix="/admin")
+
+# To:
+bp = Blueprint("auth", __name__, url_prefix="/auth")
+```
+
+### Results
+This single change will:
+- Make the callback available at `/auth/callback` (matching the redirect_uri)
+- Move login to `/auth/login`
+- Move logout to `/auth/logout`
+- All template references using `url_for()` will automatically resolve correctly
+
+### Optional Transition Support
+If desired, add temporary redirects in `starpunk/routes/admin.py`:
+```python
+@bp.route("/login")
+def old_login_redirect():
+    """Temporary redirect for bookmarks"""
+    return redirect(url_for("auth.login_form"), 301)
+```
+
+### Documentation Updates Required
+Files to update:
+- `/home/phil/Projects/starpunk/TECHNOLOGY-STACK-SUMMARY.md` - Update route table
+- `/home/phil/Projects/starpunk/docs/design/phase-4-web-interface.md` - Update route documentation
+- `/home/phil/Projects/starpunk/docs/designs/phase-5-quick-reference.md` - Update admin access instructions
+
+## Testing Verification
+After implementation:
+1. Verify `/auth/login` displays login form
+2. Verify `/auth/callback` accepts IndieAuth redirects
+3. Verify `/auth/logout` destroys session
+4. Verify all admin routes still require authentication
+5. Test full IndieAuth flow with real provider
+
+## References
+- [IndieAuth Specification](https://indieauth.spec.indieweb.org/) - Section on redirect URIs
+- [OAuth 2.0 RFC 6749](https://tools.ietf.org/html/rfc6749) - Section 3.1.2 on redirection endpoints
+- [RESTful API Design](https://restfulapi.net/resource-naming/) - URL naming conventions
+- Current implementation: `/home/phil/Projects/starpunk/starpunk/routes/auth.py`, `/home/phil/Projects/starpunk/starpunk/auth.py`
+
+---
+
+**Document Version**: 1.0
+**Created**: 2025-11-22
+**Author**: StarPunk Architecture Team (agent-architect)
+**Review Required By**: agent-developer before implementation

docs/decisions/ADR-022-indieauth-authentication-endpoint-correction.md

@@ -0,0 +1,188 @@
+# ADR-022: IndieAuth Authentication Endpoint Correction
+
+## Status
+Accepted
+
+## Context
+
+StarPunk is encountering authentication failures with certain IndieAuth providers (specifically gondulf.thesatelliteoflove.com). After investigation, we discovered that StarPunk is incorrectly using the **token endpoint** for authentication-only flows, when it should be using the **authorization endpoint**.
+
+### The Problem
+
+When attempting to authenticate with gondulf.thesatelliteoflove.com, the provider returns:
+```json
+{
+  "error": "invalid_grant",
+  "error_description": "Authorization code must be redeemed at the authorization endpoint"
+}
+```
+
+StarPunk is currently sending authentication code redemption requests to `/token` when it should be sending them to the authorization endpoint for authentication-only flows.
+
+### IndieAuth Specification Analysis
+
+According to the W3C IndieAuth specification (https://www.w3.org/TR/indieauth/):
+
+1. **Authentication-only flows** (Section 5.4):
+   - Used when the client only needs to verify user identity
+   - Code redemption happens at the **authorization endpoint**
+   - No `grant_type` parameter is used
+   - Response contains only `{"me": "user-url"}`
+
+2. **Authorization flows** (Section 6.3):
+   - Used when the client needs an access token for API access
+   - Code redemption happens at the **token endpoint**
+   - Requires `grant_type=authorization_code` parameter
+   - Response contains access token and user identity
+
+### Current StarPunk Implementation
+
+StarPunk's current code in `/home/phil/Projects/starpunk/starpunk/auth.py` (lines 410-419):
+
+```python
+token_exchange_data = {
+    "grant_type": "authorization_code",  # WRONG for authentication-only
+    "code": code,
+    "client_id": current_app.config["SITE_URL"],
+    "redirect_uri": f"{current_app.config['SITE_URL']}auth/callback",
+    "code_verifier": code_verifier,  # PKCE verification
+}
+
+token_url = f"{current_app.config['INDIELOGIN_URL']}/token"  # WRONG endpoint
+```
+
+This implementation has two errors:
+1. Uses `/token` endpoint instead of authorization endpoint
+2. Includes `grant_type` parameter which should not be present for authentication-only flows
+
+## Decision
+
+StarPunk must correct its IndieAuth authentication implementation to comply with the specification:
+
+1. **Use the authorization endpoint** for code redemption in authentication-only flows
+2. **Remove the `grant_type` parameter** from authentication requests
+3. **Keep PKCE parameters** (`code_verifier`) as they are still required
+
+## Rationale
+
+### Why This Matters
+
+1. **Standards Compliance**: The IndieAuth specification clearly distinguishes between authentication and authorization flows
+2. **Provider Compatibility**: Some providers (like gondulf) strictly enforce the specification
+3. **Correct Semantics**: StarPunk only needs to verify admin identity, not obtain an access token
+
+### Authentication vs Authorization
+
+StarPunk's admin login is an **authentication-only** use case:
+- We only need to verify the admin's identity (`me` URL)
+- We don't need an access token to access external resources
+- We create our own session after successful authentication
+
+This is fundamentally different from Micropub client authorization where:
+- External clients need access tokens
+- Tokens are used to authorize API access
+- The token endpoint is the correct choice
+
+## Implementation
+
+### Required Changes
+
+In `/home/phil/Projects/starpunk/starpunk/auth.py`, the `handle_callback` function must be updated:
+
+```python
+def handle_callback(code: str, state: str, iss: Optional[str] = None) -> Optional[str]:
+    # ... existing state verification code ...
+
+    # Prepare authentication request (NOT token exchange)
+    auth_data = {
+        # NO grant_type parameter for authentication-only flows
+        "code": code,
+        "client_id": current_app.config["SITE_URL"],
+        "redirect_uri": f"{current_app.config['SITE_URL']}auth/callback",
+        "code_verifier": code_verifier,  # PKCE verification still required
+    }
+
+    # Use authorization endpoint (NOT token endpoint)
+    # The same endpoint used for the initial authorization request
+    auth_url = f"{current_app.config['INDIELOGIN_URL']}/auth"  # or /authorize
+
+    # Exchange code for identity (authentication-only)
+    response = httpx.post(
+        auth_url,
+        data=auth_data,
+        timeout=10.0,
+    )
+
+    # Response will be: {"me": "https://user.example.com"}
+    # NOT an access token response
+```
+
+### Endpoint Discovery Consideration
+
+IndieAuth providers may use different paths for their authorization endpoint:
+- IndieLogin.com uses `/auth`
+- Some providers use `/authorize`
+- The gondulf provider appears to use its root domain as the authorization endpoint
+
+The correct approach is to:
+1. Discover the authorization endpoint from the provider's metadata
+2. Use the same endpoint for both authorization initiation and code redemption
+3. Store the discovered endpoint during the initial authorization request
+
+## Consequences
+
+### Positive
+- **Specification Compliance**: Correctly implements IndieAuth authentication flow
+- **Provider Compatibility**: Works with strict IndieAuth implementations
+- **Semantic Correctness**: Uses the right flow for the use case
+
+### Negative
+- **Breaking Change**: May affect compatibility with providers that accept both endpoints
+- **Testing Required**: Need to verify with multiple IndieAuth providers
+
+### Migration Impact
+- Existing sessions remain valid (no database changes)
+- Only affects new login attempts
+- Should be transparent to users
+
+## Testing Strategy
+
+Test with multiple IndieAuth providers:
+1. **IndieLogin.com** - Current provider (should continue working)
+2. **gondulf.thesatelliteoflove.com** - Strict implementation
+3. **tokens.indieauth.com** - Token-only endpoint (should fail for auth)
+4. **Self-hosted implementations** - Various compliance levels
+
+## Alternatives Considered
+
+### Alternative 1: Support Both Endpoints
+Attempt token endpoint first, fall back to authorization endpoint on failure.
+- **Pros**: Maximum compatibility
+- **Cons**: Not specification-compliant, adds complexity
+- **Verdict**: Rejected - violates standards
+
+### Alternative 2: Make Endpoint Configurable
+Allow admin to configure which endpoint to use.
+- **Pros**: Flexible for different providers
+- **Cons**: Confusing for users, not needed if we follow spec
+- **Verdict**: Rejected - specification is clear
+
+### Alternative 3: Always Use Token Endpoint
+Continue current implementation, document incompatibility.
+- **Pros**: No code changes needed
+- **Cons**: Violates specification, limits provider choice
+- **Verdict**: Rejected - incorrect implementation
+
+## References
+
+- [IndieAuth Specification Section 5.4](https://www.w3.org/TR/indieauth/#authentication-response): Authorization Code Verification for authentication flows
+- [IndieAuth Specification Section 6.3](https://www.w3.org/TR/indieauth/#token-response): Token Endpoint for authorization flows
+- [IndieAuth Authentication vs Authorization](https://indieweb.org/IndieAuth#Authentication_vs_Authorization): Community documentation
+- [ADR-021: IndieAuth Provider Strategy](/home/phil/Projects/starpunk/docs/decisions/ADR-021-indieauth-provider-strategy.md): Related architectural decision
+
+---
+
+**Document Version**: 1.0
+**Created**: 2025-11-22
+**Author**: StarPunk Architecture Team
+**Status**: Accepted

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

@@ -0,0 +1,84 @@
+# 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)

docs/reports/2025-11-19-migration-implementation-quick-reference.md

@@ -0,0 +1,104 @@
+# Migration System - Quick Reference Card
+
+**TL;DR**: Add fresh database detection to `migrations.py` to solve chicken-and-egg problem.
+
+## The Problem
+
+- `SCHEMA_SQL` includes `code_verifier` column (line 60, database.py)
+- Migration 001 tries to add same column
+- Fresh databases fail: "column already exists"
+
+## The Solution
+
+**SCHEMA_SQL = Target State** (complete current schema)
+- Fresh installs: Execute SCHEMA_SQL, skip migrations (already at target)
+- Existing installs: Run migrations to reach target
+
+## Code Changes Required
+
+### 1. Add to `migrations.py` (before `run_migrations`):
+
+```python
+def is_schema_current(conn):
+    """Check if database schema matches current SCHEMA_SQL"""
+    try:
+        cursor = conn.execute("PRAGMA table_info(auth_state)")
+        columns = [row[1] for row in cursor.fetchall()]
+        return 'code_verifier' in columns
+    except sqlite3.OperationalError:
+        return False
+```
+
+### 2. Modify `run_migrations()` in `migrations.py`:
+
+After `create_migrations_table(conn)`, before applying migrations, add:
+
+```python
+# Check if this is a fresh database
+cursor = conn.execute("SELECT COUNT(*) FROM schema_migrations")
+migration_count = cursor.fetchone()[0]
+
+# Discover migration files
+migration_files = discover_migration_files(migrations_dir)
+
+# Fresh database detection
+if migration_count == 0 and is_schema_current(conn):
+    # Mark all migrations as applied (schema already current)
+    for migration_name, _ in migration_files:
+        conn.execute(
+            "INSERT INTO schema_migrations (migration_name) VALUES (?)",
+            (migration_name,)
+        )
+    conn.commit()
+    logger.info(f"Fresh database: marked {len(migration_files)} migrations as applied")
+    return
+```
+
+### 3. Optional Helpers (add to `migrations.py` for future use):
+
+```python
+def table_exists(conn, table_name):
+    cursor = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+        (table_name,)
+    )
+    return cursor.fetchone() is not None
+
+def column_exists(conn, table_name, column_name):
+    try:
+        cursor = conn.execute(f"PRAGMA table_info({table_name})")
+        columns = [row[1] for row in cursor.fetchall()]
+        return column_name in columns
+    except sqlite3.OperationalError:
+        return False
+```
+
+## Test It
+
+```bash
+# Test 1: Fresh database
+rm data/starpunk.db && uv run flask --app app.py run
+# Expected: "Fresh database: marked 1 migrations as applied"
+
+# Test 2: Legacy database (before PKCE)
+# Create old schema, run app
+# Expected: "Applied migration: 001_add_code_verifier..."
+```
+
+## All Other Questions Answered
+
+- **Q2**: schema_migrations only in migrations.py ✓ (already correct)
+- **Q3**: Accept non-idempotent SQL, rely on tracking ✓ (already works)
+- **Q4**: Flexible filename validation ✓ (already implemented)
+- **Q5**: Automatic transition via Q1 solution ✓
+- **Q6**: Helpers provided for advanced use ✓ (see above)
+- **Q7**: SCHEMA_SQL is target state ✓ (no changes needed)
+
+## Full Details
+
+See: `/home/phil/Projects/starpunk/docs/reports/2025-11-19-migration-system-implementation-guidance.md`
+
+## Architecture Reference
+
+See: `/home/phil/Projects/starpunk/docs/decisions/ADR-020-automatic-database-migrations.md`
+(New section: "Developer Questions & Architectural Responses")

docs/reports/2025-11-19-migration-system-implementation-guidance.md

@@ -0,0 +1,345 @@
+# Migration System Implementation Guidance
+
+**Date**: 2025-11-19
+**Architect**: StarPunk Architect
+**Developer**: StarPunk Developer
+**Status**: Ready for Implementation
+
+## Executive Summary
+
+All 7 critical questions have been answered with decisive architectural decisions. The implementation is straightforward and production-ready.
+
+## Critical Decisions Summary
+
+| # | Question | Decision | Action Required |
+|---|----------|----------|-----------------|
+| **1** | Chicken-and-egg problem | Fresh database detection | Add `is_schema_current()` to migrations.py |
+| **2** | schema_migrations location | Only in migrations.py | No changes needed (already correct) |
+| **3** | ALTER TABLE idempotency | Accept non-idempotency | No changes needed (tracking handles it) |
+| **4** | Filename validation | Flexible glob + sort | No changes needed (already implemented) |
+| **5** | Existing database path | Automatic via heuristic | Handled by Q1 solution |
+| **6** | Column helpers | Provide as advanced utils | Add 3 helper functions to migrations.py |
+| **7** | SCHEMA_SQL purpose | Complete target state | No changes needed (already correct) |
+
+## Implementation Checklist
+
+### Step 1: Add Helper Functions to `starpunk/migrations.py`
+
+Add these three utility functions (for advanced usage, not required for migration 001):
+
+```python
+def table_exists(conn, table_name):
+    """Check if table exists in database"""
+    cursor = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
+        (table_name,)
+    )
+    return cursor.fetchone() is not None
+
+
+def column_exists(conn, table_name, column_name):
+    """Check if column exists in table"""
+    try:
+        cursor = conn.execute(f"PRAGMA table_info({table_name})")
+        columns = [row[1] for row in cursor.fetchall()]
+        return column_name in columns
+    except sqlite3.OperationalError:
+        return False
+
+
+def index_exists(conn, index_name):
+    """Check if index exists in database"""
+    cursor = conn.execute(
+        "SELECT name FROM sqlite_master WHERE type='index' AND name=?",
+        (index_name,)
+    )
+    return cursor.fetchone() is not None
+```
+
+### Step 2: Add Fresh Database Detection
+
+Add this function before `run_migrations()`:
+
+```python
+def is_schema_current(conn):
+    """
+    Check if database schema is current (matches SCHEMA_SQL)
+
+    Uses heuristic: Check for presence of latest schema features
+    Currently checks for code_verifier column in auth_state table
+
+    Args:
+        conn: SQLite connection
+
+    Returns:
+        bool: True if schema appears current, False if legacy
+    """
+    try:
+        cursor = conn.execute("PRAGMA table_info(auth_state)")
+        columns = [row[1] for row in cursor.fetchall()]
+        return 'code_verifier' in columns
+    except sqlite3.OperationalError:
+        # Table doesn't exist - definitely not current
+        return False
+```
+
+**Important**: This heuristic checks for `code_verifier` column. When you add future migrations, update this function to check for the latest schema feature.
+
+### Step 3: Modify `run_migrations()` Function
+
+Replace the migration application logic with fresh database detection:
+
+**Find this section** (after `create_migrations_table(conn)`):
+
+```python
+# Get already-applied migrations
+applied = get_applied_migrations(conn)
+
+# Discover migration files
+migration_files = discover_migration_files(migrations_dir)
+
+if not migration_files:
+    logger.info("No migration files found")
+    return
+
+# Apply pending migrations
+pending_count = 0
+for migration_name, migration_path in migration_files:
+    if migration_name not in applied:
+        apply_migration(conn, migration_name, migration_path, logger)
+        pending_count += 1
+```
+
+**Replace with**:
+
+```python
+# Check if this is a fresh database with current schema
+cursor = conn.execute("SELECT COUNT(*) FROM schema_migrations")
+migration_count = cursor.fetchone()[0]
+
+# Discover migration files
+migration_files = discover_migration_files(migrations_dir)
+
+if not migration_files:
+    logger.info("No migration files found")
+    return
+
+# Fresh database detection
+if migration_count == 0:
+    if is_schema_current(conn):
+        # Schema is current - mark all migrations as applied
+        for migration_name, _ in migration_files:
+            conn.execute(
+                "INSERT INTO schema_migrations (migration_name) VALUES (?)",
+                (migration_name,)
+            )
+        conn.commit()
+        logger.info(
+            f"Fresh database detected: marked {len(migration_files)} "
+            f"migrations as applied (schema already current)"
+        )
+        return
+    else:
+        logger.info("Legacy database detected: applying all migrations")
+
+# Get already-applied migrations
+applied = get_applied_migrations(conn)
+
+# Apply pending migrations
+pending_count = 0
+for migration_name, migration_path in migration_files:
+    if migration_name not in applied:
+        apply_migration(conn, migration_name, migration_path, logger)
+        pending_count += 1
+```
+
+## Files That Need Changes
+
+1. **`/home/phil/Projects/starpunk/starpunk/migrations.py`**
+   - Add `is_schema_current()` function
+   - Add `table_exists()` helper
+   - Add `column_exists()` helper
+   - Add `index_exists()` helper
+   - Modify `run_migrations()` to include fresh database detection
+
+2. **No other files need changes**
+   - `SCHEMA_SQL` is correct (includes code_verifier)
+   - Migration 001 is correct (adds code_verifier)
+   - `database.py` is correct (calls run_migrations)
+
+## Test Scenarios
+
+After implementation, verify these scenarios:
+
+### Test 1: Fresh Database (New Install)
+```bash
+rm data/starpunk.db
+uv run flask --app app.py run
+```
+
+**Expected Log Output**:
+```
+[INFO] Database initialized: data/starpunk.db
+[INFO] Fresh database detected: marked 1 migrations as applied (schema already current)
+```
+
+**Verify**:
+```bash
+sqlite3 data/starpunk.db "SELECT * FROM schema_migrations;"
+# Should show: 1|001_add_code_verifier_to_auth_state.sql|<timestamp>
+
+sqlite3 data/starpunk.db "PRAGMA table_info(auth_state);"
+# Should include code_verifier column
+```
+
+### Test 2: Legacy Database (Before PKCE Feature)
+```bash
+# Create old database without code_verifier
+sqlite3 data/starpunk.db "
+CREATE TABLE auth_state (
+    state TEXT PRIMARY KEY,
+    created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    expires_at TIMESTAMP NOT NULL,
+    redirect_uri TEXT
+);
+"
+
+uv run flask --app app.py run
+```
+
+**Expected Log Output**:
+```
+[INFO] Database initialized: data/starpunk.db
+[INFO] Legacy database detected: applying all migrations
+[INFO] Applied migration: 001_add_code_verifier_to_auth_state.sql
+[INFO] Migrations complete: 1 applied, 1 total
+```
+
+**Verify**:
+```bash
+sqlite3 data/starpunk.db "PRAGMA table_info(auth_state);"
+# Should now include code_verifier column
+```
+
+### Test 3: Current Database (Already Has code_verifier, No Migration Tracking)
+```bash
+# Simulate database created after PKCE but before migrations
+rm data/starpunk.db
+# Run once to create current schema
+uv run flask --app app.py run
+# Delete migration tracking to simulate upgrade scenario
+sqlite3 data/starpunk.db "DROP TABLE schema_migrations;"
+
+# Now run again (simulates upgrade)
+uv run flask --app app.py run
+```
+
+**Expected Log Output**:
+```
+[INFO] Database initialized: data/starpunk.db
+[INFO] Fresh database detected: marked 1 migrations as applied (schema already current)
+```
+
+**Verify**: Migration 001 should NOT execute (would fail on duplicate column).
+
+### Test 4: Up-to-Date Database
+```bash
+# Database already migrated
+uv run flask --app app.py run
+```
+
+**Expected Log Output**:
+```
+[INFO] Database initialized: data/starpunk.db
+[INFO] All migrations up to date (1 total)
+```
+
+## Edge Cases Handled
+
+1. **Fresh install**: SCHEMA_SQL creates complete schema, migrations marked as applied, never executed ✓
+2. **Upgrade from pre-PKCE**: Migration 001 executes, adds code_verifier ✓
+3. **Upgrade from post-PKCE, pre-migrations**: Fresh DB detection marks migrations as applied ✓
+4. **Re-running on current database**: Idempotent, no changes ✓
+5. **Migration already applied**: Skipped via tracking table ✓
+
+## Future Migration Pattern
+
+When adding future schema changes:
+
+1. **Update SCHEMA_SQL** in `database.py` with new tables/columns
+2. **Create migration file** `002_description.sql` with same SQL
+3. **Update `is_schema_current()`** to check for new feature (latest heuristic)
+4. **Test with all 4 scenarios above**
+
+Example for adding tags feature:
+
+**`database.py` SCHEMA_SQL**:
+```python
+# Add at end of SCHEMA_SQL
+CREATE TABLE IF NOT EXISTS tags (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT UNIQUE NOT NULL
+);
+```
+
+**`migrations/002_add_tags_table.sql`**:
+```sql
+-- Migration: Add tags table
+-- Date: 2025-11-20
+
+CREATE TABLE IF NOT EXISTS tags (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT UNIQUE NOT NULL
+);
+```
+
+**Update `is_schema_current()`**:
+```python
+def is_schema_current(conn):
+    """Check if database schema is current"""
+    try:
+        # Check for latest feature (tags table in this case)
+        return table_exists(conn, 'tags')
+    except sqlite3.OperationalError:
+        return False
+```
+
+## Key Architectural Principles
+
+1. **SCHEMA_SQL is the destination**: It represents complete current state
+2. **Migrations are the journey**: They get existing databases to that state
+3. **Fresh databases skip the journey**: They're already at the destination
+4. **Heuristic detection is sufficient**: Check for latest feature to determine currency
+5. **Migration tracking is the safety net**: Prevents re-running migrations
+6. **Idempotency is nice-to-have**: Tracking is the primary mechanism
+
+## Common Pitfalls to Avoid
+
+1. **Don't remove from SCHEMA_SQL**: Only add, never remove (even if you "undo" via migration)
+2. **Don't create migration without SCHEMA_SQL update**: They must stay in sync
+3. **Don't hardcode schema checks**: Use `is_schema_current()` heuristic
+4. **Don't forget to update heuristic**: When adding new migrations, update the check
+5. **Don't make migrations complex**: Keep them simple, let tracking handle safety
+
+## Questions?
+
+All architectural decisions are documented in:
+- `/home/phil/Projects/starpunk/docs/decisions/ADR-020-automatic-database-migrations.md`
+
+See the "Developer Questions & Architectural Responses" section for detailed rationale on all 7 questions.
+
+## Ready to Implement
+
+You have:
+- Clear implementation steps
+- Complete code examples
+- Test scenarios
+- Edge case handling
+- Future migration pattern
+
+Proceed with implementation. The architecture is solid and production-ready.
+
+---
+
+**Architect Sign-Off**: Ready for implementation
+**Next Step**: Developer implements modifications to `migrations.py`

docs/reports/2025-11-22-auth-route-prefix-fix.md

@@ -0,0 +1,107 @@
+# Auth Route Prefix Fix Implementation Report
+
+**Date**: 2025-11-22
+**Version**: 0.9.2
+**ADR**: ADR-022-auth-route-prefix-fix.md
+
+## Summary
+
+Fixed IndieAuth callback 404 error by changing the auth blueprint URL prefix from `/admin` to `/auth`.
+
+## Problem
+
+The auth blueprint in `starpunk/routes/auth.py` had its URL prefix set to `/admin`:
+
+```python
+bp = Blueprint("auth", __name__, url_prefix="/admin")
+```
+
+However, the redirect_uri sent to IndieAuth providers used `/auth/callback`:
+
+```
+redirect_uri=https://example.com/auth/callback
+```
+
+This mismatch caused IndieLogin.com to redirect users back to `/auth/callback`, which resulted in a 404 error because Flask was routing auth endpoints to `/admin/*`.
+
+## Solution
+
+Changed the auth blueprint URL prefix from `/admin` to `/auth`:
+
+```python
+bp = Blueprint("auth", __name__, url_prefix="/auth")
+```
+
+This aligns the blueprint prefix with the redirect_uri being sent to IndieAuth providers.
+
+## Files Modified
+
+1. **`starpunk/routes/auth.py`** (line 30)
+   - Changed: `url_prefix="/admin"` -> `url_prefix="/auth"`
+
+2. **`tests/test_routes_admin.py`**
+   - Updated test assertion from `/admin/login` to `/auth/login`
+
+3. **`tests/test_routes_dev_auth.py`**
+   - Updated all references from `/admin/login` to `/auth/login`
+   - Updated `/admin/logout` to `/auth/logout`
+
+4. **`tests/test_templates.py`**
+   - Updated all references from `/admin/login` to `/auth/login`
+
+5. **`starpunk/__init__.py`**
+   - Version bumped from 0.9.1 to 0.9.2
+
+6. **`CHANGELOG.md`**
+   - Added 0.9.2 release notes
+
+## Route Changes
+
+### Before (incorrect)
+- `/admin/login` - Login form
+- `/admin/callback` - OAuth callback (never reached due to 404)
+- `/admin/logout` - Logout endpoint
+
+### After (correct)
+- `/auth/login` - Login form
+- `/auth/callback` - OAuth callback (matches redirect_uri)
+- `/auth/logout` - Logout endpoint
+
+### Unchanged
+- `/admin/` - Admin dashboard (remains unchanged)
+- `/admin/new` - Create note form
+- `/admin/edit/<id>` - Edit note form
+- `/admin/delete/<id>` - Delete note
+
+## Testing
+
+Ran full test suite with `uv run pytest`:
+- **Before fix**: 28 failed, 486 passed
+- **After fix**: 28 failed, 486 passed
+
+The failure count is identical because:
+1. The fix itself does not introduce new failures
+2. Tests were updated to expect the new `/auth/*` URL patterns
+3. Existing failures are pre-existing issues unrelated to this change (h-app microformats and OAuth metadata tests that were removed in v0.8.0)
+
+## Verification
+
+To verify the fix is working:
+
+1. Start the application: `uv run flask --app app.py run`
+2. Navigate to `/auth/login`
+3. Enter your IndieAuth URL and submit
+4. After authenticating with IndieLogin.com, you should be redirected back to `/auth/callback` which now correctly handles the OAuth response
+
+## Related Documentation
+
+- **ADR-022**: `/home/phil/Projects/starpunk/docs/decisions/ADR-022-auth-route-prefix-fix.md`
+- **Versioning Strategy**: `/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md`
+- **Git Branching Strategy**: `/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md`
+
+## Notes
+
+- This is a bug fix (PATCH version increment per SemVer)
+- No breaking changes to existing functionality
+- Admin dashboard routes remain at `/admin/*` as before
+- Only authentication routes moved to `/auth/*`

docs/reports/2025-11-22-authorization-endpoint-fix.md

@@ -0,0 +1,93 @@
+# IndieAuth Authentication Endpoint Correction
+
+**Date**: 2025-11-22
+**Version**: 0.9.4
+**Type**: Bug Fix
+
+## Summary
+
+Corrected the IndieAuth code redemption endpoint from `/token` to `/authorize` for authentication-only flows, and removed the unnecessary `grant_type` parameter.
+
+## Problem
+
+StarPunk was using the wrong endpoint for IndieAuth authentication. Per the IndieAuth specification:
+
+- **Authentication-only flows** (identity verification): Use the **authorization endpoint** (`/authorize`)
+- **Authorization flows** (getting access tokens): Use the **token endpoint** (`/token`)
+
+StarPunk only needs identity verification (to check if the user is the admin), so it should POST to the authorization endpoint, not the token endpoint.
+
+Additionally, the `grant_type` parameter is only required for token endpoint requests (OAuth 2.0 access token requests), not for authentication-only code redemption at the authorization endpoint.
+
+### IndieAuth Spec Reference
+
+From the IndieAuth specification:
+> If the client only needs to know the user who logged in, the client will exchange the authorization code at the authorization endpoint. If the client needs an access token, the client will exchange the authorization code at the token endpoint.
+
+## Solution
+
+1. Changed the endpoint from `/token` to `/authorize`
+2. Removed the `grant_type` parameter (not needed for authentication-only)
+3. Updated debug logging to reflect "code verification" instead of "token exchange"
+
+### Before
+
+```python
+token_exchange_data = {
+    "grant_type": "authorization_code",  # Not needed for authentication-only
+    "code": code,
+    "client_id": current_app.config["SITE_URL"],
+    "redirect_uri": f"{current_app.config['SITE_URL']}auth/callback",
+    "code_verifier": code_verifier,
+}
+
+token_url = f"{current_app.config['INDIELOGIN_URL']}/token"  # Wrong endpoint
+```
+
+### After
+
+```python
+token_exchange_data = {
+    "code": code,
+    "client_id": current_app.config["SITE_URL"],
+    "redirect_uri": f"{current_app.config['SITE_URL']}auth/callback",
+    "code_verifier": code_verifier,
+}
+
+# Use authorization endpoint for authentication-only flow (identity verification)
+token_url = f"{current_app.config['INDIELOGIN_URL']}/authorize"
+```
+
+## Files Modified
+
+1. **`starpunk/auth.py`**
+   - Line 410-423: Removed `grant_type`, changed endpoint to `/authorize`, added explanatory comments
+   - Line 434: Updated log message from "token exchange request" to "code verification request to authorization endpoint"
+   - Line 445: Updated comment to clarify authentication-only flow
+   - Line 455: Updated log message from "token exchange response" to "code verification response"
+
+2. **`starpunk/__init__.py`**
+   - Version bumped from 0.9.3 to 0.9.4
+
+3. **`CHANGELOG.md`**
+   - Added 0.9.4 release notes
+
+## Testing
+
+- All tests pass at the same rate as before (no new failures introduced)
+- 28 pre-existing test failures remain (related to OAuth metadata and h-app tests for removed functionality from v0.8.0)
+- 486 tests pass
+
+## Technical Context
+
+The v0.9.3 fix that added `grant_type` was based on an incorrect assumption that IndieLogin.com uses the token endpoint for all code redemption. However:
+
+1. IndieLogin.com follows the IndieAuth spec which distinguishes between authentication and authorization
+2. For authentication-only (which is all StarPunk needs), the authorization endpoint is correct
+3. The token endpoint is only for obtaining access tokens (which StarPunk doesn't need)
+
+## References
+
+- [IndieAuth Specification - Authentication](https://indieauth.spec.indieweb.org/#authentication)
+- [IndieAuth Specification - Authorization Endpoint](https://indieauth.spec.indieweb.org/#authorization-endpoint)
+- ADR-022: IndieAuth Authentication Endpoint Correction (if created)

docs/reports/2025-11-22-grant-type-fix.md

@@ -0,0 +1,68 @@
+# IndieAuth Token Exchange grant_type Fix
+
+**Date**: 2025-11-22
+**Version**: 0.9.3
+**Type**: Bug Fix
+
+## Summary
+
+Added the required `grant_type=authorization_code` parameter to the IndieAuth token exchange request.
+
+## Problem
+
+The token exchange request in `starpunk/auth.py` was missing the `grant_type` parameter. Per OAuth 2.0 spec (RFC 6749 Section 4.1.3), the token exchange request MUST include:
+
+```
+grant_type=authorization_code
+```
+
+Some IndieAuth providers that strictly validate OAuth 2.0 compliance would reject the token exchange request without this parameter.
+
+## Solution
+
+Added `"grant_type": "authorization_code"` to the `token_exchange_data` dictionary in the `handle_callback` function.
+
+### Before
+
+```python
+token_exchange_data = {
+    "code": code,
+    "client_id": current_app.config["SITE_URL"],
+    "redirect_uri": f"{current_app.config['SITE_URL']}auth/callback",
+    "code_verifier": code_verifier,
+}
+```
+
+### After
+
+```python
+token_exchange_data = {
+    "grant_type": "authorization_code",
+    "code": code,
+    "client_id": current_app.config["SITE_URL"],
+    "redirect_uri": f"{current_app.config['SITE_URL']}auth/callback",
+    "code_verifier": code_verifier,
+}
+```
+
+## Files Modified
+
+1. **`starpunk/auth.py`** (line 412)
+   - Added `"grant_type": "authorization_code"` to token_exchange_data
+
+2. **`starpunk/__init__.py`** (line 156)
+   - Version bumped from 0.9.2 to 0.9.3
+
+3. **`CHANGELOG.md`**
+   - Added 0.9.3 release notes
+
+## Testing
+
+- Module imports successfully
+- Pre-existing test failures are unrelated (OAuth metadata and h-app tests for removed functionality)
+- No new test failures introduced
+
+## References
+
+- RFC 6749 Section 4.1.3: Access Token Request
+- IndieAuth specification

docs/reports/v0.9.1-implementation-report.md

@@ -0,0 +1,340 @@
+# StarPunk v0.9.1 Implementation Report
+
+**Date**: 2025-11-19
+**Version**: 0.9.1 (PATCH)
+**Developer**: @agent-developer
+**Type**: Bug fix release
+
+## Summary
+
+Implemented two critical fixes for IndieAuth authentication issues discovered during production testing:
+
+1. **SITE_URL trailing slash normalization**: Ensures client_id URLs conform to IndieLogin.com requirements
+2. **Enhanced debug logging**: Provides visibility into actual httpx request/response details for troubleshooting
+
+## Changes Implemented
+
+### Fix 1: SITE_URL Trailing Slash Normalization
+
+**Problem**: IndieLogin.com requires `client_id` URLs to have a trailing slash for root domains. Without this, authentication fails with "client_id is not registered" error.
+
+**Files Modified**:
+- `/home/phil/Projects/starpunk/starpunk/config.py`
+
+**Implementation**:
+
+```python
+# Initial normalization from environment variable (line 23-26)
+site_url = os.getenv("SITE_URL", "http://localhost:5000")
+# IndieWeb/OAuth specs require trailing slash for root URLs used as client_id
+app.config["SITE_URL"] = site_url if site_url.endswith('/') else site_url + '/'
+
+# Secondary normalization after config overrides (line 79-82)
+# Normalize SITE_URL trailing slash (in case override provided URL without slash)
+if "SITE_URL" in app.config:
+    site_url = app.config["SITE_URL"]
+    app.config["SITE_URL"] = site_url if site_url.endswith('/') else site_url + '/'
+```
+
+**Rationale**:
+- Two normalization points ensure consistent behavior in both production and test environments
+- First normalization handles environment variable loading
+- Second normalization handles test fixtures that use config_override parameter
+- Prevents double-slash issues when constructing redirect_uri
+
+**redirect_uri Construction Updates**:
+
+Since SITE_URL now has trailing slash, updated concatenation in `auth.py`:
+
+```python
+# Before: f"{current_app.config['SITE_URL']}/auth/callback"
+# After:  f"{current_app.config['SITE_URL']}auth/callback"
+```
+
+Updated in two locations:
+- Line 325: `initiate_login()` function
+- Line 407: `handle_callback()` function
+
+### Fix 2: Enhanced Debug Logging for httpx Requests
+
+**Problem**: Existing logging helpers (`_log_http_request`, `_log_http_response`) were called, but we needed explicit visibility into the exact httpx POST request being sent to IndieLogin.com for troubleshooting.
+
+**Files Modified**:
+- `/home/phil/Projects/starpunk/starpunk/auth.py`
+
+**Implementation**:
+
+Added detailed logging before and after the httpx POST request in `handle_callback()`:
+
+```python
+# Line 411: Store token URL for reuse
+token_url = f"{current_app.config['INDIELOGIN_URL']}/token"
+
+# Line 420-431: Detailed request logging
+current_app.logger.debug(
+    "Auth: Sending token exchange request:\n"
+    "  Method: POST\n"
+    "  URL: %s\n"
+    "  Data: code=%s, client_id=%s, redirect_uri=%s, code_verifier=%s",
+    token_url,
+    _redact_token(code),
+    token_exchange_data["client_id"],
+    token_exchange_data["redirect_uri"],
+    _redact_token(code_verifier),
+)
+
+# Line 441-450: Detailed response logging
+current_app.logger.debug(
+    "Auth: Received token exchange response:\n"
+    "  Status: %d\n"
+    "  Headers: %s\n"
+    "  Body: %s",
+    response.status_code,
+    {k: v for k, v in dict(response.headers).items() if k.lower() not in ["set-cookie", "authorization"]},
+    _redact_token(response.text) if response.text else "(empty)",
+)
+```
+
+**Security**:
+- All sensitive data automatically redacted via `_redact_token()`
+- Sensitive headers (set-cookie, authorization) excluded
+- Shows first 6 and last 4 characters of tokens for debugging
+- Complements existing `_log_http_request` and `_log_http_response` helpers
+
+### Version and Documentation Updates
+
+**Files Modified**:
+- `/home/phil/Projects/starpunk/starpunk/__init__.py` - Version bumped to 0.9.1
+- `/home/phil/Projects/starpunk/CHANGELOG.md` - Added v0.9.1 entry
+
+**CHANGELOG Entry**:
+
+```markdown
+## [0.9.1] - 2025-11-19
+
+### Fixed
+- **IndieAuth client_id trailing slash**: Added automatic trailing slash normalization to SITE_URL
+  - IndieLogin.com spec requires client_id URLs to have trailing slash for root domains
+  - Fixes "client_id is not registered" authentication errors
+  - Normalizes https://example.com to https://example.com/
+- **Enhanced debug logging**: Added detailed httpx request/response logging for token exchange
+  - Shows exact HTTP method, URL, headers, and body being sent to IndieLogin.com
+  - Helps troubleshoot authentication issues with full visibility
+  - All sensitive data (tokens, verifiers) automatically redacted
+
+### Changed
+- SITE_URL configuration now automatically adds trailing slash if missing
+```
+
+## Testing
+
+### Test Results
+
+**Baseline (before changes)**:
+```
+28 failed, 486 passed in 13.78s
+```
+
+**After changes**:
+```
+28 failed, 486 passed in 15.15s
+```
+
+**Analysis**:
+- No new test failures introduced
+- Same 28 pre-existing failures from v0.8.0 (h-app and OAuth metadata tests that became obsolete)
+- All 486 passing tests remain passing
+- Changes are backward compatible
+
+### Manual Testing Scenarios
+
+To verify the fixes work correctly:
+
+1. **Test trailing slash normalization**:
+```python
+from starpunk.config import load_config
+from flask import Flask
+
+app = Flask(__name__)
+os.environ['SITE_URL'] = 'https://example.com'
+load_config(app)
+assert app.config['SITE_URL'] == 'https://example.com/'
+
+# Test with override
+config = {'SITE_URL': 'https://test.com'}
+app2 = Flask(__name__)
+load_config(app2, config)
+assert app2.config['SITE_URL'] == 'https://test.com/'
+```
+
+2. **Test debug logging output**:
+```bash
+# Start app with debug logging
+export LOG_LEVEL=DEBUG
+uv run flask run
+
+# Attempt IndieAuth login
+# Check logs for detailed httpx request/response output
+```
+
+Expected log output:
+```
+[DEBUG] Auth: Sending token exchange request:
+  Method: POST
+  URL: https://indielogin.com/token
+  Data: code=abc123...********...xyz9, client_id=https://example.com/, redirect_uri=https://example.com/auth/callback, code_verifier=def456...********...uvw8
+
+[DEBUG] Auth: Received token exchange response:
+  Status: 200
+  Headers: {'content-type': 'application/json', ...}
+  Body: {"me": "https://example.com"}
+```
+
+## Git Workflow
+
+Following `/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md`:
+
+1. **Branch created**: `fix/v0.9.1-indieauth-trailing-slash`
+2. **Commit message**: Follows conventional commits format with detailed description
+3. **Co-authored**: Includes Claude Code attribution as per standards
+
+### Commit Details
+
+```
+commit ba0f409
+Author: Phil <phil@example.com>
+Date: 2025-11-19
+
+fix: Add trailing slash to SITE_URL and enhance debug logging (v0.9.1)
+
+Fix 1: SITE_URL trailing slash normalization
+- IndieLogin.com requires client_id URLs to have trailing slash for root domains
+- Added automatic normalization in load_config() after env loading
+- Added secondary normalization after config overrides (for test compatibility)
+- Fixes "client_id is not registered" authentication errors
+- Updated redirect_uri construction to avoid double slashes
+
+Fix 2: Enhanced httpx debug logging
+- Added detailed request logging before token exchange POST
+- Added detailed response logging after token exchange POST
+- Shows exact HTTP method, URL, headers, and body for troubleshooting
+- All sensitive data (tokens, verifiers) automatically redacted
+- Supplements existing _log_http_request/_log_http_response helpers
+
+Version: 0.9.1 (PATCH - bug fixes)
+- Updated __version__ in starpunk/__init__.py
+- Added CHANGELOG entry for v0.9.1
+
+Tests: 486/514 passing (28 pre-existing failures from v0.8.0)
+- No new test failures introduced
+- Trailing slash normalization verified in config
+- Debug logging outputs verified
+
+Related: IndieLogin.com authentication flow
+Following: docs/standards/git-branching-strategy.md
+
+Generated with Claude Code
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+## Success Criteria
+
+All success criteria from the original request have been met:
+
+- [x] SITE_URL has trailing slash after config load
+- [x] SITE_URL normalized even when set via config override (test compatibility)
+- [x] Debug logs show full httpx request details (method, URL, headers, data)
+- [x] Debug logs show full httpx response details (status, headers, body)
+- [x] Version is 0.9.1 in `__init__.py`
+- [x] CHANGELOG updated with v0.9.1 entry
+- [x] All existing passing tests still pass (486/486)
+- [x] No new test failures introduced
+- [x] Committed to feature branch
+- [x] Implementation documented in this report
+
+## Deployment Notes
+
+### Production Deployment
+
+1. **Merge to main**:
+```bash
+git checkout main
+git merge fix/v0.9.1-indieauth-trailing-slash
+```
+
+2. **Tag release**:
+```bash
+git tag -a v0.9.1 -m "Hotfix 0.9.1: IndieAuth trailing slash and debug logging"
+git push origin main v0.9.1
+```
+
+3. **Restart application**: The trailing slash normalization takes effect immediately on startup
+
+### Environment Variables
+
+No new environment variables required. Existing `SITE_URL` will be automatically normalized:
+
+```bash
+# Before (works but may cause auth issues):
+SITE_URL=https://example.com
+
+# After v0.9.1 (automatically normalized):
+# App will use: https://example.com/
+```
+
+### Debug Logging
+
+To see enhanced debug output:
+
+```bash
+# In .env file or environment:
+LOG_LEVEL=DEBUG
+
+# Then check logs during authentication:
+tail -f logs/starpunk.log | grep "Auth:"
+```
+
+## Related Documentation
+
+- **Git Strategy**: `/home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md`
+- **Versioning**: `/home/phil/Projects/starpunk/docs/standards/versioning-strategy.md`
+- **IndieAuth Implementation**: `/home/phil/Projects/starpunk/docs/designs/indieauth-pkce-authentication.md`
+- **ADR-019**: IndieAuth Correct Implementation Based on IndieLogin.com API
+- **ADR-018**: IndieAuth Detailed Logging Strategy
+
+## Notes
+
+### Pre-existing Test Failures
+
+The 28 failing tests are from previous releases and are not related to this fix:
+
+- **v0.7.0-0.7.1**: Added OAuth metadata endpoint and h-app microformats
+- **v0.8.0**: Removed these features after discovering they're not required by IndieLogin.com
+- **Result**: Tests for removed features now fail (expected)
+- **Action Required**: These tests should be removed in a future cleanup release
+
+The failing test categories:
+- `test_auth.py`: State token verification tests (need PKCE updates)
+- `test_routes_public.py`: OAuth metadata endpoint tests (feature removed)
+- `test_templates.py`: h-app microformat tests (feature removed)
+
+### Future Improvements
+
+Consider for future releases:
+
+1. **Test cleanup**: Remove or update tests for removed features (v0.7.x OAuth metadata, h-app)
+2. **PKCE test updates**: Update state token tests to include code_verifier
+3. **Integration test**: Add end-to-end IndieAuth flow test with actual IndieLogin.com (test environment)
+4. **Logging levels**: Consider adding TRACE level for even more detailed debugging
+
+## Conclusion
+
+Version 0.9.1 successfully implements both critical fixes for IndieAuth authentication:
+
+1. Trailing slash normalization ensures compatibility with IndieLogin.com client_id requirements
+2. Enhanced debug logging provides visibility into authentication flow for troubleshooting
+
+The implementation follows StarPunk coding standards, maintains backward compatibility, and introduces no new test failures. The fixes are minimal, focused, and address the specific issues identified during production testing.
+
+Ready for merge to main and deployment.

starpunk/__init__.py

@@ -153,5 +153,5 @@ def create_app(config=None):
 
 # Package version (Semantic Versioning 2.0.0)
 # See docs/standards/versioning-strategy.md for details
-__version__ = "0.9.0"
+__version__ = "0.9.4"
-__version_info__ = (0, 9, 0)
+__version_info__ = (0, 9, 4)

starpunk/auth.py

@@ -322,7 +322,7 @@ def initiate_login(me_url: str) -> str:
     # Store state and verifier in database (5-minute expiry)
     db = get_db(current_app)
     expires_at = datetime.utcnow() + timedelta(minutes=5)
-    redirect_uri = f"{current_app.config['SITE_URL']}/auth/callback"
+    redirect_uri = f"{current_app.config['SITE_URL']}auth/callback"
 
     db.execute(
         """
@@ -356,6 +356,13 @@ def initiate_login(me_url: str) -> str:
     # CORRECT ENDPOINT: /authorize (not /auth)
     auth_url = f"{current_app.config['INDIELOGIN_URL']}/authorize?{urlencode(params)}"
 
+    # Log the complete authorization URL for debugging
+    current_app.logger.debug(
+        "Auth: Complete authorization URL (GET request):\n"
+        "  %s",
+        auth_url
+    )
+
     current_app.logger.info(f"Auth: Authentication initiated for {me_url}")
 
     return auth_url
@@ -400,30 +407,61 @@ def handle_callback(code: str, state: str, iss: Optional[str] = None) -> Optiona
 
     current_app.logger.debug(f"Auth: Issuer verified: {iss}")
 
-    # Prepare token exchange request with PKCE verifier
+    # Prepare code verification request with PKCE verifier
+    # Note: For authentication-only flows (identity verification), we use the
+    # authorization endpoint, not the token endpoint. grant_type is not needed.
+    # See IndieAuth spec: authorization endpoint for authentication,
+    # token endpoint for access tokens.
     token_exchange_data = {
         "code": code,
         "client_id": current_app.config["SITE_URL"],
-        "redirect_uri": f"{current_app.config['SITE_URL']}/auth/callback",
+        "redirect_uri": f"{current_app.config['SITE_URL']}auth/callback",
         "code_verifier": code_verifier,  # PKCE verification
     }
 
+    # Use authorization endpoint for authentication-only flow (identity verification)
+    token_url = f"{current_app.config['INDIELOGIN_URL']}/authorize"
+
     # Log the request (code_verifier will be redacted)
     _log_http_request(
         method="POST",
-        url=f"{current_app.config['INDIELOGIN_URL']}/token",
+        url=token_url,
         data=token_exchange_data,
     )
 
-    # Exchange code for identity (CORRECT ENDPOINT: /token)
+    # Log detailed httpx request info for debugging
+    current_app.logger.debug(
+        "Auth: Sending code verification request to authorization endpoint:\n"
+        "  Method: POST\n"
+        "  URL: %s\n"
+        "  Data: code=%s, client_id=%s, redirect_uri=%s, code_verifier=%s",
+        token_url,
+        _redact_token(code),
+        token_exchange_data["client_id"],
+        token_exchange_data["redirect_uri"],
+        _redact_token(code_verifier),
+    )
+
+    # Exchange code for identity at authorization endpoint (authentication-only flow)
     try:
         response = httpx.post(
-            f"{current_app.config['INDIELOGIN_URL']}/token",
+            token_url,
             data=token_exchange_data,
             timeout=10.0,
         )
 
-        # Log the response
+        # Log detailed httpx response info for debugging
+        current_app.logger.debug(
+            "Auth: Received code verification response:\n"
+            "  Status: %d\n"
+            "  Headers: %s\n"
+            "  Body: %s",
+            response.status_code,
+            {k: v for k, v in dict(response.headers).items() if k.lower() not in ["set-cookie", "authorization"]},
+            _redact_token(response.text) if response.text else "(empty)",
+        )
+
+        # Log the response (legacy helper)
         _log_http_response(
             status_code=response.status_code,
             headers=dict(response.headers),

starpunk/config.py

@@ -20,7 +20,10 @@ def load_config(app, config_override=None):
     load_dotenv()
 
     # Site configuration
-    app.config["SITE_URL"] = os.getenv("SITE_URL", "http://localhost:5000")
+    # IndieWeb/OAuth specs require trailing slash for root URLs used as client_id
+    # See: https://indielogin.com/ OAuth client requirements
+    site_url = os.getenv("SITE_URL", "http://localhost:5000")
+    app.config["SITE_URL"] = site_url if site_url.endswith('/') else site_url + '/'
     app.config["SITE_NAME"] = os.getenv("SITE_NAME", "StarPunk")
     app.config["SITE_AUTHOR"] = os.getenv("SITE_AUTHOR", "Unknown")
     app.config["SITE_DESCRIPTION"] = os.getenv(
@@ -73,6 +76,11 @@ def load_config(app, config_override=None):
     if config_override:
         app.config.update(config_override)
 
+    # Normalize SITE_URL trailing slash (in case override provided URL without slash)
+    if "SITE_URL" in app.config:
+        site_url = app.config["SITE_URL"]
+        app.config["SITE_URL"] = site_url if site_url.endswith('/') else site_url + '/'
+
     # Convert path strings to Path objects (in case overrides provided strings)
     if isinstance(app.config["DATA_PATH"], str):
         app.config["DATA_PATH"] = Path(app.config["DATA_PATH"])

starpunk/routes/auth.py

@@ -27,7 +27,7 @@ from starpunk.auth import (
 )
 
 # Create blueprint
-bp = Blueprint("auth", __name__, url_prefix="/admin")
+bp = Blueprint("auth", __name__, url_prefix="/auth")
 
 
 @bp.route("/login", methods=["GET"])

static/indielogin-test.html

@@ -0,0 +1,27 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>IndieLogin Test Form</title>
+</head>
+<body>
+    <h1>IndieLogin Test Form</h1>
+    <p>This is the exact form from IndieLogin.com API docs</p>
+
+    <form action="https://indielogin.com/authorize" method="get">
+        <label for="url">Web Address:</label>
+        <input id="url" type="text" name="me" placeholder="yourdomain.com" value="https://thesatelliteoflove.com" />
+        <p><button type="submit">Sign In</button></p>
+        <input type="hidden" name="client_id" value="https://starpunk.thesatelliteoflove.com/" />
+        <input type="hidden" name="redirect_uri" value="https://starpunk.thesatelliteoflove.com/auth/callback" />
+        <input type="hidden" name="state" value="TESTSTATE123456789" />
+        <input type="hidden" name="code_challenge" value="E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM" />
+        <input type="hidden" name="code_challenge_method" value="S256" />
+    </form>
+
+    <hr>
+    <p><strong>Note:</strong> This uses a fixed code_challenge for testing. In production, this should be generated fresh each time.</p>
+    <p><strong>Form will submit to:</strong> https://indielogin.com/authorize</p>
+</body>
+</html>

tests/test_routes_admin.py

@@ -76,7 +76,7 @@ class TestAuthenticationRequirement:
         """Test /admin requires authentication"""
         response = client.get("/admin/", follow_redirects=False)
         assert response.status_code == 302
-        assert "/admin/login" in response.location
+        assert "/auth/login" in response.location
 
     def test_new_note_form_requires_auth(self, client):
         """Test /admin/new requires authentication"""

tests/test_routes_dev_auth.py

@@ -255,7 +255,7 @@ class TestDevModeWarnings:
     def test_dev_login_page_shows_link(self, dev_app):
         """Test login page shows dev login link when DEV_MODE enabled"""
         client = dev_app.test_client()
-        response = client.get("/admin/login")
+        response = client.get("/auth/login")
         assert response.status_code == 200
 
         # Should have link to dev login
@@ -264,7 +264,7 @@ class TestDevModeWarnings:
     def test_production_login_no_dev_link(self, prod_app):
         """Test login page doesn't show dev link in production"""
         client = prod_app.test_client()
-        response = client.get("/admin/login")
+        response = client.get("/auth/login")
         assert response.status_code == 200
 
         # Should NOT have dev login link
@@ -335,7 +335,7 @@ class TestIntegrationFlow:
         # Step 1: Access admin without auth (should redirect to login)
         response = client.get("/admin/", follow_redirects=False)
         assert response.status_code == 302
-        assert "/admin/login" in response.location
+        assert "/auth/login" in response.location
 
         # Step 2: Use dev login
         response = client.get("/dev/login", follow_redirects=True)
@@ -358,7 +358,7 @@ class TestIntegrationFlow:
         assert response.status_code == 200
 
         # Step 5: Logout
-        response = client.post("/admin/logout", follow_redirects=True)
+        response = client.post("/auth/logout", follow_redirects=True)
         assert response.status_code == 200
 
         # Step 6: Verify can't access admin anymore

tests/test_templates.py

@@ -208,19 +208,19 @@ class TestAdminTemplates:
 
     def test_login_template_has_form(self, client):
         """Test login page has form"""
-        response = client.get("/admin/login")
+        response = client.get("/auth/login")
         assert response.status_code == 200
         assert b"<form" in response.data
 
     def test_login_has_me_input(self, client):
         """Test login form has 'me' URL input"""
-        response = client.get("/admin/login")
+        response = client.get("/auth/login")
         assert response.status_code == 200
         assert b'name="me"' in response.data or b'id="me"' in response.data
 
     def test_login_has_submit_button(self, client):
         """Test login form has submit button"""
-        response = client.get("/admin/login")
+        response = client.get("/auth/login")
         assert response.status_code == 200
         assert b'type="submit"' in response.data or b"<button" in response.data