phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3222620cee138d5d788a8ad56338e209b1b18c1e
StarPunk/docs/design/v1.0.0/ADR-025-implementation-summary.md
Phil Skentelbery f10d0679da feat(tags): Add database schema and tags module (v1.3.0 Phase 1) 
Implements tag/category system backend following microformats2 p-category specification.

Database changes:
- Migration 008: Add tags and note_tags tables
- Normalized tag storage (case-insensitive lookup, display name preserved)
- Indexes for performance

New module:
- starpunk/tags.py: Tag management functions
  - normalize_tag: Normalize tag strings
  - get_or_create_tag: Get or create tag records
  - add_tags_to_note: Associate tags with notes (replaces existing)
  - get_note_tags: Retrieve note tags (alphabetically ordered)
  - get_tag_by_name: Lookup tag by normalized name
  - get_notes_by_tag: Get all notes with specific tag
  - parse_tag_input: Parse comma-separated tag input

Model updates:
- Note.tags property (lazy-loaded, prefer pre-loading in routes)
- Note.to_dict() add include_tags parameter

CRUD updates:
- create_note() accepts tags parameter
- update_note() accepts tags parameter (None = no change, [] = remove all)

Micropub integration:
- Pass tags to create_note() (tags already extracted by extract_tags())
- Return tags in q=source response

Per design doc: docs/design/v1.3.0/microformats-tags-design.md

Generated with Claude Code

Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-10 11:24:23 -07:00

6.8 KiB
Raw Blame History

ADR-025 Implementation Summary

Quick Reference for Developer Date: 2025-11-19 Version Target: 0.8.0

What You Need to Know

This is a critical bug fix that implements IndieAuth authentication correctly by following the IndieLogin.com API specification. The previous attempts (v0.7.0 OAuth metadata, v0.7.1 h-app visibility) were based on misunderstanding the requirements.

Documentation Structure

All documentation has been separated into proper categories:

1. Architecture Decision Record (ADR-025)

File: /home/phil/Projects/starpunk/docs/decisions/ADR-025-indieauth-pkce-authentication.md

What it contains:

  • Context: Why we need this change
  • Decision: What we're doing (PKCE implementation)
  • Rationale: Why this approach is correct
  • Consequences: Benefits and trade-offs
  • NO implementation details (those are in the design doc)

2. Design Document (Complete Technical Specifications)

File: /home/phil/Projects/starpunk/docs/designs/indieauth-pkce-authentication.md

What it contains:

  • Complete authentication flow diagrams
  • PKCE implementation specifications
  • Database schema changes
  • Exact code changes with line numbers
  • Code to remove with line numbers
  • Testing strategy and test code
  • Error handling specifications
  • Security considerations
  • Complete implementation guide with step-by-step instructions

This is your primary implementation reference.

3. Versioning Guidance

File: /home/phil/Projects/starpunk/docs/reports/ADR-025-versioning-guidance.md

What it contains:

  • Version number decision: 0.8.0
  • Git tag handling (keep all existing tags)
  • CHANGELOG update instructions
  • Rationale for versioning choice
  • What to do with v0.7.0 and v0.7.1 tags

Quick Implementation Checklist

Follow the design document for detailed steps. This is just a high-level checklist:

Pre-Implementation

  • Read ADR-025 (architectural decision)
  • Read full design document
  • Review versioning guidance
  • Understand PKCE flow

Database

  • Add code_verifier column to auth_state table
  • Test migration

Code Changes

  • Add PKCE functions to starpunk/auth.py
  • Update _verify_state_token() to return verifier
  • Update initiate_login() with PKCE
  • Update handle_callback() with PKCE and iss validation
  • Update callback route to extract and pass iss
  • Update logging to redact code_verifier

Code Removal

  • Remove OAuth metadata endpoint from starpunk/routes/public.py
  • Remove h-app microformats from templates/base.html
  • Remove indieauth-metadata link from templates/base.html

Testing

  • Run unit tests for PKCE functions
  • Run integration tests for auth flow
  • Manual testing with IndieLogin.com
  • Verify logs show PKCE parameters (redacted)
  • Check database for code_verifier storage

Versioning

  • Update __version__ to "0.8.0" in starpunk/__init__.py
  • Update __version_info__ to (0, 8, 0)
  • Update CHANGELOG.md with v0.8.0 entry
  • Add notes to v0.7.0 and v0.7.1 CHANGELOG entries
  • Create git tag v0.8.0
  • Do NOT delete v0.7.0 or v0.7.1 tags

Documentation

  • Update ADR-016 status to "Superseded by ADR-025"
  • Update ADR-017 status to "Superseded by ADR-025"
  • Add implementation note to ADR-005

Key Points

What's Wrong Now

  1. Missing PKCE - IndieLogin.com requires it, we don't have it
  2. Wrong endpoints - Using /auth instead of /authorize and /token
  3. Unnecessary features - OAuth metadata and h-app not needed

What We're Fixing

  1. Add PKCE - Generate verifier/challenge, store, validate
  2. Correct endpoints - Use /authorize and /token
  3. Remove cruft - Delete OAuth metadata and h-app
  4. Add iss validation - Security best practice

Why v0.8.0?

  • Not v0.7.2: Too substantial for PATCH (database change, PKCE implementation, removals)
  • Not v1.0.0: Not ready for stable (V1 features not complete)
  • Yes v0.8.0: Appropriate MINOR increment for significant change during 0.x phase

Why Keep v0.7.0 and v0.7.1 Tags?

  • Git history integrity
  • Can't "un-release" versions
  • CHANGELOG explains what didn't work
  • Shows progression of understanding

File Reference

Read in this order:

  1. This file (you are here) - Overview
  2. /home/phil/Projects/starpunk/docs/decisions/ADR-025-indieauth-pkce-authentication.md - Architectural decision
  3. /home/phil/Projects/starpunk/docs/designs/indieauth-pkce-authentication.md - Full implementation guide
  4. /home/phil/Projects/starpunk/docs/reports/ADR-025-versioning-guidance.md - Versioning details

Standards Reference:

  • /home/phil/Projects/starpunk/docs/standards/versioning-strategy.md - Semantic versioning rules
  • /home/phil/Projects/starpunk/docs/standards/git-branching-strategy.md - Git workflow

Critical Files to Modify

Python Code

/home/phil/Projects/starpunk/starpunk/auth.py
/home/phil/Projects/starpunk/starpunk/routes/auth.py
/home/phil/Projects/starpunk/starpunk/routes/public.py (deletions)
/home/phil/Projects/starpunk/starpunk/__init__.py (version)

Templates

/home/phil/Projects/starpunk/templates/base.html (deletions)

Database

Schema: auth_state table (add code_verifier column)

Documentation

/home/phil/Projects/starpunk/CHANGELOG.md (updates)
/home/phil/Projects/starpunk/docs/decisions/ADR-016-indieauth-client-discovery.md (status)
/home/phil/Projects/starpunk/docs/decisions/ADR-017-oauth-client-metadata-document.md (status)
/home/phil/Projects/starpunk/docs/decisions/ADR-005-indielogin-authentication.md (note)

Success Criteria

You're done when:

  1. User can log in via IndieLogin.com
  2. PKCE parameters visible in authorization URL
  3. code_verifier stored in database
  4. Token exchange succeeds with code_verifier
  5. All tests pass
  6. Version is 0.8.0
  7. CHANGELOG updated
  8. ADR statuses updated

Getting Help

If authentication still fails:

  1. Check logs for PKCE parameters (should be redacted but visible)
  2. Verify database has code_verifier column
  3. Check authorization URL has code_challenge and code_challenge_method=S256
  4. Verify token exchange POST includes code_verifier
  5. Check IndieLogin.com response in logs

Key debugging points:

  • initiate_login(): Should generate verifier and challenge
  • Database: Should store verifier with state
  • Authorization URL: Should include challenge
  • handle_callback(): Should retrieve verifier
  • Token exchange: Should send verifier
  • IndieLogin.com: Should return {"me": "url"}

Questions?

Refer to:

  • Design document for "how"
  • ADR-025 for "why"
  • Versioning guidance for "what version"

All documentation follows the project principle: Every line must justify its existence.

Author: StarPunk Architect Status: Ready for Implementation Priority: Critical (authentication broken in production)

Reference in New Issue View Git Blame Copy Permalink