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
```bash
# 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`

```markdown
# 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.