Phil Skentelbery
f10d0679da
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>
4.4 KiB
4.4 KiB
IndieAuth Identity Page Architecture
Overview
An IndieAuth identity page serves as the authoritative source for a user's online identity in the IndieWeb ecosystem. This document defines the minimal requirements and best practices for creating a static HTML page that functions as an IndieAuth identity URL.
Purpose
The identity page serves three critical functions:
- Authentication Endpoint Discovery - Provides rel links to IndieAuth endpoints
- Identity Verification - Contains h-card microformats with user information
- Social Proof - Optional rel="me" links for identity consolidation
Technical Requirements
1. HTML Structure
DOCTYPE html5
├── head
│ ├── meta charset="utf-8"
│ ├── meta viewport (responsive)
│ ├── title (user's name)
│ ├── rel="authorization_endpoint"
│ ├── rel="token_endpoint"
│ └── optional: rel="micropub"
└── body
└── h-card
├── p-name (full name)
├── u-url (identity URL)
├── u-photo (optional avatar)
└── rel="me" links (optional)
2. IndieAuth Discovery
The page MUST include these link elements in the <head>:
<link rel="authorization_endpoint" href="https://indieauth.com/auth">
<link rel="token_endpoint" href="https://tokens.indieauth.com/token">
These endpoints:
- authorization_endpoint: Handles the OAuth 2.0 authorization flow
- token_endpoint: Issues access tokens for API access
3. Microformats2 h-card
The h-card provides machine-readable identity information:
<div class="h-card">
<h1 class="p-name">User Name</h1>
<a class="u-url" href="https://example.com" rel="me">https://example.com</a>
</div>
Required properties:
p-name: The person's full nameu-url: The canonical identity URL (must match the page URL)
Optional properties:
u-photo: Avatar image URLp-note: Brief biographyu-email: Contact email (consider privacy implications)
4. rel="me" Links
For identity consolidation and social proof:
<a href="https://github.com/username" rel="me">GitHub</a>
Best practices:
- Only include links to profiles you control
- Ensure reciprocal rel="me" links where possible
- Use HTTPS URLs whenever available
Security Considerations
1. HTTPS Requirement
- Identity URLs MUST use HTTPS
- All linked endpoints MUST use HTTPS
- Mixed content will break authentication flows
2. Content Security
- No inline JavaScript required or recommended
- Minimal inline CSS only if necessary
- No external dependencies for core functionality
3. Privacy
- Consider what information to make public
- Email addresses can attract spam
- Phone numbers should generally be avoided
Testing Strategy
1. IndieAuth Validation
- Test with https://indielogin.com/
- Verify endpoint discovery works
- Complete a full authentication flow
2. Microformats Validation
- Use https://indiewebify.me/
- Verify h-card is properly parsed
- Check all properties are detected
3. HTML Validation
- Validate with W3C validator
- Ensure semantic HTML5 compliance
- Check accessibility basics
Common Pitfalls
1. Missing or Wrong URLs
- Identity URL must be absolute and match the actual page URL
- Endpoints must be absolute URLs
- rel="me" links must be to HTTPS when available
2. Incorrect Microformats
- Missing required h-card properties
- Using old hCard format instead of h-card
- Nesting errors in microformat classes
3. Authentication Failures
- Using HTTP instead of HTTPS
- Incorrect or missing endpoint declarations
- Not including trailing slashes consistently
Minimal Implementation Checklist
- HTML5 DOCTYPE declaration
- UTF-8 character encoding
- Viewport meta tag for mobile
- Authorization endpoint link
- Token endpoint link
- h-card with p-name
- h-card with u-url matching page URL
- All URLs use HTTPS
- No broken links or empty hrefs
- Valid HTML5 structure
Reference Implementations
See /docs/examples/identity-page.html for a complete, working example that can be customized for any IndieAuth user.