Gondulf/docs/designs/phase-5c-real-client-testing.md

Design: Phase 5c - Real Client Testing

Date: 2025-11-24 Author: Claude (Architect Agent) Status: Ready for Implementation Version: 1.0.0-rc.8

Purpose

Validate that the Gondulf IndieAuth server successfully interoperates with real-world IndieAuth clients, confirming W3C specification compliance and production readiness for v1.0.0 release.

Specification References

• W3C IndieAuth: Section 5.2 (Client Behavior)
• OAuth 2.0 RFC 6749: Section 4.1 (Authorization Code Flow)
• IndieAuth Discovery: https://indieauth.spec.indieweb.org/#discovery

Design Overview

This phase focuses on testing the deployed Gondulf server with actual IndieAuth clients to ensure real-world compatibility. The DNS verification bug fix in rc.8 has removed the last known blocker, making the system ready for comprehensive client testing.

Testing Strategy

Prerequisites

1. DNS Configuration Verified

   • Record exists: _gondulf.thesatelliteoflove.com TXT "gondulf-verify-domain"
   • Record is queryable from production server
   • TTL considerations understood

2. Production Deployment

   • v1.0.0-rc.8 container deployed
   • HTTPS working with valid certificate
   • Health check returning 200 OK
   • Logs accessible for debugging

3. Test Environment

   • Production URL: https://gondulf.thesatelliteoflove.com
   • Domain to authenticate: thesatelliteoflove.com
   • Email configured for verification codes

Client Testing Matrix

Tier 1: Essential Clients (Must Pass)

1. IndieAuth.com Test Client

URL: https://indieauth.com/ Why Critical: Reference implementation test client Test Flow:

1. Navigate to https://indieauth.com/
2. Enter domain: thesatelliteoflove.com
3. Verify discovery finds Gondulf endpoints
4. Complete authentication flow
5. Verify token received

Success Criteria:

• Discovery succeeds
• Authorization initiated
• Email code works
• Token exchange successful
• Profile information returned

2. IndieWebify.me

URL: https://indiewebify.me/ Why Critical: Common IndieWeb validation tool Test Flow:

1. Use Web Sign-in test
2. Enter domain: thesatelliteoflove.com
3. Complete authentication
4. Verify success message

Success Criteria:

• Endpoints discovered
• Authentication completes
• Validation passes

Tier 2: Real-World Clients (Should Pass)

3. Quill (Micropub Editor)

URL: https://quill.p3k.io/ Why Important: Popular Micropub client Test Flow:

1. Sign in with domain
2. Complete auth flow
3. Verify token works (even without Micropub endpoint)

Success Criteria:

• Authentication succeeds
• Token issued
• No breaking errors

4. Webmention.io

URL: https://webmention.io/ Why Important: Webmention service using IndieAuth Test Flow:

1. Sign up/sign in with domain
2. Complete authentication
3. Verify account created/accessed

Success Criteria:

• Auth flow completes
• Service recognizes authentication

Tier 3: Extended Testing (Nice to Have)

5. Indigenous (Mobile App)

Platform: iOS/Android Why Useful: Mobile client testing Note: Optional based on availability

6. Micropub Rocks Validator

URL: https://micropub.rocks/ Why Useful: Comprehensive endpoint testing Note: Tests auth even without Micropub

Test Execution Protocol

For Each Client Test

Pre-Test Setup

# Monitor production logs
docker logs -f gondulf --tail 50

# Verify DNS record
dig TXT _gondulf.thesatelliteoflove.com

# Check server health
curl https://gondulf.thesatelliteoflove.com/health

Test Execution

1. Document Initial State

   • Screenshot client interface
   • Note exact domain entered
   • Record timestamp

2. Discovery Phase

   • Verify client finds authorization endpoint
   • Check logs for discovery requests
   • Note any errors or warnings

3. Authorization Phase

   • Verify redirect to Gondulf
   • Check domain verification flow
   • Confirm email code delivery
   • Document consent screen

4. Token Phase

   • Verify code exchange
   • Check token generation logs
   • Confirm client receives token

5. Post-Auth Verification

   • Verify client shows authenticated state
   • Test any client-specific features
   • Check for error messages

Test Documentation

Create test report: /docs/reports/2025-11-24-client-testing-[client-name].md

# Client Testing Report: [Client Name]

**Date**: 2025-11-24
**Client**: [Name and URL]
**Version**: v1.0.0-rc.8
**Tester**: [Name]

## Test Results

### Summary
- **Result**: PASS/FAIL
- **Duration**: XX minutes
- **Issues Found**: None/Listed below

### Discovery Phase
- Endpoints discovered: YES/NO
- Discovery method: Link headers/HTML tags/.well-known
- Issues: None/Description

### Authorization Phase
- Redirect successful: YES/NO
- Domain verification: DNS/Email/Pre-verified
- Email code received: YES/NO (time: XX seconds)
- Consent shown: YES/NO
- Issues: None/Description

### Token Phase
- Code exchange successful: YES/NO
- Token received: YES/NO
- Token format correct: YES/NO
- Issues: None/Description

### Logs

[Relevant log entries]

### Screenshots
[Attach if relevant]

### Recommendations
[Any improvements needed]

Error Scenarios to Test

1. Invalid Redirect URI

• Modify redirect_uri after authorization
• Expect: Error response

2. Expired Authorization Code

• Wait >10 minutes before token exchange
• Expect: Error response

3. Wrong Domain

• Try authenticating with different domain
• Expect: Domain verification required

4. Invalid State Parameter

• Modify state parameter
• Expect: Error response

Performance Validation

Response Time Targets

• Discovery: <500ms
• Authorization page load: <1s
• Email delivery: <30s
• Token exchange: <500ms

Concurrency Test

• Multiple clients simultaneously
• Verify no session conflicts
• Check memory usage

Acceptance Criteria

Must Pass (P0)

• IndieAuth.com test client works end-to-end
• IndieWebify.me validation passes
• No critical errors in logs
• Response times within targets
• Security headers present

Should Pass (P1)

• At least one Micropub client works
• Webmention.io authentication works
• Error responses follow OAuth 2.0 spec
• Concurrent clients handled correctly

Nice to Have (P2)

• Mobile client tested
• 5+ different clients tested
• Performance under load validated

Security Considerations

During Testing

1. Use Production Domain: Test with actual domain, not localhost
2. Monitor Logs: Watch for any security warnings
3. Check Headers: Verify security headers on all responses
4. Test HTTPS: Ensure no HTTP fallback

Post-Testing

1. Review Logs: Check for any suspicious activity
2. Rotate Secrets: If any were exposed during testing
3. Document Issues: Any security concerns found

Rollback Plan

If critical issues found during testing:

1. Immediate Response

   • Document exact failure
   • Capture all logs
   • Screenshot error states

2. Assessment

   • Determine if issue is:
     • Configuration (fix without code change)
     • Minor bug (rc.9 candidate)
     • Major issue (requires design review)

3. Action

   • Configuration: Fix and retest
   • Minor bug: Create fix design, implement rc.9
   • Major issue: Halt release, return to design phase

Success Metrics

Quantitative

• Client compatibility: ≥80% (4 of 5 tested clients work)
• Response times: All <1 second
• Error rate: <1% of requests
• Uptime during testing: 100%

Qualitative

• No confusing UX issues
• Clear error messages
• Smooth authentication flow
• Professional appearance

Timeline

Day 1: Core Testing (4-6 hours)

1. Deploy rc.8 (30 minutes)
2. Verify DNS (15 minutes)
3. Test Tier 1 clients (2 hours)
4. Test Tier 2 clients (2 hours)
5. Document results (1 hour)

Day 2: Extended Testing (2-4 hours)

1. Error scenario testing (1 hour)
2. Performance validation (1 hour)
3. Additional clients (1 hour)
4. Final report (1 hour)

Day 3: Release Decision

1. Review all test results
2. Go/No-Go decision
3. Tag v1.0.0 or create rc.9

Output Artifacts

Required Documentation

1. /docs/reports/2025-11-24-client-testing-summary.md - Overall results
2. /docs/reports/2025-11-24-client-testing-[name].md - Per-client reports
3. /docs/architecture/v1.0.0-compatibility-matrix.md - Client compatibility table

Release Artifacts (If Proceeding)

1. Git tag: v1.0.0
2. GitHub release with notes
3. Updated README with tested clients
4. Announcement blog post (optional)

Decision Tree

Start Testing
    |
    v
DNS Verification Works?
    |
    +-- NO --> Fix DNS, restart
    |
    +-- YES
        |
        v
    IndieAuth.com Works?
        |
        +-- NO --> Critical failure, create rc.9
        |
        +-- YES
            |
            v
        IndieWebify.me Works?
            |
            +-- NO --> Investigate spec compliance
            |
            +-- YES
                |
                v
            2+ Other Clients Work?
                |
                +-- NO --> Document issues, assess impact
                |
                +-- YES
                    |
                    v
                RELEASE v1.0.0

Post-Release Monitoring

After v1.0.0 release:

First 24 Hours

• Monitor error rates
• Check memory usage
• Review user reports
• Verify backup working

First Week

• Track authentication success rate
• Collect client compatibility reports
• Document any new issues
• Plan v1.1.0 features

First Month

• Analyze usage patterns
• Review security logs
• Optimize performance
• Gather user feedback

Conclusion

This testing phase is the final validation before v1.0.0 release. With the DNS bug fixed in rc.8, the system should be fully functional. Successful completion of these tests will confirm production readiness and W3C IndieAuth specification compliance.

The structured approach ensures comprehensive validation while maintaining focus on the most critical clients. The clear success criteria and rollback plan provide confidence in the release decision.