phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
97 Commits 2 Branches 33 Tags
b46ab2264e8fce55fb69a9c72e497d68ee063c7b
Commit Graph

14 Commits

Author SHA1 Message Date
Phil Skentelbery
e589f5bd6c docs: Fix ADR numbering conflicts and create comprehensive documentation indices 
This commit resolves all documentation issues identified in the comprehensive review:

CRITICAL FIXES:
- Renumbered duplicate ADRs to eliminate conflicts:
  * ADR-022-migration-race-condition-fix → ADR-037
  * ADR-022-syndication-formats → ADR-038
  * ADR-023-microformats2-compliance → ADR-040
  * ADR-027-versioning-strategy-for-authorization-removal → ADR-042
  * ADR-030-CORRECTED-indieauth-endpoint-discovery → ADR-043
  * ADR-031-endpoint-discovery-implementation → ADR-044

- Updated all cross-references to renumbered ADRs in:
  * docs/projectplan/ROADMAP.md
  * docs/reports/v1.0.0-rc.5-migration-race-condition-implementation.md
  * docs/reports/2025-11-24-endpoint-discovery-analysis.md
  * docs/decisions/ADR-043-CORRECTED-indieauth-endpoint-discovery.md
  * docs/decisions/ADR-044-endpoint-discovery-implementation.md

- Updated README.md version from 1.0.0 to 1.1.0
- Tracked ADR-021-indieauth-provider-strategy.md in git

DOCUMENTATION IMPROVEMENTS:
- Created comprehensive INDEX.md files for all docs/ subdirectories:
  * docs/architecture/INDEX.md (28 documents indexed)
  * docs/decisions/INDEX.md (55 ADRs indexed with topical grouping)
  * docs/design/INDEX.md (phase plans and feature designs)
  * docs/standards/INDEX.md (9 standards with compliance checklist)
  * docs/reports/INDEX.md (57 implementation reports)
  * docs/deployment/INDEX.md (deployment guides)
  * docs/examples/INDEX.md (code samples and usage patterns)
  * docs/migration/INDEX.md (version migration guides)
  * docs/releases/INDEX.md (release documentation)
  * docs/reviews/INDEX.md (architectural reviews)
  * docs/security/INDEX.md (security documentation)

- Updated CLAUDE.md with complete folder descriptions including:
  * docs/migration/
  * docs/releases/
  * docs/security/

VERIFICATION:
- All ADR numbers now sequential and unique (50 total ADRs)
- No duplicate ADR numbers remain
- All cross-references updated and verified
- Documentation structure consistent and well-organized

These changes improve documentation discoverability, maintainability, and
ensure proper version tracking. All index files follow consistent format
with clear navigation guidance.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-25 13:28:56 -07:00
Phil Skentelbery
82bb1499d5 docs: Add v1.1.0 architecture and validation documentation 
- ADR-033: Database migration redesign
- ADR-034: Full-text search with FTS5
- ADR-035: Custom slugs in Micropub
- ADR-036: IndieAuth token verification method
- ADR-039: Micropub URL construction fix
- Implementation plan and decisions
- Architecture specifications
- Validation reports for implementation and search UI

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-25 10:39:58 -07:00
Phil Skentelbery
a7e0af9c2c docs: Add complete documentation for v1.0.0-rc.5 hotfix 
Complete architectural documentation for:
- Migration race condition fix with database locking
- IndieAuth endpoint discovery implementation
- Security considerations and migration guides

New documentation:
- ADR-030-CORRECTED: IndieAuth endpoint discovery decision
- ADR-031: Endpoint discovery implementation details
- Architecture docs on endpoint discovery
- Migration guide for removed TOKEN_ENDPOINT
- Security analysis of endpoint discovery
- Implementation and analysis reports
 2025-11-24 20:20:00 -07:00
Phil Skentelbery
2240414f22 docs: Add architect documentation for migration race condition fix 
Add comprehensive architectural documentation for the migration race
condition fix, including:

- ADR-022: Architectural decision record for the fix
- migration-race-condition-answers.md: All 23 Q&A answered
- migration-fix-quick-reference.md: Implementation checklist
- migration-race-condition-fix-implementation.md: Detailed guide

These documents guided the implementation in v1.0.0-rc.5.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-24 18:53:55 -07:00
Phil Skentelbery
1e1a917056 docs: Add architectural review for IndieAuth removal 2025-11-24 18:15:27 -07:00
Phil Skentelbery
a3bac86647 feat: Complete IndieAuth server removal (Phases 2-4) 
Completed all remaining phases of ADR-030 IndieAuth provider removal.
StarPunk no longer acts as an authorization server - all IndieAuth
operations delegated to external providers.

Phase 2 - Remove Token Issuance:
- Deleted /auth/token endpoint
- Removed token_endpoint() function from routes/auth.py
- Deleted tests/test_routes_token.py

Phase 3 - Remove Token Storage:
- Deleted starpunk/tokens.py module entirely
- Created migration 004 to drop tokens and authorization_codes tables
- Deleted tests/test_tokens.py
- Removed all internal token CRUD operations

Phase 4 - External Token Verification:
- Created starpunk/auth_external.py module
- Implemented verify_external_token() for external IndieAuth providers
- Updated Micropub endpoint to use external verification
- Added TOKEN_ENDPOINT configuration
- Updated all Micropub tests to mock external verification
- HTTP timeout protection (5s) for external requests

Additional Changes:
- Created migration 003 to remove code_verifier from auth_state
- Fixed 5 migration tests that referenced obsolete code_verifier column
- Updated 11 Micropub tests for external verification
- Fixed test fixture and app context issues
- All 501 tests passing

Breaking Changes:
- Micropub clients must use external IndieAuth providers
- TOKEN_ENDPOINT configuration now required
- Existing internal tokens invalid (tables dropped)

Migration Impact:
- Simpler codebase: -500 lines of code
- Fewer database tables: -2 tables (tokens, authorization_codes)
- More secure: External providers handle token security
- More maintainable: Less authentication code to maintain

Standards Compliance:
- W3C IndieAuth specification
- OAuth 2.0 Bearer token authentication
- IndieWeb principle: delegate to external services

Related:
- ADR-030: IndieAuth Provider Removal Strategy
- ADR-050: Remove Custom IndieAuth Server
- Migration 003: Remove code_verifier from auth_state
- Migration 004: Drop tokens and authorization_codes tables

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-24 17:23:46 -07:00
Phil Skentelbery
2b2849a58d docs: Add database migration architecture and conflict resolution documentation 
Documents the diagnosis and resolution of database migration detection conflicts
 2025-11-24 13:27:19 -07:00
Phil Skentelbery
2eaf67279d docs: Standardize all IndieAuth spec references to W3C URL 
- Updated 42 references from indieauth.spec.indieweb.org to www.w3.org/TR/indieauth
- Ensures consistency across all documentation
- Points to the authoritative W3C specification
- No functional changes, documentation update only

Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-24 11:54:04 -07:00
Phil Skentelbery
800bc1069d docs: Update architecture overview to reflect v0.9.5 implementation 
Comprehensively updated docs/architecture/overview.md to document the
actual v0.9.5 implementation instead of aspirational V1 features.

Major Changes:

1. Executive Summary
   - Added version tag (v0.9.5) and status (Pre-V1 Release)
   - Updated tech stack: Python 3.11, uv, Gunicorn, Gitea Actions
   - Added deployment context (container-based, CI/CD)

2. Route Documentation
   - Public routes: Documented actual routes (/, /note/<slug>, /feed.xml, /health)
   - Admin routes: Updated from /admin/* to /auth/* (v0.9.2 change)
   - Added development routes (/dev/login)
   - Clearly marked implemented vs. planned routes

3. API Layer Reality Check
   - Notes API: Marked as NOT IMPLEMENTED (optional, deferred to V2)
   - Micropub endpoint: Marked as NOT IMPLEMENTED (critical V1 blocker)
   - RSS feed: Marked as IMPLEMENTED with full feature list (v0.6.0)

4. Authentication Flow Updates
   - Documented PKCE implementation (v0.8.0)
   - Updated IndieLogin flow to use /authorize endpoint (v0.9.4)
   - Added trailing slash normalization (v0.9.1)
   - Documented session token hashing (SHA-256)
   - Updated cookie name (starpunk_session, v0.5.1)
   - Corrected code verification endpoint usage

5. Database Schema
   - Added schema_migrations table (v0.9.0)
   - Added code_verifier to auth_state (v0.8.0)
   - Documented automatic migration system
   - Added session metadata fields (user_agent, ip_address)
   - Updated indexes for performance

6. Container Deployment (NEW)
   - Multi-stage Containerfile documentation
   - Gunicorn WSGI server configuration
   - Health check endpoint
   - CI/CD pipeline (Gitea Actions)
   - Volume persistence strategy

7. Implementation Status Section (NEW)
   - Comprehensive list of implemented features (v0.3.0-v0.9.5)
   - Clear documentation of unimplemented features
   - Micropub marked as critical V1 blocker
   - Standards validation status (partial)

8. Success Metrics
   - Updated with actual achievements
   - 70% complete toward V1
   - Container deployment working
   - Automated migrations implemented

Security documentation now accurately reflects PKCE implementation,
session token hashing, and correct IndieLogin.com API usage.

All route tables, data flow diagrams, and examples updated to match
v0.9.5 codebase reality.

Related: Architect validation report identified need to update
architecture docs to reflect actual implementation vs. planned features.
 2025-11-24 11:03:44 -07:00
Phil Skentelbery
066cde8c46 docs: Extract and organize CLAUDE.MD content, restructure documentation 
This commit performs comprehensive documentation reorganization:

1. Extracted testing checklist from CLAUDE.MD to docs/standards/testing-checklist.md
   - Consolidated manual testing checklist
   - Added validation tools and resources
   - Created pre-release validation workflow

2. Streamlined CLAUDE.md to lightweight operational instructions
   - Python environment setup (uv)
   - Agent-developer protocol
   - Key documentation references
   - Removed redundant content (already in other docs)

3. Removed CLAUDE.MD (uppercase) - content was redundant
   - All content already exists in architecture/overview.md and projectplan docs
   - Only unique content (testing checklist) was extracted

4. Moved root documentation files to appropriate locations:
   - CONTAINER_IMPLEMENTATION_SUMMARY.md -> docs/reports/2025-11-19-container-implementation-summary.md
   - QUICKFIX-AUTH-LOOP.md -> docs/reports/2025-11-18-quickfix-auth-loop.md
   - TECHNOLOGY-STACK-SUMMARY.md -> docs/architecture/technology-stack-legacy.md
   - TODO_TEST_UPDATES.md -> docs/reports/2025-11-19-todo-test-updates.md

5. Consolidated design folders:
   - Moved all docs/designs/ content into docs/design/
   - Renamed PHASE-5-EXECUTIVE-SUMMARY.md to phase-5-executive-summary.md (consistent naming)
   - Removed empty docs/designs/ directory

6. Added ADR-021: IndieAuth Provider Strategy
   - Documents decision to build own IndieAuth provider
   - Explains rationale and trade-offs

Repository root now contains only: README.md, CLAUDE.md, CHANGELOG.md

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-24 10:17:50 -07:00
Phil Skentelbery
dd85917988 docs: add IndieAuth client identification analysis and decision 
Architect analysis identified the root cause of 'client_id is not
registered' error: h-app microformat is hidden from parsers.

Includes:
- Complete diagnosis of IndieAuth client registration issue
- ADR-006: IndieAuth Client Identification decision record
- Implementation guidelines for developer

Developer task: Remove hidden attributes from h-app div.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-19 14:09:14 -07:00
Phil Skentelbery
68669b9a6a docs: add reference IndieAuth identity page implementation 
Add minimal, production-ready static HTML identity page as reference
implementation for IndieAuth authentication.

Includes:
- Complete identity-page.html with h-card and IndieAuth endpoints
- Architectural documentation and rationale
- ADR-010: Static Identity Page decision record
- Customization guide for users

The example is zero-dependency, copy-paste ready, and guaranteed to
work with IndieLogin.com and StarPunk. Pre-configured for
thesatelliteoflove.com as working example.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-19 13:03:49 -07:00
Phil Skentelbery
6863bcae67 docs: add Phase 5 design and architectural review documentation 
- Add ADR-014: RSS Feed Implementation
- Add ADR-015: Phase 5 Implementation Approach
- Add Phase 5 design documents (RSS and container)
- Add pre-implementation review
- Add RSS and container validation reports
- Add architectural approval for v0.6.0 release

Architecture reviews confirm 98/100 (RSS) and 96/100 (container) scores.
Phase 5 approved for production deployment.

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

Co-Authored-By: Claude <noreply@anthropic.com>
 2025-11-19 10:30:55 -07:00
Phil Skentelbery
a68fd570c7 that initial commit 2025-11-18 19:21:31 -07:00