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

205 lines
6.8 KiB
Markdown
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