From d3fa5b7a2ae60ce709c5aa2279f970ddbd7a36b9 Mon Sep 17 00:00:00 2001 From: Phil Date: Sat, 31 Oct 2026 11:17:51 -0600 Subject: [PATCH 1/2] chore: Recover v1.6.0-rc.2 source from production image The v1.6.0 work (webmentions, reply contexts, rate limiter, migration 010) was built and deployed as git.thesatelliteoflove.com/phil/starpunk:v1.6.0-rc.2 but never committed. This restores the application code from /app in the running container so later work builds on what production runs. Tests and docs for v1.6.0 were not in the image and are not recovered. Co-Authored-By: Claude Opus 5.5 --- migrations/010_add_webmentions.sql | 79 +++ requirements.txt | 3 + starpunk/__init__.py | 112 +++- starpunk/config.py | 15 + starpunk/media.py | 197 +++++-- starpunk/models.py | 2 + starpunk/notes.py | 145 ++++- starpunk/rate_limiter.py | 210 +++++++ starpunk/reply_context.py | 329 +++++++++++ starpunk/routes/__init__.py | 6 +- starpunk/routes/admin.py | 224 ++++++- starpunk/routes/public.py | 36 +- starpunk/routes/webmention.py | 272 +++++++++ starpunk/webmention_processor.py | 373 ++++++++++++ starpunk/webmention_queries.py | 295 +++++++++ starpunk/webmention_sender.py | 198 +++++++ starpunk/webmention_ssrf.py | 113 ++++ starpunk/webmention_worker.py | 787 +++++++++++++++++++++++++ static/css/style.css | 262 ++++++++ templates/admin/dashboard.html | 22 + templates/admin/webmention_detail.html | 108 ++++ templates/admin/webmentions.html | 125 ++++ templates/base.html | 9 +- templates/note.html | 138 +++++ 24 files changed, 3982 insertions(+), 78 deletions(-) create mode 100644 migrations/010_add_webmentions.sql create mode 100644 starpunk/rate_limiter.py create mode 100644 starpunk/reply_context.py create mode 100644 starpunk/routes/webmention.py create mode 100644 starpunk/webmention_processor.py create mode 100644 starpunk/webmention_queries.py create mode 100644 starpunk/webmention_sender.py create mode 100644 starpunk/webmention_ssrf.py create mode 100644 starpunk/webmention_worker.py create mode 100644 templates/admin/webmention_detail.html create mode 100644 templates/admin/webmentions.html diff --git a/migrations/010_add_webmentions.sql b/migrations/010_add_webmentions.sql new file mode 100644 index 0000000..2b1b6d2 --- /dev/null +++ b/migrations/010_add_webmentions.sql @@ -0,0 +1,79 @@ +-- Migration 010: Add Webmention support +-- Version: 1.6.0 +-- Per ADR-063: Webmention Implementation +-- Per W3C Webmention Recommendation + +-- Add reply-to support to notes table +ALTER TABLE notes ADD COLUMN in_reply_to TEXT; + +-- Incoming webmentions storage +CREATE TABLE IF NOT EXISTS webmentions ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + source_url TEXT NOT NULL, + target_url TEXT NOT NULL, + target_note_id INTEGER, + mention_type TEXT NOT NULL DEFAULT 'mention' + CHECK (mention_type IN ('reply', 'like', 'repost', 'bookmark', 'mention')), + author_name TEXT, + author_url TEXT, + author_photo TEXT, + content_snippet TEXT, + validation_status TEXT NOT NULL DEFAULT 'pending' + CHECK (validation_status IN ('pending', 'valid', 'invalid', 'error')), + moderation_status TEXT NOT NULL DEFAULT 'pending' + CHECK (moderation_status IN ('pending', 'approved', 'hidden', 'deleted')), + validation_error TEXT, + validated_at TIMESTAMP, + received_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + FOREIGN KEY (target_note_id) REFERENCES notes(id) ON DELETE SET NULL, + UNIQUE(source_url, target_url) +); + +CREATE INDEX IF NOT EXISTS idx_webmentions_target_note ON webmentions(target_note_id); +CREATE INDEX IF NOT EXISTS idx_webmentions_moderation ON webmentions(moderation_status); +CREATE INDEX IF NOT EXISTS idx_webmentions_validation ON webmentions(validation_status); +CREATE INDEX IF NOT EXISTS idx_webmentions_received ON webmentions(received_at DESC); + +-- Outgoing webmention queue +CREATE TABLE IF NOT EXISTS webmention_queue ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + source_url TEXT NOT NULL, + target_url TEXT NOT NULL, + source_note_id INTEGER, + endpoint_url TEXT, + status TEXT NOT NULL DEFAULT 'pending' + CHECK (status IN ('pending', 'sending', 'sent', 'failed', 'no_endpoint')), + retry_count INTEGER NOT NULL DEFAULT 0, + next_retry_at TIMESTAMP, + last_error TEXT, + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + started_at TIMESTAMP, + sent_at TIMESTAMP, + FOREIGN KEY (source_note_id) REFERENCES notes(id) ON DELETE CASCADE, + UNIQUE(source_url, target_url) +); + +CREATE INDEX IF NOT EXISTS idx_webmention_queue_status ON webmention_queue(status); +CREATE INDEX IF NOT EXISTS idx_webmention_queue_retry ON webmention_queue(next_retry_at); +CREATE INDEX IF NOT EXISTS idx_webmention_queue_note ON webmention_queue(source_note_id); + +-- Cached reply contexts +CREATE TABLE IF NOT EXISTS reply_contexts ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + url TEXT UNIQUE NOT NULL, + title TEXT, + content_snippet TEXT, + published_at TIMESTAMP, + author_name TEXT, + author_url TEXT, + author_photo TEXT, + site_name TEXT, + fetch_status TEXT NOT NULL DEFAULT 'pending' + CHECK (fetch_status IN ('pending', 'fetched', 'error')), + fetch_error TEXT, + fetched_at TIMESTAMP, + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP +); + +CREATE INDEX IF NOT EXISTS idx_reply_contexts_url ON reply_contexts(url); diff --git a/requirements.txt b/requirements.txt index 04aa93e..4aeed68 100644 --- a/requirements.txt +++ b/requirements.txt @@ -36,3 +36,6 @@ Pillow==10.1.* # HEIC/HEIF Support (v1.4.2 - iPhone photos) pillow-heif==0.18.* + +# HTML Sanitization (v1.6.0 - Webmention content) +nh3==0.2.* diff --git a/starpunk/__init__.py b/starpunk/__init__.py index 8abe228..a0cadeb 100644 --- a/starpunk/__init__.py +++ b/starpunk/__init__.py @@ -156,6 +156,10 @@ def create_app(config=None): configure_cache(max_size=max_size, ttl=ttl) app.logger.info(f"Feed cache enabled (max_size={max_size}, ttl={ttl}s)") + # Initialize rate limiters (v1.6.0 Phase 2) + from starpunk.rate_limiter import init_rate_limiters + init_rate_limiters(app) + # Initialize FTS index if needed from pathlib import Path from starpunk.search import has_fts_table, rebuild_fts_index @@ -211,12 +215,77 @@ def create_app(config=None): return {'author': author} + # Template filter - URL to color for facepile (v1.6.0) + @app.template_filter('url_to_color') + def url_to_color_filter(url): + """ + Generate consistent color from URL hash for facepile initials + + Per display-moderation.md design: Hash URL to generate deterministic + color for facepile fallback initials. + + Args: + url: Author URL or any string + + Returns: + CSS color string (hex format) + """ + import hashlib + + if not url: + return '#6B7280' # Gray fallback + + # Hash the URL to get consistent color + hash_value = int(hashlib.md5(url.encode()).hexdigest()[:6], 16) + + # Generate pleasant, readable colors + # Use HSL-style generation for better color distribution + hue = hash_value % 360 + saturation = 65 # Medium saturation for readability + lightness = 50 # Medium lightness + + # Convert HSL to RGB (simplified) + def hsl_to_rgb(h, s, l): + s = s / 100.0 + l = l / 100.0 + c = (1 - abs(2 * l - 1)) * s + x = c * (1 - abs((h / 60) % 2 - 1)) + m = l - c / 2 + + if h < 60: + r, g, b = c, x, 0 + elif h < 120: + r, g, b = x, c, 0 + elif h < 180: + r, g, b = 0, c, x + elif h < 240: + r, g, b = 0, x, c + elif h < 300: + r, g, b = x, 0, c + else: + r, g, b = c, 0, x + + return int((r + m) * 255), int((g + m) * 255), int((b + m) * 255) + + r, g, b = hsl_to_rgb(hue, saturation, lightness) + return f'#{r:02x}{g:02x}{b:02x}' + # Request middleware - Add correlation ID to each request @app.before_request def before_request(): """Add correlation ID to request context for tracing""" add_correlation_id() + # Response middleware - Add webmention Link header (v1.6.0) + @app.after_request + def add_webmention_headers(response): + """Add webmention Link header to HTML responses""" + if (app.config.get('WEBMENTION_ENABLED', True) and + response.content_type and + 'text/html' in response.content_type): + response.headers['Link'] = '; rel="webmention"' + return response + # Register centralized error handlers from starpunk.errors import register_error_handlers @@ -237,6 +306,32 @@ def create_app(config=None): if hasattr(app, 'memory_monitor') and app.memory_monitor.is_alive(): app.memory_monitor.stop() + # Start webmention worker thread (v1.6.0 Phase 2) + # Per background-worker.md: Skip in test mode + if app.config.get('WEBMENTION_WORKER_ENABLED', True) and not app.config.get('TESTING', False): + from starpunk.webmention_worker import WebmentionWorker + webmention_worker = WebmentionWorker( + db_path=app.config['DATABASE_PATH'], + site_url=app.config['SITE_URL'], + poll_interval=app.config.get('WEBMENTION_POLL_INTERVAL', 10), + error_backoff=app.config.get('WEBMENTION_ERROR_BACKOFF', 60), + batch_size=app.config.get('WEBMENTION_BATCH_SIZE', 5), + auto_approve=app.config.get('WEBMENTION_AUTO_APPROVE', True) + ) + webmention_worker.start() + app.webmention_worker = webmention_worker + app.logger.info( + f"Webmention worker started " + f"(poll_interval={webmention_worker.poll_interval}s, " + f"batch_size={webmention_worker.batch_size})" + ) + + # Register cleanup handler + @app.teardown_appcontext + def cleanup_webmention_worker(error=None): + if hasattr(app, 'webmention_worker') and app.webmention_worker.is_alive(): + app.webmention_worker.stop() + # Health check endpoint for containers and monitoring @app.route("/health") def health_check(): @@ -322,15 +417,24 @@ def create_app(config=None): else: # Basic mode - just return 200 OK (for load balancers) # No authentication required, minimal checks - return jsonify({ + response = { "status": "ok", "version": app.config.get("VERSION", __version__) - }), 200 + } + + # Add webmention worker stats if enabled (v1.6.0 Phase 2) + if hasattr(app, 'webmention_worker'): + try: + response['webmention_worker'] = app.webmention_worker.get_stats() + except Exception as e: + app.logger.debug(f"Failed to get webmention worker stats: {e}") + + return jsonify(response), 200 return app # Package version (Semantic Versioning 2.0.0) # See docs/standards/versioning-strategy.md for details -__version__ = "1.5.0" -__version_info__ = (1, 5, 0) +__version__ = "1.6.0" +__version_info__ = (1, 6, 0) diff --git a/starpunk/config.py b/starpunk/config.py index 62ac68a..c38be42 100644 --- a/starpunk/config.py +++ b/starpunk/config.py @@ -110,6 +110,21 @@ def load_config(app, config_override=None): app.config["DEBUG_FILE_MAX_AGE_DAYS"] = int(os.getenv("DEBUG_FILE_MAX_AGE_DAYS", "7")) app.config["DEBUG_FILE_MAX_SIZE_MB"] = int(os.getenv("DEBUG_FILE_MAX_SIZE_MB", "100")) + # Webmention configuration (v1.6.0) + app.config["WEBMENTION_ENABLED"] = os.getenv("WEBMENTION_ENABLED", "true").lower() == "true" + app.config["WEBMENTION_WORKER_ENABLED"] = os.getenv("WEBMENTION_WORKER_ENABLED", "true").lower() == "true" + app.config["WEBMENTION_POLL_INTERVAL"] = int(os.getenv("WEBMENTION_POLL_INTERVAL", "10")) + app.config["WEBMENTION_ERROR_BACKOFF"] = int(os.getenv("WEBMENTION_ERROR_BACKOFF", "60")) + app.config["WEBMENTION_BATCH_SIZE"] = int(os.getenv("WEBMENTION_BATCH_SIZE", "5")) + app.config["WEBMENTION_AUTO_APPROVE"] = os.getenv("WEBMENTION_AUTO_APPROVE", "true").lower() == "true" + + # Webmention rate limiting (v1.6.0 Phase 2) + app.config["WEBMENTION_RATE_LIMIT_ENABLED"] = os.getenv("WEBMENTION_RATE_LIMIT_ENABLED", "true").lower() == "true" + app.config["WEBMENTION_RATE_LIMIT_IP"] = int(os.getenv("WEBMENTION_RATE_LIMIT_IP", "60")) + app.config["WEBMENTION_RATE_LIMIT_DOMAIN"] = int(os.getenv("WEBMENTION_RATE_LIMIT_DOMAIN", "10")) + app.config["WEBMENTION_RATE_LIMIT_WINDOW"] = int(os.getenv("WEBMENTION_RATE_LIMIT_WINDOW", "60")) + app.config["TRUSTED_PROXY"] = os.getenv("TRUSTED_PROXY", "false").lower() == "true" + # Apply overrides if provided if config_override: app.config.update(config_override) diff --git a/starpunk/media.py b/starpunk/media.py index c152f78..373c19c 100644 --- a/starpunk/media.py +++ b/starpunk/media.py @@ -14,15 +14,21 @@ Debug file management (v1.5.0 Phase 2): - Debug file saving disabled by default - Automatic cleanup of old debug files - Size limit enforcement + +Memory-safe image processing (v1.5.1): +- Early downscale for large images (>4096px) to prevent OOM +- PIL Image passed through pipeline (not bytes) to avoid memory copies +- Explicit memory cleanup after processing steps """ from PIL import Image, ImageOps from pathlib import Path from datetime import datetime, timedelta +import time import uuid import io import shutil -from typing import Optional, List, Dict, Tuple +from typing import Optional, List, Dict, Tuple, Union from flask import current_app # HEIC/HEIF support - import registers with Pillow automatically @@ -50,6 +56,11 @@ MIN_QUALITY = 70 # Minimum JPEG quality before rejection (v1.4. MIN_DIMENSION = 640 # Minimum dimension before rejection (v1.4.0) MAX_IMAGES_PER_NOTE = 4 +# Memory safety limits (v1.5.1 - fix for OOM on large phone images) +# Early downscale very large images to prevent memory exhaustion +# A 4096x4096 image = 50MB uncompressed, manageable per worker +MEMORY_SAFE_DIMENSION = 4096 # Downscale to this before heavy processing + # Variant specifications (v1.4.0 Phase 2) VARIANT_SPECS = { 'thumb': {'size': (150, 150), 'crop': True}, @@ -82,21 +93,22 @@ def get_optimization_params(file_size: int) -> Tuple[int, int]: return (1280, 85) -def validate_image(file_data: bytes, filename: str) -> Tuple[bytes, str, int, int]: +def validate_image(file_data: bytes, filename: str) -> Tuple[Image.Image, str, int, int]: """ - Validate image file + Validate image file and return PIL Image for memory-efficient processing Per Q11: Validate MIME type using Pillow - Per Q6: Reject if >50MB or >4096px (updated v1.4.0) + Per Q6: Reject if >50MB or >12000px Per v1.4.2: Convert HEIC to JPEG (browsers cannot display HEIC) + Per v1.5.1: Return PIL Image (not bytes) to avoid memory copies Args: file_data: Raw file bytes filename: Original filename Returns: - Tuple of (file_data, mime_type, width, height) - Note: file_data may be converted (e.g., HEIC to JPEG) + Tuple of (pil_image, mime_type, original_width, original_height) + Note: Image may be downscaled for memory safety but original dimensions returned Raises: ValueError: If file is invalid @@ -150,40 +162,34 @@ def validate_image(file_data: bytes, filename: str) -> Tuple[bytes, str, int, in else: raise ValueError(f"Invalid or corrupted image: {e}") + # Store original format before any conversions + original_format = img.format + # HEIC/HEIF conversion (v1.4.2) # HEIC cannot be displayed in browsers, convert to JPEG - if img.format in ('HEIF', 'HEIC'): + if original_format in ('HEIF', 'HEIC'): if not HEIC_SUPPORTED: raise ValueError( "HEIC/HEIF images require pillow-heif library. " "Please convert to JPEG before uploading." ) - # Convert HEIC to JPEG in memory - output = io.BytesIO() # Convert to RGB if needed (HEIC may have alpha channel) if img.mode in ('RGBA', 'P'): img = img.convert('RGB') - img.save(output, format='JPEG', quality=95) - output.seek(0) - # Re-open as JPEG for further processing - file_data = output.getvalue() - img = Image.open(io.BytesIO(file_data)) + # Mark format as JPEG for later processing + original_format = 'JPEG' # MPO (Multi-Picture Object) conversion (v1.4.2) - # MPO is used by iPhones for depth/portrait photos - extract primary image as JPEG - if img.format == 'MPO': - output = io.BytesIO() + # MPO is used by iPhones for depth/portrait photos - extract primary image + if original_format == 'MPO': # Convert to RGB if needed if img.mode in ('RGBA', 'P'): img = img.convert('RGB') - img.save(output, format='JPEG', quality=95) - output.seek(0) - file_data = output.getvalue() - img = Image.open(io.BytesIO(file_data)) + original_format = 'JPEG' # Check format is allowed - if img.format: - format_lower = img.format.lower() + if original_format: + format_lower = original_format.lower() mime_type = f'image/{format_lower}' # Special case: JPEG format can be reported as 'jpeg' @@ -195,26 +201,29 @@ def validate_image(file_data: bytes, filename: str) -> Tuple[bytes, str, int, in try: current_app.logger.warning( f'Media upload rejected format: filename="{filename}", ' - f'detected_format="{img.format}", mime_type="{mime_type}"' + f'detected_format="{original_format}", mime_type="{mime_type}"' ) except RuntimeError: pass # Outside app context - raise ValueError(f"Invalid image format '{img.format}'. Accepted: JPEG, PNG, GIF, WebP") + raise ValueError(f"Invalid image format '{original_format}'. Accepted: JPEG, PNG, GIF, WebP") else: raise ValueError("Could not determine image format") + # Store original dimensions before any resizing + orig_width, orig_height = img.size + # Check dimensions (v1.4.2: increased to 12000px to support modern phone cameras) - # Images will be resized by optimize_image() anyway - width, height = img.size - if max(width, height) > MAX_DIMENSION: + if max(orig_width, orig_height) > MAX_DIMENSION: raise ValueError(f"Image dimensions too large. Maximum is {MAX_DIMENSION}x{MAX_DIMENSION} pixels") # Check for animated GIF (v1.4.0) # Animated GIFs cannot be resized, so reject if >10MB - if img.format == 'GIF': + is_animated_gif = False + if original_format == 'GIF': try: img.seek(1) # Try to seek to second frame # If successful, it's animated + is_animated_gif = True if file_size > MAX_OUTPUT_SIZE: raise ValueError( "Animated GIF too large. Maximum size for animated GIFs is 10MB. " @@ -225,10 +234,38 @@ def validate_image(file_data: bytes, filename: str) -> Tuple[bytes, str, int, in # Not animated, continue normally pass - return file_data, mime_type, width, height + # v1.5.1: Early downscale for memory safety + # Large phone images (48MP+) can use 500MB+ per copy in memory + # Downscale early to MEMORY_SAFE_DIMENSION to reduce memory footprint + # This happens BEFORE optimize_image to prevent OOM during processing + if not is_animated_gif and max(orig_width, orig_height) > MEMORY_SAFE_DIMENSION: + try: + current_app.logger.info( + f'Memory safety downscale: {orig_width}x{orig_height} -> ' + f'{MEMORY_SAFE_DIMENSION}x{MEMORY_SAFE_DIMENSION} max' + ) + except RuntimeError: + pass # Outside app context + + # Apply EXIF orientation before resize + img = ImageOps.exif_transpose(img) + + # Use thumbnail() for memory-efficient in-place resize + img.thumbnail((MEMORY_SAFE_DIMENSION, MEMORY_SAFE_DIMENSION), Image.Resampling.LANCZOS) + + # Store the format on the image object for later use + img.format = original_format + + # Clear file_data reference to allow garbage collection + del file_data + + return img, mime_type, orig_width, orig_height -def optimize_image(image_data: bytes, original_size: int = None) -> Tuple[Image.Image, int, int, bytes]: +def optimize_image( + image_input: Union[Image.Image, bytes], + original_size: int = None +) -> Tuple[Image.Image, int, int, bytes]: """ Optimize image for web display with size-aware strategy @@ -237,8 +274,12 @@ def optimize_image(image_data: bytes, original_size: int = None) -> Tuple[Image. - Iterative quality reduction if needed - Target output <=10MB + Per v1.5.1: + - Accept PIL Image directly to avoid memory copies + - Image may already be downscaled for memory safety + Args: - image_data: Raw image bytes + image_input: PIL Image object or raw image bytes original_size: Original file size (for tiered optimization) Returns: @@ -247,24 +288,35 @@ def optimize_image(image_data: bytes, original_size: int = None) -> Tuple[Image. Raises: ValueError: If image cannot be optimized to target size """ - if original_size is None: - original_size = len(image_data) + # Handle both PIL Image and bytes input (v1.5.1) + if isinstance(image_input, Image.Image): + img = image_input + # For PIL input, use provided size or estimate from current dimensions + if original_size is None: + # Estimate: assume worst case of uncompressed RGB + original_size = img.width * img.height * 3 + else: + # Legacy bytes input path + if original_size is None: + original_size = len(image_input) + img = Image.open(io.BytesIO(image_input)) # Get initial optimization parameters based on input size max_dim, quality = get_optimization_params(original_size) - img = Image.open(io.BytesIO(image_data)) - # Save original format before any processing (copy() loses this) - original_format = img.format + original_format = img.format or 'JPEG' # Correct EXIF orientation (per ADR-058), except for GIFs - img = ImageOps.exif_transpose(img) if img.format != 'GIF' else img + # Note: For v1.5.1, this may already be done in validate_image for large images + if original_format != 'GIF': + img = ImageOps.exif_transpose(img) - # For animated GIFs, return as-is (already validated in validate_image) - if img.format == 'GIF' and getattr(img, 'is_animated', False): - # Already checked size in validate_image, just return original - return img, img.size[0], img.size[1], image_data + # For animated GIFs, serialize and return (already validated in validate_image) + if original_format == 'GIF' and getattr(img, 'is_animated', False): + output = io.BytesIO() + img.save(output, format='GIF') + return img, img.size[0], img.size[1], output.getvalue() # Iterative optimization loop while True: @@ -277,8 +329,7 @@ def optimize_image(image_data: bytes, original_size: int = None) -> Tuple[Image. # Save to bytes to check size output = io.BytesIO() - # Use original format (copy() loses the format attribute) - save_format = original_format or 'JPEG' + save_format = original_format save_kwargs = {'optimize': True} if save_format in ['JPEG', 'JPG']: @@ -528,6 +579,7 @@ def save_media(file_data: bytes, filename: str) -> Dict: Per Q2: Date-organized path: /media/YYYY/MM/uuid.ext Per Q6: Validate, optimize, then save Per v1.4.0: Size-aware optimization with iterative quality reduction + Per v1.6.0 Phase 0: Timing logs for performance monitoring Args: file_data: Raw file bytes @@ -544,24 +596,42 @@ def save_media(file_data: bytes, filename: str) -> Dict: # Capture file size for logging file_size = len(file_data) + # Timing instrumentation (v1.6.0 Phase 0) + timing_start = time.monotonic() + timing_validation = 0.0 + timing_optimization = 0.0 + timing_variants = 0.0 + timing_save = 0.0 + try: - # Validate image (returns 4-tuple with potentially converted bytes) + # Validate image (v1.5.1: returns PIL Image to avoid memory copies) try: - file_data, mime_type, orig_width, orig_height = validate_image(file_data, filename) + t_start = time.monotonic() + validated_img, mime_type, orig_width, orig_height = validate_image(file_data, filename) + timing_validation = time.monotonic() - t_start + # Clear file_data early to reduce memory pressure + del file_data except ValueError as e: + timing_validation = time.monotonic() - timing_start current_app.logger.warning( f'Media upload validation failed: filename="{filename}", ' - f'size={file_size}b, error="{e}"' + f'size={file_size}b, error="{e}", timing: validation={timing_validation:.1f}s' ) raise - # Optimize image with size-aware strategy (now returns 4-tuple with bytes) + # Optimize image with size-aware strategy (v1.5.1: accepts PIL Image) try: - optimized_img, width, height, optimized_bytes = optimize_image(file_data, file_size) + t_start = time.monotonic() + optimized_img, width, height, optimized_bytes = optimize_image(validated_img, file_size) + timing_optimization = time.monotonic() - t_start + # Clear validated_img reference (optimized_img is the result now) + del validated_img except ValueError as e: + timing_optimization = time.monotonic() - t_start current_app.logger.warning( f'Media upload optimization failed: filename="{filename}", ' - f'size={file_size}b, error="{e}"' + f'size={file_size}b, error="{e}", ' + f'timing: validation={timing_validation:.1f}s, optimization={timing_optimization:.1f}s' ) raise @@ -601,7 +671,8 @@ def save_media(file_data: bytes, filename: str) -> Dict: temp_subdir = None try: - # Step 1: Save original to temp directory + # Step 1: Generate variants to temp directory + t_start = time.monotonic() media_dir = Path(current_app.config.get('DATA_PATH', 'data')) / 'media' temp_dir = media_dir / '.tmp' temp_dir.mkdir(parents=True, exist_ok=True) @@ -623,8 +694,10 @@ def save_media(file_data: bytes, filename: str) -> Dict: optimized_bytes, db ) + timing_variants = time.monotonic() - t_start - # Step 3: Begin transaction + # Step 3: Begin transaction and save to database + t_start = time.monotonic() db.execute("BEGIN TRANSACTION") # Step 4: Insert media record @@ -667,6 +740,7 @@ def save_media(file_data: bytes, filename: str) -> Dict: # Step 7: Commit transaction (after files are moved successfully) db.commit() + timing_save = time.monotonic() - t_start # Step 8: Clean up temp directory try: @@ -679,6 +753,9 @@ def save_media(file_data: bytes, filename: str) -> Dict: variants = [v for v in variant_metadata if v['variant_type'] != 'original'] except Exception as e: + # Capture timing for failed save operation + timing_save = time.monotonic() - t_start if 't_start' in locals() else 0.0 + # Rollback database on any failure (best effort) try: db.rollback() @@ -722,19 +799,27 @@ def save_media(file_data: bytes, filename: str) -> Dict: except OSError: pass - # Log and re-raise + # Calculate total timing + timing_total = time.monotonic() - timing_start + + # Log and re-raise (with timing data) current_app.logger.warning( f'Media upload atomic operation failed: filename="{filename}", ' - f'error="{e}"' + f'error="{e}", timing: validation={timing_validation:.1f}s, ' + f'optimization={timing_optimization:.1f}s, variants={timing_variants:.1f}s, ' + f'save={timing_save:.1f}s, total={timing_total:.1f}s' ) raise - # Log success + # Log success with timing data (v1.6.0 Phase 0) + timing_total = time.monotonic() - timing_start was_optimized = len(optimized_bytes) < file_size current_app.logger.info( f'Media upload successful: filename="{filename}", ' f'stored="{stored_filename}", size={len(optimized_bytes)}b, ' - f'optimized={was_optimized}, variants={len(variants)}' + f'optimized={was_optimized}, variants={len(variants)}, ' + f'timing: validation={timing_validation:.1f}s, optimization={timing_optimization:.1f}s, ' + f'variants={timing_variants:.1f}s, save={timing_save:.1f}s, total={timing_total:.1f}s' ) return { diff --git a/starpunk/models.py b/starpunk/models.py index 70c95a8..58cc04d 100644 --- a/starpunk/models.py +++ b/starpunk/models.py @@ -114,6 +114,7 @@ class Note: # Optional fields deleted_at: Optional[datetime] = None content_hash: Optional[str] = None + in_reply_to: Optional[str] = None # v1.6.0: URL being replied to _cached_content: Optional[str] = field( default=None, repr=False, compare=False, init=False ) @@ -171,6 +172,7 @@ class Note: deleted_at=deleted_at, _data_dir=data_dir, content_hash=data.get("content_hash"), + in_reply_to=data.get("in_reply_to"), ) @property diff --git a/starpunk/notes.py b/starpunk/notes.py index a72de69..54de270 100644 --- a/starpunk/notes.py +++ b/starpunk/notes.py @@ -138,7 +138,8 @@ def create_note( published: bool = False, created_at: Optional[datetime] = None, custom_slug: Optional[str] = None, - tags: Optional[list[str]] = None + tags: Optional[list[str]] = None, + in_reply_to: Optional[str] = None ) -> Note: """ Create a new note @@ -153,6 +154,7 @@ def create_note( created_at: Creation timestamp (default: current UTC time) custom_slug: Optional custom slug (from Micropub mp-slug property) tags: Optional list of tag display names (v1.3.0) + in_reply_to: Optional URL being replied to (v1.6.0) Returns: Note object with all metadata and content loaded @@ -262,10 +264,10 @@ def create_note( try: db.execute( """ - INSERT INTO notes (slug, file_path, published, created_at, updated_at, content_hash) - VALUES (?, ?, ?, ?, ?, ?) + INSERT INTO notes (slug, file_path, published, created_at, updated_at, content_hash, in_reply_to) + VALUES (?, ?, ?, ?, ?, ?, ?) """, - (slug, file_path_rel, published, created_at, updated_at, content_hash), + (slug, file_path_rel, published, created_at, updated_at, content_hash, in_reply_to), ) db.commit() except Exception as e: @@ -313,6 +315,44 @@ def create_note( # FTS update failure should not prevent note creation current_app.logger.warning(f"Failed to update FTS index for note {slug}: {e}") + # 11. QUEUE WEBMENTIONS (v1.6.0 Phase 3) + # Only queue if note is published (not draft) + if published: + try: + from starpunk.webmention_sender import queue_webmentions_for_note + db_path = Path(current_app.config["DATABASE_PATH"]) + site_url = current_app.config["SITE_URL"] + note_url = f"{site_url}/note/{slug}" + + # Get rendered HTML from note + html_content = note.html + + # Queue webmentions (best-effort, failures logged but don't fail note creation) + queue_webmentions_for_note( + db_path=db_path, + note_id=note_id, + note_url=note_url, + content_html=html_content, + in_reply_to=in_reply_to + ) + except Exception as e: + # Webmention queueing failure should not prevent note creation + current_app.logger.warning(f"Failed to queue webmentions for note {slug}: {e}") + + # 12. FETCH REPLY CONTEXT (v1.6.0 Phase 3) + # Fetch context if this is a reply + if in_reply_to: + try: + from starpunk.reply_context import fetch_reply_context + db_path = Path(current_app.config["DATABASE_PATH"]) + site_url = current_app.config["SITE_URL"] + + # Fetch context (best-effort, failures logged but don't fail note creation) + fetch_reply_context(db_path, in_reply_to, site_url) + except Exception as e: + # Reply context fetch failure should not prevent note creation + current_app.logger.warning(f"Failed to fetch reply context for {in_reply_to}: {e}") + return note @@ -548,7 +588,8 @@ def update_note( id: Optional[int] = None, content: Optional[str] = None, published: Optional[bool] = None, - tags: Optional[list[str]] = None + tags: Optional[list[str]] = None, + in_reply_to: Optional[str] = None ) -> Note: """ Update a note's content and/or published status @@ -563,6 +604,7 @@ def update_note( content: New markdown content (None = no change) published: New published status (None = no change) tags: New tags list (None = no change, [] = remove all tags) (v1.3.0) + in_reply_to: New in-reply-to URL (None = no change) (v1.6.0) Returns: Updated Note object with new content and metadata @@ -618,8 +660,8 @@ def update_note( if slug is not None and id is not None: raise ValueError("Cannot provide both slug and id") - if content is None and published is None and tags is None: - raise ValueError("Must provide at least one of content, published, or tags to update") + if content is None and published is None and tags is None and in_reply_to is None: + raise ValueError("Must provide at least one of content, published, tags, or in_reply_to to update") # Validate content if provided if content is not None: @@ -629,7 +671,8 @@ def update_note( ) # 2. GET EXISTING NOTE - existing_note = get_note(slug=slug, id=id, load_content=False) + # Phase 6: Load content to get old HTML for webmention URL diffing + existing_note = get_note(slug=slug, id=id, load_content=True) if existing_note is None: identifier = slug if slug is not None else id @@ -648,7 +691,18 @@ def update_note( "Path validation failed", ) - # 4. UPDATE FILE (if content changed) + # 4. CAPTURE OLD HTML (Phase 6: for webmention URL diffing) + # Capture old HTML before writing new content + # Only if note is/was published (unpublished notes don't send webmentions) + old_html = None + if existing_note.published: + try: + old_html = existing_note.html + except Exception as e: + # HTML rendering failed - continue with update, skip old_html + current_app.logger.warning(f"Failed to render old HTML for note {existing_note.slug}: {e}") + + # 5. UPDATE FILE (if content changed) new_content_hash = existing_note.content_hash if content is not None: try: @@ -664,7 +718,7 @@ def update_note( f"Could not update note file: {note_path}", ) - # 5. UPDATE DATABASE + # 6. UPDATE DATABASE db = get_db(current_app) # Build update query based on what changed @@ -679,6 +733,10 @@ def update_note( update_fields.append("published = ?") params.append(published) + if in_reply_to is not None: + update_fields.append("in_reply_to = ?") + params.append(in_reply_to) + # Add WHERE clause parameter if slug is not None: where_clause = "slug = ?" @@ -726,9 +784,74 @@ def update_note( # FTS update failure should not prevent note update current_app.logger.warning(f"Failed to update FTS index for note {existing_note.slug}: {e}") - # 8. RETURN UPDATED NOTE + # 8. QUEUE WEBMENTIONS (v1.6.0 Phase 6) + # Queue webmentions if: + # - Note is being unpublished (notify removed URLs) + # - Note is being published (content changed OR publish status changed) + # - Note was published and content/in_reply_to changed updated_note = get_note(slug=existing_note.slug, load_content=True) + # Detect unpublishing (published -> unpublished) + is_unpublishing = existing_note.published and published is False + + # Check if content actually changed (Phase 6 optimization) + content_changed = (new_content_hash != existing_note.content_hash) + publish_status_changed = (published is not None and published != existing_note.published) + + # Determine if we should queue webmentions + should_queue = False + if is_unpublishing: + # Unpublishing - queue for ALL previously-linked URLs + should_queue = True + elif published is not None and published: + # Being published now - queue if content changed OR just being published + should_queue = content_changed or publish_status_changed + elif existing_note.published and (content_changed or in_reply_to is not None): + # Was already published and content/reply-to changed + should_queue = True + + if should_queue: + try: + from starpunk.webmention_sender import queue_webmentions_for_note + db_path = Path(current_app.config["DATABASE_PATH"]) + site_url = current_app.config["SITE_URL"] + note_url = f"{site_url}/note/{updated_note.slug}" + + # Get rendered HTML from updated note (if published) + html_content = updated_note.html if updated_note.published else None + + # Determine in_reply_to (use new value if provided, otherwise existing) + reply_to = in_reply_to if in_reply_to is not None else updated_note.in_reply_to + + # Queue webmentions (best-effort) + # Pass old_html for URL diffing (Phase 6) + queue_webmentions_for_note( + db_path=db_path, + note_id=updated_note.id, + note_url=note_url, + content_html=html_content, + in_reply_to=reply_to, + old_content_html=old_html # Phase 6: for URL diffing + ) + except Exception as e: + # Webmention queueing failure should not prevent note update + current_app.logger.warning(f"Failed to queue webmentions for note {updated_note.slug}: {e}") + + # 9. FETCH REPLY CONTEXT (v1.6.0 Phase 3) + # Fetch context if in_reply_to changed and is not None + if in_reply_to is not None: + try: + from starpunk.reply_context import fetch_reply_context + db_path = Path(current_app.config["DATABASE_PATH"]) + site_url = current_app.config["SITE_URL"] + + # Fetch context (best-effort) + fetch_reply_context(db_path, in_reply_to, site_url) + except Exception as e: + # Reply context fetch failure should not prevent note update + current_app.logger.warning(f"Failed to fetch reply context for {in_reply_to}: {e}") + + # 10. RETURN UPDATED NOTE return updated_note diff --git a/starpunk/rate_limiter.py b/starpunk/rate_limiter.py new file mode 100644 index 0000000..adf7f2d --- /dev/null +++ b/starpunk/rate_limiter.py @@ -0,0 +1,210 @@ +""" +Rate limiting for webmention endpoint + +Implements sliding window log algorithm with thread-safe in-memory storage. +Per ADR-064, this uses in-memory counters consistent with the existing +_discovery_cache pattern in webmention_worker.py. + +References: + - ADR-064: Webmention Rate Limiting + - Design: /docs/design/v1.6.0/rate-limiting.md +""" + +import threading +import time +from datetime import datetime, timedelta +from typing import Dict, List, Tuple + + +class RateLimiter: + """ + Thread-safe sliding window rate limiter. + + Uses sliding window log algorithm: + - Stores timestamp of each request in window + - Removes expired entries on each check + - Rejects if count >= limit + """ + + def __init__(self, limit: int, window_seconds: int): + """ + Initialize rate limiter. + + Args: + limit: Maximum requests allowed in window + window_seconds: Time window in seconds + """ + self.limit = limit + self.window_seconds = window_seconds + self._requests: Dict[str, List[float]] = {} + self._lock = threading.Lock() + + def is_allowed(self, key: str) -> bool: + """ + Check if request is allowed and record it if so. + + Args: + key: Identifier (e.g., IP address or domain) + + Returns: + True if request is allowed, False if rate limited + """ + with self._lock: + now = time.time() + cutoff = now - self.window_seconds + + # Get or create request log for this key + if key not in self._requests: + self._requests[key] = [] + + # Remove expired entries + self._requests[key] = [ts for ts in self._requests[key] if ts > cutoff] + + # Check if at or over limit + if len(self._requests[key]) >= self.limit: + return False + + # Allow request and record timestamp + self._requests[key].append(now) + return True + + def get_retry_after(self, key: str) -> int: + """ + Get seconds until oldest request expires (for Retry-After header). + + Args: + key: Identifier (e.g., IP address or domain) + + Returns: + Seconds until rate limit resets, or window_seconds if no requests + """ + with self._lock: + if key not in self._requests or not self._requests[key]: + return self.window_seconds + + now = time.time() + oldest_request = self._requests[key][0] + expires_at = oldest_request + self.window_seconds + retry_after = int(expires_at - now) + + # Return at least 1 second, max window_seconds + return max(1, min(retry_after, self.window_seconds)) + + def cleanup(self, max_idle_seconds: int = 300): + """ + Remove keys with no recent requests to prevent memory growth. + + Args: + max_idle_seconds: Remove keys idle for this many seconds + """ + with self._lock: + now = time.time() + cutoff = now - max_idle_seconds + keys_to_remove = [] + + for key, timestamps in self._requests.items(): + # Remove expired timestamps first + self._requests[key] = [ts for ts in timestamps if ts > cutoff] + # Mark empty keys for removal + if not self._requests[key]: + keys_to_remove.append(key) + + for key in keys_to_remove: + del self._requests[key] + + def get_request_count(self, key: str) -> int: + """ + Get current request count for a key (for testing/logging). + + Args: + key: Identifier (e.g., IP address or domain) + + Returns: + Number of requests in current window + """ + with self._lock: + if key not in self._requests: + return 0 + + now = time.time() + cutoff = now - self.window_seconds + # Count non-expired requests + return len([ts for ts in self._requests[key] if ts > cutoff]) + + +# Module-level rate limiters (initialized in init_rate_limiters) +_ip_limiter: RateLimiter | None = None +_domain_limiter: RateLimiter | None = None + + +def init_rate_limiters(app) -> None: + """ + Initialize rate limiters with Flask app configuration. + + Args: + app: Flask application instance + """ + global _ip_limiter, _domain_limiter + + if not app.config.get('WEBMENTION_RATE_LIMIT_ENABLED', True): + app.logger.info("Rate limiting disabled") + _ip_limiter = None + _domain_limiter = None + return + + ip_limit = app.config.get('WEBMENTION_RATE_LIMIT_IP', 60) + domain_limit = app.config.get('WEBMENTION_RATE_LIMIT_DOMAIN', 10) + window = app.config.get('WEBMENTION_RATE_LIMIT_WINDOW', 60) + + _ip_limiter = RateLimiter(ip_limit, window) + _domain_limiter = RateLimiter(domain_limit, window) + + app.logger.info( + f"Webmention rate limiter initialized: {ip_limit}/min IP, " + f"{domain_limit}/min domain" + ) + + +def check_rate_limit(ip: str, source_domain: str | None) -> Tuple[bool, str | None]: + """ + Check rate limits for a request. + + Args: + ip: Client IP address + source_domain: Source URL domain (optional) + + Returns: + (allowed, error_message) tuple + - allowed: True if request allowed, False if rate limited + - error_message: Error description if rate limited, None otherwise + """ + # If rate limiting disabled, allow all requests + if _ip_limiter is None: + return True, None + + # Check IP limit first + if not _ip_limiter.is_allowed(ip): + retry_after = _ip_limiter.get_retry_after(ip) + count = _ip_limiter.get_request_count(ip) + return False, f"Too many requests from your IP. Please retry after {retry_after} seconds." + + # Check domain limit if source domain provided + if source_domain and _domain_limiter is not None: + if not _domain_limiter.is_allowed(source_domain): + retry_after = _domain_limiter.get_retry_after(source_domain) + count = _domain_limiter.get_request_count(source_domain) + return False, f"Too many requests from source domain. Please retry after {retry_after} seconds." + + return True, None + + +def cleanup_rate_limiters() -> None: + """ + Cleanup expired entries from rate limiters. + + Called periodically to prevent memory growth. + """ + if _ip_limiter: + _ip_limiter.cleanup() + if _domain_limiter: + _domain_limiter.cleanup() diff --git a/starpunk/reply_context.py b/starpunk/reply_context.py new file mode 100644 index 0000000..8a61e2b --- /dev/null +++ b/starpunk/reply_context.py @@ -0,0 +1,329 @@ +""" +Reply context fetching for in-reply-to URLs + +Per database-schema.md Story 2.4: +- Fetch context from in_reply_to URL when note is reply +- Parse microformats for author, content +- Store in reply_contexts table +- Graceful degradation on fetch failure + +References: + - Database Schema: /docs/design/v1.6.0/database-schema.md + - Background Worker: /docs/design/v1.6.0/background-worker.md +""" + +import logging +import sqlite3 +from datetime import datetime +from pathlib import Path +from typing import Optional, Dict, Any + +from starpunk.webmention_processor import ( + fetch_source, + extract_author, + extract_content, + ValidationError +) +import mf2py + + +logger = logging.getLogger(__name__) + + +def fetch_reply_context( + db_path: Path, + reply_url: str, + site_url: str +) -> Dict[str, Any]: + """ + Fetch and parse reply context from a URL. + + Per database-schema.md: + - Fetch URL content with SSRF protection + - Parse h-entry for title, content, published date + - Parse h-card for author information + - Store in reply_contexts table + - Graceful degradation: errors don't prevent reply creation + + Args: + db_path: Path to SQLite database + reply_url: URL being replied to + site_url: Site URL for User-Agent header + + Returns: + Dict with fetch status and context data + """ + # Check if context already exists + try: + conn = sqlite3.connect(db_path) + conn.row_factory = sqlite3.Row + cursor = conn.cursor() + + cursor.execute(""" + SELECT * FROM reply_contexts WHERE url = ? + """, (reply_url,)) + + existing = cursor.fetchone() + conn.close() + + if existing: + logger.debug(f"Reply context already cached for {reply_url}") + return dict(existing) + + except Exception as e: + logger.warning(f"Failed to check existing context: {e}") + + # Fetch and parse context + try: + # Fetch URL content + content, content_type = fetch_source(reply_url, site_url) + + # Parse microformats (only for HTML) + if 'html' not in content_type.lower(): + # Not HTML - store minimal context + return _store_minimal_context(db_path, reply_url, "Not HTML content") + + parsed_mf2 = mf2py.parse(doc=content, url=reply_url) + + # Extract h-entry data + entry_data = _extract_entry_data(parsed_mf2) + + # Extract author data + author_data = extract_author(parsed_mf2, reply_url) + + # Store in database + context = _store_context( + db_path, + reply_url, + entry_data.get('title'), + entry_data.get('content_snippet'), + entry_data.get('published_at'), + author_data.get('author_name'), + author_data.get('author_url'), + author_data.get('author_photo'), + entry_data.get('site_name') + ) + + logger.info(f"Fetched reply context for {reply_url}") + return context + + except ValidationError as e: + # Fetch/validation error - store error status + logger.warning(f"Failed to fetch reply context for {reply_url}: {e}") + return _store_minimal_context(db_path, reply_url, str(e)) + + except Exception as e: + # Unexpected error - store error status + logger.error(f"Error fetching reply context for {reply_url}: {e}", exc_info=True) + return _store_minimal_context(db_path, reply_url, f"Unexpected error: {e}") + + +def _extract_entry_data(parsed_mf2: Dict) -> Dict[str, Any]: + """ + Extract entry data from parsed microformats. + + Args: + parsed_mf2: Parsed microformats data from mf2py + + Returns: + Dict with title, content_snippet, published_at, site_name + """ + title = None + content_snippet = None + published_at = None + site_name = None + + # Find h-entry + for item in parsed_mf2.get('items', []): + if 'h-entry' not in item.get('type', []): + continue + + props = item.get('properties', {}) + + # Extract title (p-name) + name = props.get('name', []) + if name: + title = name[0] + if isinstance(title, dict): + title = title.get('value', '') + # Truncate if too long + if title and len(title) > 200: + title = title[:197] + '...' + + # Extract content (reuse processor function) + content_snippet = extract_content(parsed_mf2) + + # Extract published date + published = props.get('published', []) + if published: + pub_str = published[0] + if isinstance(pub_str, dict): + pub_str = pub_str.get('value', '') + # Try to parse ISO 8601 datetime + try: + from dateutil import parser as dateutil_parser + published_at = dateutil_parser.parse(pub_str) + except Exception: + # Parsing failed, leave as None + pass + + break # Use first h-entry + + # Try to extract site name from h-card + for item in parsed_mf2.get('items', []): + if 'h-card' in item.get('type', []): + props = item.get('properties', {}) + name = props.get('name', []) + if name: + site_name = name[0] + if isinstance(site_name, dict): + site_name = site_name.get('value', '') + break + + return { + 'title': title, + 'content_snippet': content_snippet, + 'published_at': published_at, + 'site_name': site_name + } + + +def _store_context( + db_path: Path, + url: str, + title: Optional[str], + content_snippet: Optional[str], + published_at: Optional[datetime], + author_name: Optional[str], + author_url: Optional[str], + author_photo: Optional[str], + site_name: Optional[str] +) -> Dict[str, Any]: + """ + Store reply context in database. + + Args: + db_path: Database path + url: Reply-to URL + title: Entry title + content_snippet: Content snippet + published_at: Published datetime + author_name: Author name + author_url: Author URL + author_photo: Author photo URL + site_name: Site name + + Returns: + Stored context dict + """ + try: + conn = sqlite3.connect(db_path) + cursor = conn.cursor() + + cursor.execute(""" + INSERT OR REPLACE INTO reply_contexts + (url, title, content_snippet, published_at, + author_name, author_url, author_photo, site_name, + fetch_status, fetched_at) + VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'fetched', CURRENT_TIMESTAMP) + """, ( + url, title, content_snippet, published_at, + author_name, author_url, author_photo, site_name + )) + + conn.commit() + conn.close() + + return { + 'url': url, + 'title': title, + 'content_snippet': content_snippet, + 'published_at': published_at, + 'author_name': author_name, + 'author_url': author_url, + 'author_photo': author_photo, + 'site_name': site_name, + 'fetch_status': 'fetched' + } + + except Exception as e: + logger.error(f"Failed to store reply context: {e}") + raise + + +def _store_minimal_context( + db_path: Path, + url: str, + error: str +) -> Dict[str, Any]: + """ + Store minimal context with error status. + + Args: + db_path: Database path + url: Reply-to URL + error: Error message + + Returns: + Minimal context dict with error + """ + try: + conn = sqlite3.connect(db_path) + cursor = conn.cursor() + + cursor.execute(""" + INSERT OR REPLACE INTO reply_contexts + (url, fetch_status, fetch_error, created_at) + VALUES (?, 'error', ?, CURRENT_TIMESTAMP) + """, (url, error)) + + conn.commit() + conn.close() + + return { + 'url': url, + 'fetch_status': 'error', + 'fetch_error': error + } + + except Exception as e: + logger.error(f"Failed to store minimal context: {e}") + # Return in-memory dict even if storage fails + return { + 'url': url, + 'fetch_status': 'error', + 'fetch_error': error + } + + +def get_reply_context(db_path: Path, reply_url: str) -> Optional[Dict[str, Any]]: + """ + Get cached reply context from database. + + Args: + db_path: Database path + reply_url: Reply-to URL + + Returns: + Context dict if exists, None otherwise + """ + try: + conn = sqlite3.connect(db_path) + conn.row_factory = sqlite3.Row + cursor = conn.cursor() + + cursor.execute(""" + SELECT * FROM reply_contexts WHERE url = ? + """, (reply_url,)) + + row = cursor.fetchone() + conn.close() + + if row: + return dict(row) + + return None + + except Exception as e: + logger.error(f"Failed to get reply context: {e}") + return None diff --git a/starpunk/routes/__init__.py b/starpunk/routes/__init__.py index 1a9c690..0ac464a 100644 --- a/starpunk/routes/__init__.py +++ b/starpunk/routes/__init__.py @@ -7,7 +7,7 @@ admin, auth, and (conditionally) dev auth routes. from flask import Flask -from starpunk.routes import admin, auth, micropub, public, search +from starpunk.routes import admin, auth, micropub, public, search, webmention def register_routes(app: Flask) -> None: @@ -39,6 +39,10 @@ def register_routes(app: Flask) -> None: # Register search routes app.register_blueprint(search.bp) + # Register webmention routes (v1.6.0) + if app.config.get("WEBMENTION_ENABLED", True): + app.register_blueprint(webmention.bp) + # Conditionally register dev auth routes if app.config.get("DEV_MODE"): app.logger.warning( diff --git a/starpunk/routes/admin.py b/starpunk/routes/admin.py index 69fc38f..057b0ac 100644 --- a/starpunk/routes/admin.py +++ b/starpunk/routes/admin.py @@ -6,10 +6,13 @@ editing, and deletion. All routes require authentication. """ from flask import Blueprint, flash, g, jsonify, redirect, render_template, request, url_for +import logging import os import shutil from datetime import datetime +logger = logging.getLogger(__name__) + from starpunk.auth import require_auth from starpunk.notes import ( create_note, @@ -32,17 +35,51 @@ def dashboard(): Displays all notes (published and drafts) with management controls. Requires authentication. + Per v1.6.0: Added pagination (25 items per page) + Returns: - Rendered dashboard template with complete note list + Rendered dashboard template with paginated note list Decorator: @require_auth Template: templates/admin/dashboard.html Access: g.user_me (set by require_auth decorator) """ - # Get all notes (published and drafts) - notes = list_notes() + from flask import current_app + import math - return render_template("admin/dashboard.html", notes=notes, user_me=g.me) + # Get pagination params (v1.6.0) + page = int(request.args.get('page', 1)) + per_page = 25 + + # Get all notes (published and drafts) + all_notes = list_notes() + + # Calculate pagination + total_notes = len(all_notes) + total_pages = math.ceil(total_notes / per_page) if total_notes > 0 else 1 + + # Slice for current page + start_idx = (page - 1) * per_page + end_idx = start_idx + per_page + notes = all_notes[start_idx:end_idx] + + # Get pending webmention count (v1.6.0) + webmention_pending_count = 0 + if current_app.config.get('WEBMENTION_ENABLED', False): + try: + from starpunk.webmention_queries import count_webmentions + webmention_pending_count = count_webmentions(status_filter='pending') + except Exception: + pass + + return render_template( + "admin/dashboard.html", + notes=notes, + page=page, + total_pages=total_pages, + webmention_pending_count=webmention_pending_count, + user_me=g.me + ) @bp.route("/new", methods=["GET"]) @@ -600,3 +637,182 @@ def health_diagnostics(): diagnostics["status"] = "healthy" if overall_healthy else "unhealthy" return jsonify(diagnostics), 200 if overall_healthy else 500 + + +# Webmention Admin Routes (v1.6.0) + +@bp.route("/webmentions") +@require_auth +def webmentions(): + """ + Webmention list with filtering and pagination (v1.6.0 Phase 5) + + Lists all webmentions with status filters and pagination. + + Query params: + status: Filter by moderation_status ('pending', 'approved', 'hidden') + page: Page number (default: 1) + + Returns: + Rendered webmentions list template + + Decorator: @require_auth + Template: templates/admin/webmentions.html + """ + from starpunk.webmention_queries import list_webmentions + + status_filter = request.args.get('status') + page = int(request.args.get('page', 1)) + + webmentions, total_pages = list_webmentions( + status_filter=status_filter, + page=page, + per_page=25 + ) + + return render_template( + "admin/webmentions.html", + webmentions=webmentions, + status_filter=status_filter, + page=page, + total_pages=total_pages, + user_me=g.me + ) + + +@bp.route("/webmentions/") +@require_auth +def webmention_detail(id: int): + """ + Webmention detail view (v1.6.0 Phase 5) + + Shows full details of a single webmention with moderation actions. + + Args: + id: Webmention database ID + + Returns: + Rendered webmention detail template or 404 if not found + + Decorator: @require_auth + Template: templates/admin/webmention_detail.html + """ + from starpunk.webmention_queries import get_webmention + + webmention = get_webmention(id) + + if not webmention: + flash("Webmention not found", "error") + return redirect(url_for("admin.webmentions")), 404 + + return render_template( + "admin/webmention_detail.html", + webmention=webmention, + user_me=g.me + ) + + +@bp.route("/webmentions//action", methods=["POST"]) +@require_auth +def webmention_action(id: int): + """ + Individual webmention moderation action (v1.6.0 Phase 5) + + Approve, hide, or delete a single webmention. + + Args: + id: Webmention database ID + + Form data: + action: 'approve', 'hide', or 'delete' + + Returns: + Redirect to webmention detail or list + + Decorator: @require_auth + """ + from starpunk.webmention_queries import update_webmention_status, delete_webmentions + + action = request.form.get('action') + + if action not in ('approve', 'hide', 'delete'): + flash("Invalid action", "error") + return redirect(url_for("admin.webmention_detail", id=id)) + + try: + if action == 'delete': + deleted = delete_webmentions([id]) + if deleted > 0: + flash("Webmention deleted", "success") + else: + flash("Webmention not found", "error") + return redirect(url_for("admin.webmentions")) + else: + # Approve or hide + status = 'approved' if action == 'approve' else 'hidden' + updated = update_webmention_status([id], status) + if updated > 0: + flash(f"Webmention {status}", "success") + else: + flash("Webmention not found", "error") + return redirect(url_for("admin.webmention_detail", id=id)) + + except Exception as e: + logger.error(f"Error performing webmention action: {e}") + flash(f"Error: {e}", "error") + return redirect(url_for("admin.webmention_detail", id=id)) + + +@bp.route("/webmentions/bulk-action", methods=["POST"]) +@require_auth +def webmention_bulk_action(): + """ + Bulk webmention moderation actions (v1.6.0 Phase 5) + + Approve, hide, or delete multiple webmentions at once. + + Form data: + action: 'approve', 'hide', or 'delete' + ids[]: List of webmention IDs + + Returns: + Redirect to webmentions list + + Decorator: @require_auth + """ + from starpunk.webmention_queries import update_webmention_status, delete_webmentions + + action = request.form.get('action') + ids = request.form.getlist('ids') + + if not ids: + flash("No webmentions selected", "warning") + return redirect(url_for("admin.webmentions")) + + # Convert IDs to integers + try: + webmention_ids = [int(id) for id in ids] + except ValueError: + flash("Invalid webmention IDs", "error") + return redirect(url_for("admin.webmentions")) + + if action not in ('approve', 'hide', 'delete'): + flash("Invalid action", "error") + return redirect(url_for("admin.webmentions")) + + try: + if action == 'delete': + deleted = delete_webmentions(webmention_ids) + flash(f"Deleted {deleted} webmention(s)", "success") + else: + # Approve or hide + status = 'approved' if action == 'approve' else 'hidden' + updated = update_webmention_status(webmention_ids, status) + flash(f"Updated {updated} webmention(s) to {status}", "success") + + return redirect(url_for("admin.webmentions")) + + except Exception as e: + logger.error(f"Error performing bulk action: {e}") + flash(f"Error: {e}", "error") + return redirect(url_for("admin.webmentions")) diff --git a/starpunk/routes/public.py b/starpunk/routes/public.py index 7167f00..4ead4c4 100644 --- a/starpunk/routes/public.py +++ b/starpunk/routes/public.py @@ -281,6 +281,8 @@ def note(slug: str): Template: templates/note.html Microformats: h-entry + + Per v1.6.0: Added webmentions and reply context display """ from starpunk.media import get_note_media from starpunk.tags import get_note_tags @@ -303,7 +305,39 @@ def note(slug: str): tags = get_note_tags(note_obj.id) object.__setattr__(note_obj, '_cached_tags', tags) - return render_template("note.html", note=note_obj) + # Get webmentions for note (v1.6.0 Phase 5) + webmentions = None + reply_context = None + + if current_app.config.get('WEBMENTION_ENABLED', False): + try: + from starpunk.webmention_queries import get_webmentions_for_note, get_reply_context + + # Get approved webmentions grouped by type + grouped = get_webmentions_for_note(note_obj.id) + + # Check if there are any webmentions + has_webmentions = any(grouped.values()) + if has_webmentions: + webmentions = grouped + + # Get reply context if this is a reply post + if note_obj.in_reply_to: + reply_context = get_reply_context(note_obj.in_reply_to) + + except Exception as e: + # Log error but don't fail page load + import logging + logger = logging.getLogger(__name__) + logger.error(f"Error loading webmentions for note {slug}: {e}") + + return render_template( + "note.html", + note=note_obj, + webmentions=webmentions, + reply_context=reply_context, + **grouped if webmentions else {} + ) @bp.route("/tag/") diff --git a/starpunk/routes/webmention.py b/starpunk/routes/webmention.py new file mode 100644 index 0000000..be8267c --- /dev/null +++ b/starpunk/routes/webmention.py @@ -0,0 +1,272 @@ +""" +Webmention routes for StarPunk + +Per W3C Webmention Recommendation and ADR-063: +- POST /webmention - Receive webmention notifications +- GET /webmention - Optional endpoint information + +References: + - W3C Webmention Specification: https://www.w3.org/TR/webmention/ + - ADR-063: Webmention Implementation +""" + +from flask import Blueprint, current_app, request, jsonify +from urllib.parse import urlparse +from starpunk.database import get_db +from starpunk.notes import get_note, NoteNotFoundError +from starpunk.rate_limiter import check_rate_limit + +bp = Blueprint("webmention", __name__) + + +def get_client_ip() -> str: + """ + Get client IP address, accounting for reverse proxy. + + If TRUSTED_PROXY is enabled, uses X-Forwarded-For header. + Otherwise uses request.remote_addr directly. + """ + if current_app.config.get('TRUSTED_PROXY', False): + forwarded = request.headers.get('X-Forwarded-For') + if forwarded: + # First IP in chain is the client + return forwarded.split(',')[0].strip() + return request.remote_addr or '0.0.0.0' + + +@bp.before_request +def rate_limit_webmention(): + """ + Check rate limits before processing webmention requests. + + Per ADR-064, checks: + 1. IP rate limit (60/min by default) + 2. Source domain rate limit (10/min by default) + + Returns 429 with Retry-After header if rate limited. + """ + # Only rate limit POST requests (the actual webmention submission) + if request.method != 'POST': + return None + + # Get client IP + ip = get_client_ip() + + # Get source domain from request (if available) + source_domain = None + content_type = request.headers.get("Content-Type", "") + + if "application/json" in content_type: + data = request.get_json(silent=True) or {} + source = data.get('source') + else: + source = request.form.get('source') + + if source: + try: + source_domain = urlparse(source).netloc + except Exception: + # Invalid URL, domain check will be skipped + # This is acceptable - IP limit still applies + current_app.logger.debug(f"Could not parse source URL for domain extraction: {source}") + + # Check rate limits + allowed, error = check_rate_limit(ip, source_domain) + if not allowed: + current_app.logger.warning( + f"Rate limit exceeded - IP: {ip}, Domain: {source_domain or 'N/A'}" + ) + return jsonify({ + "error": "rate_limit_exceeded", + "error_description": error + }), 429, {'Retry-After': str(current_app.config.get('WEBMENTION_RATE_LIMIT_WINDOW', 60))} + + return None + + +def validate_url(url: str) -> tuple[bool, str | None]: + """ + Validate a URL is well-formed and uses http/https scheme. + + Returns: + (is_valid, error_message) + """ + if not url: + return False, "URL is required" + + try: + parsed = urlparse(url) + if parsed.scheme not in ('http', 'https'): + return False, "Only http and https URLs are supported" + if not parsed.netloc: + return False, "URL must include a hostname" + if len(url) > 2048: + return False, "URL exceeds maximum length of 2048 characters" + return True, None + except Exception: + return False, "URL is malformed" + + +def is_target_on_site(target_url: str) -> bool: + """ + Check if target URL is on this site. + + Compares hostname of target_url with SITE_URL configuration. + """ + site_url = current_app.config.get('SITE_URL', '') + site_parsed = urlparse(site_url) + target_parsed = urlparse(target_url) + + return site_parsed.netloc == target_parsed.netloc + + +def resolve_target_note(target_url: str) -> int | None: + """ + Resolve target URL to a note ID if it points to a note. + + Returns: + Note ID if target is a valid note, None otherwise + """ + target_parsed = urlparse(target_url) + + # Strip query params and fragments for matching + target_path = target_parsed.path.rstrip('/') + + # Check if it's a note URL pattern: /note/{slug} + if target_path.startswith('/note/'): + slug = target_path[6:] # Remove '/note/' prefix + if slug: + try: + note = get_note(slug=slug) + # get_note() returns None if not found, or a Note object + if note and note.published: + return note.id + except NoteNotFoundError: + pass + + # Homepage or other valid page (not a note) + return None + + +@bp.route("/webmention", methods=["GET"]) +def webmention_info(): + """ + Optional endpoint information. + + Returns basic information about the webmention endpoint. + """ + return jsonify({ + "name": "Webmention endpoint", + "spec": "https://www.w3.org/TR/webmention/" + }) + + +@bp.route("/webmention", methods=["POST"]) +def receive_webmention(): + """ + Receive webmention notification per W3C spec. + + Accepts application/x-www-form-urlencoded (required) and + application/json (optional extension). + + Returns: + 202 Accepted with JSON body on success + 400 Bad Request with error details on failure + """ + # Parse request based on content type + content_type = request.headers.get("Content-Type", "") + + if "application/json" in content_type: + data = request.get_json() or {} + source = data.get("source") + target = data.get("target") + else: + # Default to form-encoded (required by W3C spec) + source = request.form.get("source") + target = request.form.get("target") + + # Validate required parameters + if not source: + return jsonify({ + "error": "invalid_request", + "error_description": "Missing required parameter: source" + }), 400 + + if not target: + return jsonify({ + "error": "invalid_request", + "error_description": "Missing required parameter: target" + }), 400 + + # Validate source URL + source_valid, source_error = validate_url(source) + if not source_valid: + return jsonify({ + "error": "invalid_request", + "error_description": f"Source must be a valid URL" + }), 400 + + # Validate target URL + target_valid, target_error = validate_url(target) + if not target_valid: + return jsonify({ + "error": "invalid_request", + "error_description": f"Target must be a valid URL" + }), 400 + + # Validate source and target are different + if source == target: + return jsonify({ + "error": "invalid_request", + "error_description": "Source and target must be different" + }), 400 + + # Validate target is on this site + if not is_target_on_site(target): + return jsonify({ + "error": "invalid_target", + "error_description": "Target URL is not on this site" + }), 400 + + # Resolve target to note (may be None for homepage/other pages) + target_note_id = resolve_target_note(target) + + # If target looks like a note URL but doesn't resolve, it's not found + target_parsed = urlparse(target) + target_path = target_parsed.path.rstrip('/') + if target_path.startswith('/note/') and target_note_id is None: + return jsonify({ + "error": "invalid_target", + "error_description": "Target URL not found" + }), 400 + + # Insert webmention into database (queued for validation) + # Use INSERT ... ON CONFLICT to handle duplicate webmentions + db = get_db() + try: + db.execute(""" + INSERT INTO webmentions (source_url, target_url, target_note_id) + VALUES (?, ?, ?) + ON CONFLICT(source_url, target_url) DO UPDATE SET + validation_status = 'pending', + updated_at = CURRENT_TIMESTAMP + """, (source, target, target_note_id)) + db.commit() + + current_app.logger.info( + f"Webmention received: {source} -> {target}" + f"{' (note_id=' + str(target_note_id) + ')' if target_note_id else ''}" + ) + + return jsonify({ + "status": "accepted", + "message": "Webmention queued for verification" + }), 202 + + except Exception as e: + db.rollback() + current_app.logger.error(f"Failed to queue webmention: {e}") + return jsonify({ + "error": "server_error", + "error_description": "Failed to queue webmention" + }), 500 diff --git a/starpunk/webmention_processor.py b/starpunk/webmention_processor.py new file mode 100644 index 0000000..291df24 --- /dev/null +++ b/starpunk/webmention_processor.py @@ -0,0 +1,373 @@ +""" +Webmention validation and processing utilities + +Per background-worker.md and api-contract.md: +- Fetch and validate source URLs +- Parse microformats with mf2py +- Extract author information from h-cards +- Detect mention types (reply, like, repost, etc.) +- Sanitize content with nh3 + +References: + - Background Worker Design: /docs/design/v1.6.0/background-worker.md + - API Contract: /docs/design/v1.6.0/api-contract.md + - W3C Webmention: https://www.w3.org/TR/webmention/ +""" + +import logging +import mf2py +import nh3 +import httpx +from datetime import datetime +from typing import Dict, Any, Optional +from urllib.parse import urlparse + +from starpunk.webmention_ssrf import validate_url_for_fetch, SSRFBlockedError + + +logger = logging.getLogger(__name__) + + +class ValidationError(Exception): + """Raised when webmention validation fails""" + pass + + +def fetch_source(url: str, site_url: str, timeout: int = 10, max_size: int = 1048576) -> tuple[str, str]: + """ + Fetch source URL content with SSRF protection. + + Args: + url: Source URL to fetch + site_url: Site URL for User-Agent header + timeout: Request timeout in seconds (default: 10) + max_size: Maximum content size in bytes (default: 1MB) + + Returns: + Tuple of (content, content_type) + + Raises: + SSRFBlockedError: If URL points to private IP + ValidationError: If fetch fails or content too large + """ + # SSRF protection + try: + validate_url_for_fetch(url) + except (SSRFBlockedError, ValueError) as e: + logger.warning(f"SSRF protection blocked URL {url}: {e}") + raise ValidationError(f"Blocked request: {e}") + + # Fetch URL + try: + # Use streaming to check size before downloading entire content + with httpx.stream( + 'GET', + url, + timeout=timeout, + headers={'User-Agent': f'StarPunk/1.6.0 (+{site_url})'}, + follow_redirects=True + ) as response: + response.raise_for_status() + + # Check content length if provided + content_length = response.headers.get('Content-Length') + if content_length and int(content_length) > max_size: + raise ValidationError(f"Source exceeds size limit ({max_size} bytes)") + + # Read content with size limit + content = b'' + for chunk in response.iter_bytes(chunk_size=8192): + content += chunk + if len(content) > max_size: + raise ValidationError(f"Source exceeds size limit ({max_size} bytes)") + + content_type = response.headers.get('Content-Type', '') + + return content.decode('utf-8', errors='replace'), content_type + + except httpx.TimeoutException: + raise ValidationError("Source fetch timed out") + except httpx.HTTPStatusError as e: + if 400 <= e.response.status_code < 500: + raise ValidationError(f"Source returned {e.response.status_code}") + else: + raise ValidationError(f"Source server error: {e.response.status_code}") + except httpx.HTTPError as e: + raise ValidationError(f"Failed to fetch source: {e}") + except UnicodeDecodeError: + raise ValidationError("Source content encoding is not supported") + + +def verify_link_presence(content: str, target_url: str, content_type: str) -> bool: + """ + Verify that source content contains a link to target URL. + + Args: + content: Source content (HTML or text) + target_url: Target URL to find + content_type: Content type of source + + Returns: + True if target link found, False otherwise + """ + # Normalize URLs for comparison (remove fragments, trailing slashes) + target_normalized = urlparse(target_url)._replace(fragment='').geturl().rstrip('/') + + # For HTML, parse and check all links + if 'html' in content_type.lower(): + try: + from lxml import html as lxml_html + doc = lxml_html.fromstring(content) + links = doc.xpath('//a/@href') + + for link in links: + # Make absolute if relative + link_normalized = urlparse(link)._replace(fragment='').geturl().rstrip('/') + if link_normalized == target_normalized: + return True + except Exception as e: + logger.debug(f"HTML parsing failed, falling back to string search: {e}") + + # Fallback: simple string search + return target_normalized in content + + +def detect_mention_type(parsed_mf2: Dict, target_url: str) -> str: + """ + Detect mention type from microformats. + + Priority: reply > like > repost > bookmark > mention + + Args: + parsed_mf2: Parsed microformats data from mf2py + target_url: Target URL being mentioned + + Returns: + Mention type: 'reply', 'like', 'repost', 'bookmark', or 'mention' + """ + target_normalized = urlparse(target_url)._replace(fragment='').geturl().rstrip('/') + + # Find h-entry that references target + for item in parsed_mf2.get('items', []): + if 'h-entry' not in item.get('type', []): + continue + + props = item.get('properties', {}) + + # Check in-reply-to (highest priority) + for reply_to in props.get('in-reply-to', []): + url = reply_to if isinstance(reply_to, str) else reply_to.get('value', '') + if urlparse(url)._replace(fragment='').geturl().rstrip('/') == target_normalized: + return 'reply' + + # Check like-of + for like in props.get('like-of', []): + url = like if isinstance(like, str) else like.get('value', '') + if urlparse(url)._replace(fragment='').geturl().rstrip('/') == target_normalized: + return 'like' + + # Check repost-of + for repost in props.get('repost-of', []): + url = repost if isinstance(repost, str) else repost.get('value', '') + if urlparse(url)._replace(fragment='').geturl().rstrip('/') == target_normalized: + return 'repost' + + # Check bookmark-of + for bookmark in props.get('bookmark-of', []): + url = bookmark if isinstance(bookmark, str) else bookmark.get('value', '') + if urlparse(url)._replace(fragment='').geturl().rstrip('/') == target_normalized: + return 'bookmark' + + # Default fallback + return 'mention' + + +def extract_author(parsed_mf2: Dict, source_url: str) -> Dict[str, Optional[str]]: + """ + Extract author information from h-card. + + Args: + parsed_mf2: Parsed microformats data from mf2py + source_url: Source URL (fallback for author URL) + + Returns: + Dict with author_name, author_url, author_photo + """ + author_name = None + author_url = None + author_photo = None + + # Find h-entry first + entry = None + for item in parsed_mf2.get('items', []): + if 'h-entry' in item.get('type', []): + entry = item + break + + # Check for author property in h-entry + if entry: + author_prop = entry.get('properties', {}).get('author', []) + if author_prop: + author_data = author_prop[0] + if isinstance(author_data, dict): + # h-card object + props = author_data.get('properties', {}) + author_name = props.get('name', [None])[0] + author_url = props.get('url', [None])[0] + author_photo = props.get('photo', [None])[0] + + # If no author in h-entry, find representative h-card + if not author_name: + for item in parsed_mf2.get('items', []): + if 'h-card' in item.get('type', []): + props = item.get('properties', {}) + author_name = props.get('name', [None])[0] + author_url = props.get('url', [None])[0] + author_photo = props.get('photo', [None])[0] + break + + # Fallback to hostname if no author found + if not author_name: + author_name = urlparse(source_url).netloc + + if not author_url: + author_url = source_url + + return { + 'author_name': author_name, + 'author_url': author_url, + 'author_photo': author_photo + } + + +def extract_content(parsed_mf2: Dict) -> Optional[str]: + """ + Extract content snippet from h-entry. + + Args: + parsed_mf2: Parsed microformats data from mf2py + + Returns: + Sanitized content snippet (max 500 chars) or None + """ + # Find h-entry + for item in parsed_mf2.get('items', []): + if 'h-entry' not in item.get('type', []): + continue + + props = item.get('properties', {}) + + # Try e-content first (HTML) + content_prop = props.get('content', []) + if content_prop: + content_data = content_prop[0] + if isinstance(content_data, dict): + content = content_data.get('html', '') or content_data.get('value', '') + else: + content = content_data + + if content: + # Sanitize HTML + sanitized = sanitize_content(content) + # Truncate to 500 chars + if len(sanitized) > 500: + sanitized = sanitized[:497] + '...' + return sanitized + + # Try p-summary as fallback + summary = props.get('summary', []) + if summary: + content = summary[0] + if isinstance(content, dict): + content = content.get('value', '') + if content: + sanitized = sanitize_content(content) + if len(sanitized) > 500: + sanitized = sanitized[:497] + '...' + return sanitized + + return None + + +def sanitize_content(html: str) -> str: + """ + Sanitize HTML content using nh3. + + Per api-contract.md: + - Allowed tags: p, br, strong, em, b, i, a, code, pre, blockquote + - Allowed attributes: a[href, rel] + + Args: + html: HTML content to sanitize + + Returns: + Sanitized HTML + """ + allowed_tags = {'p', 'br', 'strong', 'em', 'b', 'i', 'a', 'code', 'pre', 'blockquote'} + allowed_attributes = {'a': {'href'}} + + return nh3.clean( + html, + tags=allowed_tags, + attributes=allowed_attributes, + link_rel='nofollow noopener' + ) + + +def process_webmention(source_url: str, target_url: str, site_url: str) -> Dict[str, Any]: + """ + Process and validate a webmention. + + Args: + source_url: Source URL of the webmention + target_url: Target URL being mentioned + site_url: Site URL for User-Agent header + + Returns: + Dict with validation results: + - valid: bool + - error: str (if valid=False) + - mention_type: str + - author_name: str + - author_url: str + - author_photo: str or None + - content_snippet: str or None + + Raises: + ValidationError: If validation fails with specific error + """ + # Fetch source content + content, content_type = fetch_source(source_url, site_url) + + # Verify target link presence + if not verify_link_presence(content, target_url, content_type): + raise ValidationError("Source does not link to target") + + # Parse microformats (only for HTML) + parsed_mf2 = None + if 'html' in content_type.lower(): + try: + parsed_mf2 = mf2py.parse(doc=content, url=source_url) + except Exception as e: + logger.debug(f"Microformat parsing failed for {source_url}: {e}") + + # Extract data + mention_type = 'mention' + author_info = { + 'author_name': urlparse(source_url).netloc, + 'author_url': source_url, + 'author_photo': None + } + content_snippet = None + + if parsed_mf2: + mention_type = detect_mention_type(parsed_mf2, target_url) + author_info = extract_author(parsed_mf2, source_url) + content_snippet = extract_content(parsed_mf2) + + return { + 'valid': True, + 'mention_type': mention_type, + **author_info, + 'content_snippet': content_snippet + } diff --git a/starpunk/webmention_queries.py b/starpunk/webmention_queries.py new file mode 100644 index 0000000..f767511 --- /dev/null +++ b/starpunk/webmention_queries.py @@ -0,0 +1,295 @@ +""" +Webmention database query functions + +Provides database query functions for webmention management. +Per display-moderation.md design specification. + +Functions: + - get_webmentions_for_note: Get approved webmentions for public display + - list_webmentions: List webmentions for admin with filters and pagination + - get_webmention: Get single webmention by ID + - count_webmentions: Count webmentions (optionally filtered) + - update_webmention_status: Update moderation status + - delete_webmentions: Delete webmentions by IDs + - get_reply_context: Get cached reply context for a URL +""" + +import logging +import math +from datetime import datetime +from typing import List, Dict, Any, Optional +from starpunk.database import get_db + +logger = logging.getLogger(__name__) + + +def get_webmentions_for_note(note_id: int) -> Dict[str, List[Dict[str, Any]]]: + """ + Get approved webmentions for a note, grouped by type for public display. + + Per display-moderation.md: + - Only returns validation_status='valid' AND moderation_status='approved' + - Groups by mention_type (reply, like, repost, bookmark, mention) + - Sorts within groups by received_at ASC (oldest first) + + Args: + note_id: Note database ID + + Returns: + Dict with keys: 'replies', 'likes', 'reposts', 'bookmarks', 'mentions' + Each value is a list of webmention dicts + """ + db = get_db() + + # Query for approved webmentions only + query = """ + SELECT * FROM webmentions + WHERE target_note_id = ? + AND validation_status = 'valid' + AND moderation_status = 'approved' + ORDER BY + CASE mention_type + WHEN 'reply' THEN 1 + WHEN 'like' THEN 2 + WHEN 'repost' THEN 3 + WHEN 'bookmark' THEN 4 + WHEN 'mention' THEN 5 + END, + received_at ASC + """ + + rows = db.execute(query, (note_id,)).fetchall() + + # Group by type + grouped = { + 'replies': [], + 'likes': [], + 'reposts': [], + 'bookmarks': [], + 'mentions': [] + } + + for row in rows: + wm = dict(row) + # Parse received_at timestamp + if isinstance(wm.get('received_at'), str): + wm['received_at'] = datetime.fromisoformat(wm['received_at'].replace('Z', '+00:00')) + + mention_type = wm.get('mention_type', 'mention') + if mention_type == 'reply': + grouped['replies'].append(wm) + elif mention_type == 'like': + grouped['likes'].append(wm) + elif mention_type == 'repost': + grouped['reposts'].append(wm) + elif mention_type == 'bookmark': + grouped['bookmarks'].append(wm) + else: + grouped['mentions'].append(wm) + + return grouped + + +def list_webmentions( + status_filter: Optional[str] = None, + page: int = 1, + per_page: int = 25 +) -> tuple[List[Dict[str, Any]], int]: + """ + List webmentions for admin with pagination and filtering. + + Args: + status_filter: Filter by moderation_status ('pending', 'approved', 'hidden') + page: Page number (1-indexed) + per_page: Items per page (default: 25) + + Returns: + Tuple of (webmentions list, total_pages) + """ + db = get_db() + + # Build query + base_query = """ + SELECT w.*, n.slug as target_slug + FROM webmentions w + LEFT JOIN notes n ON w.target_note_id = n.id + """ + count_query = "SELECT COUNT(*) FROM webmentions" + + params = [] + where_clause = "" + + if status_filter: + where_clause = " WHERE w.moderation_status = ?" + count_query += " WHERE moderation_status = ?" + params.append(status_filter) + + # Count total + total_count = db.execute(count_query, params).fetchone()[0] + total_pages = math.ceil(total_count / per_page) if total_count > 0 else 1 + + # Get paginated results + offset = (page - 1) * per_page + query = base_query + where_clause + " ORDER BY w.received_at DESC LIMIT ? OFFSET ?" + params.extend([per_page, offset]) + + rows = db.execute(query, params).fetchall() + + # Convert to dicts + webmentions = [] + for row in rows: + wm = dict(row) + # Parse timestamps + if isinstance(wm.get('received_at'), str): + wm['received_at'] = datetime.fromisoformat(wm['received_at'].replace('Z', '+00:00')) + if wm.get('validated_at') and isinstance(wm['validated_at'], str): + wm['validated_at'] = datetime.fromisoformat(wm['validated_at'].replace('Z', '+00:00')) + webmentions.append(wm) + + return webmentions, total_pages + + +def get_webmention(webmention_id: int) -> Optional[Dict[str, Any]]: + """ + Get single webmention by ID. + + Args: + webmention_id: Webmention database ID + + Returns: + Webmention dict or None if not found + """ + db = get_db() + + query = """ + SELECT w.*, n.slug as target_slug + FROM webmentions w + LEFT JOIN notes n ON w.target_note_id = n.id + WHERE w.id = ? + """ + + row = db.execute(query, (webmention_id,)).fetchone() + + if not row: + return None + + wm = dict(row) + # Parse timestamps + if isinstance(wm.get('received_at'), str): + wm['received_at'] = datetime.fromisoformat(wm['received_at'].replace('Z', '+00:00')) + if wm.get('validated_at') and isinstance(wm['validated_at'], str): + wm['validated_at'] = datetime.fromisoformat(wm['validated_at'].replace('Z', '+00:00')) + + return wm + + +def count_webmentions(status_filter: Optional[str] = None) -> int: + """ + Count webmentions, optionally filtered by status. + + Args: + status_filter: Filter by moderation_status + + Returns: + Count of webmentions + """ + db = get_db() + + if status_filter: + query = "SELECT COUNT(*) FROM webmentions WHERE moderation_status = ?" + result = db.execute(query, (status_filter,)).fetchone() + else: + query = "SELECT COUNT(*) FROM webmentions" + result = db.execute(query).fetchone() + + return result[0] if result else 0 + + +def update_webmention_status(webmention_ids: List[int], status: str) -> int: + """ + Update moderation status for multiple webmentions. + + Args: + webmention_ids: List of webmention IDs + status: New moderation_status ('approved', 'hidden', 'pending') + + Returns: + Number of webmentions updated + """ + if not webmention_ids: + return 0 + + if status not in ('approved', 'hidden', 'pending'): + raise ValueError(f"Invalid status: {status}") + + db = get_db() + + # Use parameterized query with placeholders + placeholders = ','.join('?' * len(webmention_ids)) + query = f""" + UPDATE webmentions + SET moderation_status = ?, + updated_at = CURRENT_TIMESTAMP + WHERE id IN ({placeholders}) + """ + + params = [status] + webmention_ids + cursor = db.execute(query, params) + db.commit() + + return cursor.rowcount + + +def delete_webmentions(webmention_ids: List[int]) -> int: + """ + Delete webmentions by IDs. + + Args: + webmention_ids: List of webmention IDs to delete + + Returns: + Number of webmentions deleted + """ + if not webmention_ids: + return 0 + + db = get_db() + + placeholders = ','.join('?' * len(webmention_ids)) + query = f"DELETE FROM webmentions WHERE id IN ({placeholders})" + + cursor = db.execute(query, webmention_ids) + db.commit() + + return cursor.rowcount + + +def get_reply_context(url: str) -> Optional[Dict[str, Any]]: + """ + Get cached reply context for a URL. + + Args: + url: The in_reply_to URL + + Returns: + Reply context dict or None if not found + """ + db = get_db() + + query = "SELECT * FROM reply_contexts WHERE url = ?" + row = db.execute(query, (url,)).fetchone() + + if not row: + return None + + context = dict(row) + + # Parse timestamps + if context.get('fetched_at') and isinstance(context['fetched_at'], str): + context['fetched_at'] = datetime.fromisoformat(context['fetched_at'].replace('Z', '+00:00')) + if context.get('created_at') and isinstance(context['created_at'], str): + context['created_at'] = datetime.fromisoformat(context['created_at'].replace('Z', '+00:00')) + if context.get('published_at') and isinstance(context['published_at'], str): + context['published_at'] = datetime.fromisoformat(context['published_at'].replace('Z', '+00:00')) + + return context diff --git a/starpunk/webmention_sender.py b/starpunk/webmention_sender.py new file mode 100644 index 0000000..f583374 --- /dev/null +++ b/starpunk/webmention_sender.py @@ -0,0 +1,198 @@ +""" +Outgoing webmention link extraction and queueing + +Per background-worker.md and architect's answers: +- Extract links from rendered HTML (not markdown) +- Extract only elements, exclude
 and  blocks
+- Queue max 10 links per note per operation
+- Priority: in_reply_to first, then document order
+
+References:
+    - Background Worker Design: /docs/design/v1.6.0/background-worker.md
+    - API Contract: /docs/design/v1.6.0/api-contract.md
+"""
+
+import logging
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Set
+from lxml import html as lxml_html
+from urllib.parse import urlparse
+
+
+logger = logging.getLogger(__name__)
+
+
+def extract_links_from_html(html_content: str, exclude_code_blocks: bool = True) -> list[str]:
+    """
+    Extract links from HTML content.
+
+    Per architect's answer to Q1:
+    - Extract from rendered HTML (not markdown)
+    - Extract  elements only
+    - Exclude links in 
 and  blocks
+    - Return in document order
+
+    Args:
+        html_content: Rendered HTML content
+        exclude_code_blocks: If True, skip links in 
 and  (default: True)
+
+    Returns:
+        List of URLs in document order
+    """
+    if not html_content or not html_content.strip():
+        return []
+
+    try:
+        # Parse HTML
+        doc = lxml_html.fromstring(html_content)
+
+        if exclude_code_blocks:
+            # Remove 
 and  elements before extracting links
+            for element in doc.xpath('//pre | //code'):
+                element.getparent().remove(element)
+
+        # Extract all  attributes in document order
+        links = doc.xpath('//a/@href')
+
+        # Filter to valid absolute URLs (http/https)
+        absolute_links = []
+        for link in links:
+            parsed = urlparse(link)
+            if parsed.scheme in ('http', 'https') and parsed.netloc:
+                absolute_links.append(link)
+
+        return absolute_links
+
+    except Exception as e:
+        logger.warning(f"Failed to parse HTML for link extraction: {e}")
+        return []
+
+
+def queue_webmentions_for_note(
+    db_path: Path,
+    note_id: int,
+    note_url: str,
+    content_html: str,
+    in_reply_to: Optional[str] = None,
+    old_content_html: Optional[str] = None  # Phase 6: update semantics
+) -> int:
+    """
+    Extract links and queue webmentions for a note.
+
+    Per architect's answers (Phase 6):
+    - Called from notes.py AFTER successful database commit
+    - For updates: diff old vs new URLs, queue for new/existing/removed
+    - For creates: queue for all URLs in content
+    - Max 10 webmentions per operation
+    - Priority: in_reply_to URL first, then document order
+    - Webmention sending is best-effort; failures do not affect note creation
+
+    Args:
+        db_path: Path to SQLite database
+        note_id: Database ID of the note
+        note_url: Full URL of the published note
+        content_html: Rendered HTML content (None if unpublishing)
+        in_reply_to: Reply-to URL (if reply post)
+        old_content_html: Previous HTML (for update diff, Phase 6)
+
+    Returns:
+        Number of webmentions queued
+    """
+    # Phase 6: Implement URL diffing for updates
+    if old_content_html is not None:
+        # This is an update - compute URL diff
+        old_links = set(extract_links_from_html(old_content_html))
+
+        # Handle unpublishing case (content_html is None)
+        if content_html is None:
+            # Unpublishing - queue for all old URLs (they're all removed)
+            new_links = set()
+        else:
+            new_links = set(extract_links_from_html(content_html))
+
+        # Compute sets for URL diffing
+        new_urls = new_links - old_links  # In new, not in old
+        existing_urls = new_links & old_links  # In both (re-validate)
+        removed_urls = old_links - new_links  # In old, not in new
+
+        # Build target list: new + existing + removed
+        # (All need webmentions per W3C spec)
+        all_update_urls = list(new_urls) + list(existing_urls) + list(removed_urls)
+
+        # Add in_reply_to if changed
+        target_urls = []
+        if in_reply_to and in_reply_to not in all_update_urls:
+            target_urls.append(in_reply_to)
+
+        # Add the diffed URLs
+        target_urls.extend(all_update_urls)
+
+        # Limit to 10
+        target_urls = target_urls[:10]
+
+    else:
+        # This is a create (no old content) - use original logic
+        links = extract_links_from_html(content_html) if content_html else []
+
+        # Build priority-ordered list of target URLs
+        target_urls = []
+
+        # 1. in_reply_to gets highest priority
+        if in_reply_to:
+            target_urls.append(in_reply_to)
+
+        # 2. Add extracted links in document order (deduplicated)
+        seen = {in_reply_to} if in_reply_to else set()
+        for link in links:
+            if link not in seen:
+                target_urls.append(link)
+                seen.add(link)
+
+        # 3. Limit to 10 webmentions per operation
+        target_urls = target_urls[:10]
+
+    if not target_urls:
+        logger.debug(f"No links to send webmentions for note {note_id}")
+        return 0
+
+    # Queue webmentions
+    queued = 0
+    try:
+        conn = sqlite3.connect(db_path)
+        cursor = conn.cursor()
+
+        for target_url in target_urls:
+            try:
+                # Use UPSERT to handle duplicate sends
+                # Phase 6: Force endpoint rediscovery per W3C MUST requirement
+                cursor.execute("""
+                    INSERT INTO webmention_queue
+                        (source_url, target_url, source_note_id, status, created_at)
+                    VALUES (?, ?, ?, 'pending', CURRENT_TIMESTAMP)
+                    ON CONFLICT(source_url, target_url) DO UPDATE SET
+                        status = 'pending',
+                        retry_count = 0,
+                        next_retry_at = NULL,
+                        last_error = NULL,
+                        endpoint_url = NULL,
+                        created_at = CURRENT_TIMESTAMP
+                """, (note_url, target_url, note_id))
+
+                queued += 1
+
+            except Exception as e:
+                logger.warning(
+                    f"Failed to queue webmention {note_url} -> {target_url}: {e}"
+                )
+
+        conn.commit()
+        conn.close()
+
+        logger.info(f"Queued {queued} webmentions for note {note_id}")
+
+    except Exception as e:
+        logger.error(f"Failed to queue webmentions for note {note_id}: {e}")
+
+    return queued
diff --git a/starpunk/webmention_ssrf.py b/starpunk/webmention_ssrf.py
new file mode 100644
index 0000000..5f0c794
--- /dev/null
+++ b/starpunk/webmention_ssrf.py
@@ -0,0 +1,113 @@
+"""
+SSRF protection utilities for webmention processing
+
+Per ADR-063 Decision 9 and background-worker.md:
+- Block private IP address ranges
+- Resolve hostname before making requests
+- DEV_MODE exception for localhost testing
+- Applied to all outgoing HTTP requests
+
+References:
+    - ADR-063: Webmention Implementation
+    - Background Worker Design: /docs/design/v1.6.0/background-worker.md
+"""
+
+import ipaddress
+import socket
+from flask import current_app
+
+
+class SSRFBlockedError(Exception):
+    """Raised when SSRF protection blocks a request"""
+    pass
+
+
+# Private IP ranges per RFC 1918 and link-local ranges
+BLOCKED_NETWORKS = [
+    ipaddress.ip_network('10.0.0.0/8'),         # RFC 1918 private
+    ipaddress.ip_network('172.16.0.0/12'),      # RFC 1918 private
+    ipaddress.ip_network('192.168.0.0/16'),     # RFC 1918 private
+    ipaddress.ip_network('127.0.0.0/8'),        # Localhost
+    ipaddress.ip_network('169.254.0.0/16'),     # Link-local
+    ipaddress.ip_network('::1/128'),            # IPv6 localhost
+    ipaddress.ip_network('fc00::/7'),           # IPv6 unique local
+    ipaddress.ip_network('fe80::/10'),          # IPv6 link-local
+]
+
+
+def is_private_ip(ip: str) -> bool:
+    """
+    Check if IP address is in a private/blocked range.
+
+    Args:
+        ip: IP address string (IPv4 or IPv6)
+
+    Returns:
+        True if IP is private/blocked, False otherwise
+    """
+    try:
+        addr = ipaddress.ip_address(ip)
+        return any(addr in network for network in BLOCKED_NETWORKS)
+    except ValueError:
+        # Invalid IP format, treat as blocked
+        return True
+
+
+def safe_resolve(hostname: str) -> str:
+    """
+    Resolve hostname and validate IP is not private.
+
+    Per background-worker.md: DEV_MODE exception for localhost testing.
+
+    Args:
+        hostname: Hostname to resolve
+
+    Returns:
+        Resolved IP address if safe
+
+    Raises:
+        SSRFBlockedError: If hostname resolves to private IP
+        socket.gaierror: If hostname cannot be resolved
+    """
+    # DEV_MODE exception for localhost
+    if current_app.config.get('DEV_MODE') and hostname in ('localhost', '127.0.0.1', '::1'):
+        return '127.0.0.1'
+
+    # Resolve hostname
+    ip = socket.gethostbyname(hostname)
+
+    # Check if resolved IP is private
+    if is_private_ip(ip):
+        raise SSRFBlockedError(f"Blocked request to private IP: {ip}")
+
+    return ip
+
+
+def validate_url_for_fetch(url: str) -> None:
+    """
+    Validate URL is safe to fetch (not private IP).
+
+    Args:
+        url: URL to validate
+
+    Raises:
+        SSRFBlockedError: If URL points to private IP
+        ValueError: If URL is malformed
+    """
+    from urllib.parse import urlparse
+
+    parsed = urlparse(url)
+
+    if not parsed.scheme in ('http', 'https'):
+        raise ValueError(f"Unsupported URL scheme: {parsed.scheme}")
+
+    if not parsed.netloc:
+        raise ValueError("URL must include a hostname")
+
+    # Extract hostname (remove port if present)
+    hostname = parsed.hostname
+    if not hostname:
+        raise ValueError("Could not extract hostname from URL")
+
+    # Validate hostname resolves to public IP
+    safe_resolve(hostname)
diff --git a/starpunk/webmention_worker.py b/starpunk/webmention_worker.py
new file mode 100644
index 0000000..93b3586
--- /dev/null
+++ b/starpunk/webmention_worker.py
@@ -0,0 +1,787 @@
+"""
+Background worker thread for webmention processing
+
+Per background-worker.md:
+- Daemon thread that processes webmention queues
+- Handles both incoming validation and outgoing sending
+- Graceful shutdown on app termination
+- Orphan detection and cleanup on startup
+
+References:
+    - Background Worker Design: /docs/design/v1.6.0/background-worker.md
+    - ADR-063: Webmention Implementation
+"""
+
+import logging
+import threading
+import time
+import sqlite3
+import httpx
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Dict, Any, Optional, TypedDict
+from urllib.parse import urlparse
+from lxml import html as lxml_html
+
+from starpunk.webmention_processor import process_webmention, ValidationError
+from starpunk.webmention_ssrf import validate_url_for_fetch, SSRFBlockedError
+from flask import has_app_context
+
+
+logger = logging.getLogger(__name__)
+
+
+# Discovery cache entry type
+class DiscoveryCacheEntry(TypedDict):
+    """Cache entry for endpoint discovery results"""
+    endpoint: Optional[str]  # None = negative cache (no endpoint found)
+    expires_at: datetime
+
+
+class WebmentionWorker(threading.Thread):
+    """
+    Background thread for webmention queue processing
+
+    Follows MemoryMonitor pattern: daemon thread with stop event
+    """
+
+    def __init__(
+        self,
+        db_path: Path,
+        site_url: str,
+        poll_interval: int = 10,
+        error_backoff: int = 60,
+        batch_size: int = 5,
+        auto_approve: bool = True
+    ):
+        """
+        Initialize webmention worker thread
+
+        Args:
+            db_path: Path to SQLite database
+            site_url: Site URL for User-Agent header
+            poll_interval: Seconds between queue checks (default: 10)
+            error_backoff: Seconds to wait after error (default: 60)
+            batch_size: Items to process per iteration (default: 5)
+            auto_approve: Auto-approve valid webmentions (default: True)
+        """
+        super().__init__(daemon=True, name="webmention-worker")
+        self.db_path = db_path
+        self.site_url = site_url
+        self.poll_interval = poll_interval
+        self.error_backoff = error_backoff
+        self.batch_size = batch_size
+        self.auto_approve = auto_approve
+        self._stop_event = threading.Event()
+        self._last_processed = None
+
+        # Phase 3: Discovery cache (worker instance variable)
+        # Per architect's answer to Q4
+        self._discovery_cache: Dict[str, DiscoveryCacheEntry] = {}
+
+    def run(self):
+        """
+        Main processing loop
+
+        Per background-worker.md:
+        1. Clean up orphaned items on startup
+        2. Process pending validations (incoming)
+        3. Process pending sends (outgoing) - Phase 3
+        4. Sleep if nothing to process
+        """
+        try:
+            logger.info("Webmention worker started")
+
+            # Cleanup orphaned items from previous crashes
+            self._cleanup_orphaned_items()
+
+            # Main processing loop
+            while not self._stop_event.is_set():
+                try:
+                    processed = 0
+
+                    # Process incoming webmentions
+                    processed += self._process_pending_validations()
+
+                    # Phase 3: Process outgoing webmentions
+                    processed += self._process_pending_sends()
+
+                    # Update last processed time
+                    if processed > 0:
+                        self._last_processed = datetime.utcnow()
+
+                    # Sleep if nothing processed
+                    if processed == 0:
+                        self._stop_event.wait(self.poll_interval)
+
+                except Exception as e:
+                    logger.error(f"Worker error: {e}", exc_info=True)
+                    self._stop_event.wait(self.error_backoff)
+
+        except Exception as e:
+            logger.error(f"Webmention worker thread failed: {e}", exc_info=True)
+        finally:
+            logger.info("Webmention worker stopped")
+
+    def _cleanup_orphaned_items(self):
+        """
+        Clean up orphaned 'sending' status items on startup
+
+        Per background-worker.md:
+        Reset items stuck in 'sending' status from previous crashes
+        """
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+
+            # Reset orphaned outgoing webmentions
+            cursor.execute("""
+                UPDATE webmention_queue
+                SET status = 'pending',
+                    started_at = NULL
+                WHERE status = 'sending'
+                  AND started_at < datetime('now', '-5 minutes')
+            """)
+
+            orphaned = cursor.rowcount
+            conn.commit()
+            conn.close()
+
+            if orphaned > 0:
+                logger.info(f"Reset {orphaned} orphaned webmention queue items")
+
+        except Exception as e:
+            logger.error(f"Failed to cleanup orphaned items: {e}")
+
+    def _process_pending_validations(self) -> int:
+        """
+        Process pending incoming webmentions
+
+        Returns:
+            Number of webmentions processed
+        """
+        processed = 0
+
+        try:
+            conn = sqlite3.connect(self.db_path)
+            conn.row_factory = sqlite3.Row
+            cursor = conn.cursor()
+
+            # Get pending webmentions
+            cursor.execute("""
+                SELECT id, source_url, target_url, target_note_id
+                FROM webmentions
+                WHERE validation_status = 'pending'
+                ORDER BY received_at ASC
+                LIMIT ?
+            """, (self.batch_size,))
+
+            pending = cursor.fetchall()
+            conn.close()
+
+            # Process each webmention
+            for row in pending:
+                try:
+                    self._validate_webmention(
+                        row['id'],
+                        row['source_url'],
+                        row['target_url'],
+                        row['target_note_id']
+                    )
+                    processed += 1
+                except Exception as e:
+                    logger.error(
+                        f"Failed to validate webmention {row['id']}: {e}",
+                        exc_info=True
+                    )
+
+        except Exception as e:
+            logger.error(f"Error fetching pending validations: {e}")
+
+        return processed
+
+    def _validate_webmention(
+        self,
+        webmention_id: int,
+        source_url: str,
+        target_url: str,
+        target_note_id: Optional[int]
+    ):
+        """
+        Validate a single webmention
+
+        Args:
+            webmention_id: Database ID of webmention
+            source_url: Source URL
+            target_url: Target URL
+            target_note_id: Target note ID (if applicable)
+        """
+        try:
+            # Process webmention (fetch, validate, extract)
+            result = process_webmention(source_url, target_url, self.site_url)
+
+            # Update database with successful validation
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+
+            moderation_status = 'approved' if self.auto_approve else 'pending'
+
+            cursor.execute("""
+                UPDATE webmentions
+                SET validation_status = 'valid',
+                    validated_at = CURRENT_TIMESTAMP,
+                    mention_type = ?,
+                    author_name = ?,
+                    author_url = ?,
+                    author_photo = ?,
+                    content_snippet = ?,
+                    moderation_status = ?,
+                    updated_at = CURRENT_TIMESTAMP
+                WHERE id = ?
+            """, (
+                result['mention_type'],
+                result['author_name'],
+                result['author_url'],
+                result['author_photo'],
+                result['content_snippet'],
+                moderation_status,
+                webmention_id
+            ))
+
+            conn.commit()
+            conn.close()
+
+            logger.info(
+                f"Validated webmention: {source_url} -> {target_url} "
+                f"(type={result['mention_type']}, status={moderation_status})"
+            )
+
+        except ValidationError as e:
+            # Validation failed - update with error
+            self._mark_validation_failed(webmention_id, source_url, target_url, str(e))
+
+        except Exception as e:
+            # Unexpected error - mark as error
+            self._mark_validation_failed(
+                webmention_id,
+                source_url,
+                target_url,
+                f"Unexpected error: {e}"
+            )
+            raise
+
+    def _mark_validation_failed(
+        self,
+        webmention_id: int,
+        source_url: str,
+        target_url: str,
+        error: str
+    ):
+        """
+        Mark webmention validation as failed/invalid
+
+        Args:
+            webmention_id: Database ID
+            source_url: Source URL
+            target_url: Target URL
+            error: Error message
+        """
+        # Determine if error or invalid
+        # Per background-worker.md: HTTP 4xx and "no link" are invalid
+        # All other errors are 'error' status
+        if any(x in error.lower() for x in ['does not link', 'returned 4']):
+            status = 'invalid'
+        else:
+            status = 'error'
+
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+
+            cursor.execute("""
+                UPDATE webmentions
+                SET validation_status = ?,
+                    validation_error = ?,
+                    validated_at = CURRENT_TIMESTAMP,
+                    updated_at = CURRENT_TIMESTAMP
+                WHERE id = ?
+            """, (status, error, webmention_id))
+
+            conn.commit()
+            conn.close()
+
+            logger.warning(
+                f"Invalid webmention: {source_url} -> {target_url}: {error}"
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to mark webmention as failed: {e}")
+
+    def _process_pending_sends(self) -> int:
+        """
+        Process pending outgoing webmentions (Phase 3)
+
+        Returns:
+            Number of webmentions processed
+        """
+        processed = 0
+
+        try:
+            conn = sqlite3.connect(self.db_path)
+            conn.row_factory = sqlite3.Row
+            cursor = conn.cursor()
+
+            # Get pending webmentions ready to send
+            cursor.execute("""
+                SELECT id, source_url, target_url, endpoint_url, retry_count
+                FROM webmention_queue
+                WHERE status = 'pending'
+                  AND (next_retry_at IS NULL OR next_retry_at <= datetime('now'))
+                ORDER BY created_at ASC
+                LIMIT ?
+            """, (self.batch_size,))
+
+            pending = cursor.fetchall()
+            conn.close()
+
+            # Process each webmention
+            for row in pending:
+                try:
+                    self._send_webmention(
+                        row['id'],
+                        row['source_url'],
+                        row['target_url'],
+                        row['endpoint_url'],
+                        row['retry_count']
+                    )
+                    processed += 1
+                except Exception as e:
+                    logger.error(
+                        f"Failed to send webmention {row['id']}: {e}",
+                        exc_info=True
+                    )
+
+        except Exception as e:
+            logger.error(f"Error fetching pending sends: {e}")
+
+        return processed
+
+    def _send_webmention(
+        self,
+        queue_id: int,
+        source_url: str,
+        target_url: str,
+        cached_endpoint: Optional[str],
+        retry_count: int
+    ):
+        """
+        Send a single outgoing webmention
+
+        Args:
+            queue_id: Database ID of queue item
+            source_url: Source URL (our note)
+            target_url: Target URL to notify
+            cached_endpoint: Previously discovered endpoint (if any)
+            retry_count: Current retry count
+        """
+        # Mark as sending
+        conn = sqlite3.connect(self.db_path)
+        cursor = conn.cursor()
+        cursor.execute("""
+            UPDATE webmention_queue
+            SET status = 'sending',
+                started_at = CURRENT_TIMESTAMP
+            WHERE id = ?
+        """, (queue_id,))
+        conn.commit()
+        conn.close()
+
+        try:
+            # Discover endpoint if not cached
+            endpoint = cached_endpoint
+            if not endpoint:
+                endpoint = self._discover_endpoint(target_url)
+
+                if not endpoint:
+                    # No endpoint found - permanent failure
+                    self._mark_send_no_endpoint(queue_id, source_url, target_url)
+                    return
+
+                # Cache the discovered endpoint in database
+                conn = sqlite3.connect(self.db_path)
+                cursor = conn.cursor()
+                cursor.execute("""
+                    UPDATE webmention_queue
+                    SET endpoint_url = ?
+                    WHERE id = ?
+                """, (endpoint, queue_id))
+                conn.commit()
+                conn.close()
+
+            # Send webmention POST
+            try:
+                # SSRF protection for endpoint URL
+                validate_url_for_fetch(endpoint)
+
+                response = httpx.post(
+                    endpoint,
+                    data={
+                        'source': source_url,
+                        'target': target_url
+                    },
+                    timeout=10,
+                    headers={'User-Agent': f'StarPunk/1.6.0 (+{self.site_url})'},
+                    follow_redirects=True
+                )
+
+                # Check response
+                if 200 <= response.status_code < 300:
+                    # Success
+                    self._mark_send_success(queue_id, source_url, target_url)
+
+                elif 400 <= response.status_code < 500:
+                    # Permanent failure (4xx)
+                    error = f"HTTP {response.status_code}: {response.text[:200]}"
+                    self._mark_send_failed(queue_id, source_url, target_url, error)
+
+                else:
+                    # Temporary failure (5xx) - retry
+                    error = f"HTTP {response.status_code}: {response.text[:200]}"
+                    self._mark_send_retry(queue_id, source_url, target_url, retry_count, error)
+
+            except (httpx.TimeoutException, httpx.HTTPError) as e:
+                # Connection error - retry
+                self._mark_send_retry(queue_id, source_url, target_url, retry_count, str(e))
+
+            except (SSRFBlockedError, ValueError) as e:
+                # SSRF blocked - permanent failure
+                logger.warning(f"SSRF blocked endpoint {endpoint}: {e}")
+                self._mark_send_failed(queue_id, source_url, target_url, f"Blocked: {e}")
+
+        except Exception as e:
+            # Discovery failed - retry
+            self._mark_send_retry(queue_id, source_url, target_url, retry_count, str(e))
+
+    def _discover_endpoint(self, target_url: str) -> Optional[str]:
+        """
+        Discover webmention endpoint for target URL with caching
+
+        Per architect's answers to Q3, Q4, Q10:
+        - GET only (no HEAD)
+        - Check Link header →  → 
+        - First match wins
+        - Cache results: 1h for found, 24h for not found
+        - SSRF protection on target URL
+
+        Args:
+            target_url: Target URL to discover endpoint for
+
+        Returns:
+            Endpoint URL if found, None otherwise
+        """
+        # Check cache first
+        cached = self._discovery_cache.get(target_url)
+        if cached and cached['expires_at'] > datetime.utcnow():
+            logger.debug(f"Using cached endpoint for {target_url}: {cached['endpoint']}")
+            return cached['endpoint']
+
+        # SSRF protection
+        try:
+            validate_url_for_fetch(target_url)
+        except (SSRFBlockedError, ValueError) as e:
+            logger.warning(f"SSRF protection blocked target {target_url}: {e}")
+            # Cache negative result
+            self._cache_endpoint(target_url, None, hours=24)
+            return None
+
+        # Fetch target URL
+        try:
+            response = httpx.get(
+                target_url,
+                timeout=10,
+                headers={'User-Agent': f'StarPunk/1.6.0 (+{self.site_url})'},
+                follow_redirects=True
+            )
+            response.raise_for_status()
+
+            # 1. Check Link header
+            link_header = response.headers.get('Link', '')
+            if link_header:
+                endpoint = self._parse_link_header(link_header, response.url)
+                if endpoint:
+                    self._cache_endpoint(target_url, endpoint, hours=1)
+                    return endpoint
+
+            # 2. Parse HTML for  and  elements
+            content_type = response.headers.get('Content-Type', '')
+            if 'html' in content_type.lower():
+                endpoint = self._parse_html_for_endpoint(response.text, response.url)
+                if endpoint:
+                    self._cache_endpoint(target_url, endpoint, hours=1)
+                    return endpoint
+
+            # No endpoint found - cache negative result
+            logger.info(f"No webmention endpoint found for {target_url}")
+            self._cache_endpoint(target_url, None, hours=24)
+            return None
+
+        except Exception as e:
+            logger.warning(f"Failed to discover endpoint for {target_url}: {e}")
+            # Don't cache on error - allow retry
+            return None
+
+    def _parse_link_header(self, link_header: str, base_url: str) -> Optional[str]:
+        """
+        Parse Link header for webmention endpoint
+
+        Args:
+            link_header: Raw Link header value
+            base_url: Base URL for resolving relative URLs
+
+        Returns:
+            Absolute endpoint URL if found, None otherwise
+        """
+        # Simple parsing - look for rel="webmention"
+        # Format: ; rel="webmention"
+        import re
+        pattern = r'<([^>]+)>\s*;\s*rel\s*=\s*["\']?webmention["\']?'
+        match = re.search(pattern, link_header, re.IGNORECASE)
+
+        if match:
+            endpoint = match.group(1)
+            # Make absolute if relative
+            from urllib.parse import urljoin
+            return urljoin(base_url, endpoint)
+
+        return None
+
+    def _parse_html_for_endpoint(self, html_content: str, base_url: str) -> Optional[str]:
+        """
+        Parse HTML for webmention endpoint in  or  elements
+
+        Args:
+            html_content: HTML content
+            base_url: Base URL for resolving relative URLs
+
+        Returns:
+            Absolute endpoint URL if found, None otherwise
+        """
+        try:
+            doc = lxml_html.fromstring(html_content)
+
+            # Check  first
+            links = doc.xpath('//link[@rel="webmention"]/@href')
+            if links:
+                from urllib.parse import urljoin
+                return urljoin(base_url, links[0])
+
+            # Check 
+            anchors = doc.xpath('//a[@rel="webmention"]/@href')
+            if anchors:
+                from urllib.parse import urljoin
+                return urljoin(base_url, anchors[0])
+
+        except Exception as e:
+            logger.debug(f"HTML parsing failed: {e}")
+
+        return None
+
+    def _cache_endpoint(self, target_url: str, endpoint: Optional[str], hours: int):
+        """
+        Cache endpoint discovery result
+
+        Args:
+            target_url: Target URL
+            endpoint: Discovered endpoint (None = negative cache)
+            hours: TTL in hours
+        """
+        self._discovery_cache[target_url] = {
+            'endpoint': endpoint,
+            'expires_at': datetime.utcnow() + timedelta(hours=hours)
+        }
+
+        # Optional: Evict old entries (keep cache bounded)
+        if len(self._discovery_cache) > 1000:
+            # Remove expired entries
+            now = datetime.utcnow()
+            self._discovery_cache = {
+                k: v for k, v in self._discovery_cache.items()
+                if v['expires_at'] > now
+            }
+
+    def _mark_send_success(self, queue_id: int, source_url: str, target_url: str):
+        """Mark webmention send as successful"""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            cursor.execute("""
+                UPDATE webmention_queue
+                SET status = 'sent',
+                    sent_at = CURRENT_TIMESTAMP
+                WHERE id = ?
+            """, (queue_id,))
+            conn.commit()
+            conn.close()
+
+            logger.info(f"Sent webmention: {source_url} -> {target_url}")
+
+        except Exception as e:
+            logger.error(f"Failed to mark send success: {e}")
+
+    def _mark_send_failed(self, queue_id: int, source_url: str, target_url: str, error: str):
+        """Mark webmention send as permanently failed"""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            cursor.execute("""
+                UPDATE webmention_queue
+                SET status = 'failed',
+                    last_error = ?
+                WHERE id = ?
+            """, (error, queue_id))
+            conn.commit()
+            conn.close()
+
+            logger.warning(f"Webmention send failed permanently: {source_url} -> {target_url}: {error}")
+
+        except Exception as e:
+            logger.error(f"Failed to mark send failed: {e}")
+
+    def _mark_send_no_endpoint(self, queue_id: int, source_url: str, target_url: str):
+        """Mark webmention as no endpoint found"""
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+            cursor.execute("""
+                UPDATE webmention_queue
+                SET status = 'no_endpoint'
+                WHERE id = ?
+            """, (queue_id,))
+            conn.commit()
+            conn.close()
+
+            logger.info(f"No webmention endpoint for {target_url}")
+
+        except Exception as e:
+            logger.error(f"Failed to mark no endpoint: {e}")
+
+    def _mark_send_retry(
+        self,
+        queue_id: int,
+        source_url: str,
+        target_url: str,
+        current_retry_count: int,
+        error: str
+    ):
+        """
+        Mark webmention for retry with exponential backoff
+
+        Per architect's answer to Q5 and background-worker.md:
+        - Increment retry_count AFTER failed attempt
+        - Check retry_count >= 4 AFTER incrementing
+        - Retry schedule: 1h, 6h, 24h
+        """
+        new_retry_count = current_retry_count + 1
+
+        # Calculate next retry time
+        next_retry_at = None
+        if new_retry_count < 4:
+            delays = {
+                1: timedelta(hours=1),
+                2: timedelta(hours=6),
+                3: timedelta(hours=24),
+            }
+            delay = delays.get(new_retry_count)
+            if delay:
+                next_retry_at = datetime.utcnow() + delay
+
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+
+            if new_retry_count >= 4:
+                # Max retries reached - mark as failed
+                cursor.execute("""
+                    UPDATE webmention_queue
+                    SET status = 'failed',
+                        retry_count = ?,
+                        last_error = ?
+                    WHERE id = ?
+                """, (new_retry_count, error, queue_id))
+
+                logger.warning(
+                    f"Webmention send failed permanently after {new_retry_count} attempts: "
+                    f"{source_url} -> {target_url}: {error}"
+                )
+
+            else:
+                # Schedule retry
+                cursor.execute("""
+                    UPDATE webmention_queue
+                    SET status = 'pending',
+                        retry_count = ?,
+                        next_retry_at = ?,
+                        last_error = ?
+                    WHERE id = ?
+                """, (new_retry_count, next_retry_at, error, queue_id))
+
+                logger.warning(
+                    f"Webmention send failed, retry {new_retry_count}: "
+                    f"{source_url} -> {target_url}: {error}"
+                )
+
+            conn.commit()
+            conn.close()
+
+        except Exception as e:
+            logger.error(f"Failed to mark send retry: {e}")
+
+    def stop(self):
+        """
+        Stop the worker thread gracefully
+
+        Sets the stop event to signal the thread to exit
+        """
+        logger.info("Stopping webmention worker")
+        self._stop_event.set()
+
+    def get_stats(self) -> Dict[str, Any]:
+        """
+        Get current worker statistics
+
+        Returns:
+            Dict with worker stats for health check
+        """
+        try:
+            conn = sqlite3.connect(self.db_path)
+            cursor = conn.cursor()
+
+            # Count pending validations
+            cursor.execute("""
+                SELECT COUNT(*) FROM webmentions
+                WHERE validation_status = 'pending'
+            """)
+            pending_validations = cursor.fetchone()[0]
+
+            # Count pending sends (Phase 3)
+            cursor.execute("""
+                SELECT COUNT(*) FROM webmention_queue
+                WHERE status = 'pending'
+            """)
+            pending_sends = cursor.fetchone()[0]
+
+            conn.close()
+
+            return {
+                'running': self.is_alive(),
+                'last_processed': self._last_processed.isoformat() if self._last_processed else None,
+                'pending_validations': pending_validations,
+                'pending_sends': pending_sends
+            }
+
+        except Exception as e:
+            logger.error(f"Failed to get worker stats: {e}")
+            return {
+                'running': self.is_alive(),
+                'error': str(e)
+            }
diff --git a/static/css/style.css b/static/css/style.css
index 72203da..12660cb 100644
--- a/static/css/style.css
+++ b/static/css/style.css
@@ -191,3 +191,265 @@ small { display: block; margin-top: var(--spacing-xs); color: var(--color-text-l
     aspect-ratio: 16 / 9; /* Wider aspect on mobile */
   }
 }
+
+/* Webmention Styles (v1.6.0 Phase 5) */
+
+/* Reply Context */
+.reply-context {
+  margin-bottom: var(--spacing-md);
+  padding: var(--spacing-sm);
+  border-left: 3px solid var(--color-link);
+  background: var(--color-bg-alt);
+}
+
+.reply-context .reply-label {
+  font-size: 0.875rem;
+  color: var(--color-text-light);
+  display: block;
+  margin-bottom: var(--spacing-xs);
+}
+
+.reply-context blockquote {
+  margin: 0;
+  padding: 0;
+}
+
+.reply-context .p-content {
+  font-style: italic;
+  margin-bottom: var(--spacing-xs);
+}
+
+/* Webmentions Section */
+.webmentions {
+  margin-top: var(--spacing-lg);
+  padding-top: var(--spacing-lg);
+  border-top: 1px solid var(--color-border);
+}
+
+.webmentions h2 {
+  margin-bottom: var(--spacing-md);
+}
+
+.webmention-group {
+  margin-bottom: var(--spacing-lg);
+}
+
+.webmention-group h3 {
+  font-size: 1rem;
+  margin-bottom: var(--spacing-sm);
+  color: var(--color-text-light);
+}
+
+/* Reply Webmentions */
+.webmention-reply {
+  margin-bottom: var(--spacing-md);
+  padding: var(--spacing-sm);
+  background: var(--color-bg-alt);
+  border-radius: 4px;
+}
+
+.webmention-author {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-sm);
+  margin-bottom: var(--spacing-xs);
+}
+
+.webmention-author img {
+  border-radius: 50%;
+}
+
+.webmention-author a {
+  font-weight: bold;
+}
+
+.webmention-date {
+  font-size: 0.875rem;
+  color: var(--color-text-light);
+}
+
+/* Facepile */
+.facepile {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+}
+
+.facepile .face {
+  display: block;
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  overflow: hidden;
+  border: 2px solid var(--color-bg);
+  margin-left: -8px;
+}
+
+.facepile .face:first-child {
+  margin-left: 0;
+}
+
+.facepile .face img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+
+.facepile .face-initial {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  font-size: 14px;
+  font-weight: bold;
+  color: white;
+}
+
+.facepile .face-overflow {
+  margin-left: var(--spacing-xs);
+  font-size: 0.875rem;
+  color: var(--color-text-light);
+}
+
+/* Generic Mentions */
+.webmention-mention {
+  margin-bottom: var(--spacing-sm);
+  padding: var(--spacing-xs);
+  background: var(--color-bg-alt);
+  border-radius: 4px;
+}
+
+.webmention-mention p {
+  margin: var(--spacing-xs) 0 0 0;
+  font-size: 0.875rem;
+  color: var(--color-text-light);
+}
+
+/* Admin Webmention Styles */
+
+.filter-tabs {
+  display: flex;
+  gap: var(--spacing-sm);
+  margin-bottom: var(--spacing-md);
+  border-bottom: 1px solid var(--color-border);
+}
+
+.filter-tabs a {
+  padding: var(--spacing-sm) var(--spacing-md);
+  text-decoration: none;
+  color: var(--color-text-light);
+  border-bottom: 2px solid transparent;
+}
+
+.filter-tabs a.active {
+  color: var(--color-link);
+  border-bottom-color: var(--color-link);
+}
+
+.bulk-actions {
+  display: flex;
+  gap: var(--spacing-sm);
+  margin-bottom: var(--spacing-md);
+}
+
+.webmention-table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.webmention-table th,
+.webmention-table td {
+  padding: var(--spacing-sm);
+  text-align: left;
+  border-bottom: 1px solid var(--color-border);
+}
+
+.webmention-table th {
+  background: var(--color-bg-alt);
+  font-weight: bold;
+}
+
+.badge {
+  display: inline-block;
+  padding: 0.25rem 0.5rem;
+  font-size: 0.75rem;
+  border-radius: 4px;
+  background: var(--color-bg-alt);
+}
+
+.badge-reply { background: #DBEAFE; color: #1E40AF; }
+.badge-like { background: #FECACA; color: #991B1B; }
+.badge-repost { background: #D1FAE5; color: #065F46; }
+.badge-bookmark { background: #FEF3C7; color: #92400E; }
+.badge-mention { background: #E5E7EB; color: #374151; }
+
+.status-badge {
+  display: inline-block;
+  padding: 0.25rem 0.5rem;
+  font-size: 0.75rem;
+  border-radius: 4px;
+  font-weight: 600;
+}
+
+.status-pending { background: #FEF3C7; color: #92400E; }
+.status-approved { background: #D1FAE5; color: #065F46; }
+.status-hidden { background: #E5E7EB; color: #6B7280; }
+.status-valid { background: #D1FAE5; color: #065F46; }
+.status-invalid { background: #FECACA; color: #991B1B; }
+.status-error { background: #FECACA; color: #991B1B; }
+
+.pagination {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-md);
+  justify-content: center;
+  margin-top: var(--spacing-lg);
+}
+
+.detail-card {
+  background: var(--color-bg-alt);
+  padding: var(--spacing-md);
+  border-radius: 4px;
+  margin-bottom: var(--spacing-lg);
+}
+
+.detail-row {
+  margin-bottom: var(--spacing-md);
+}
+
+.detail-row strong {
+  display: block;
+  margin-bottom: var(--spacing-xs);
+  color: var(--color-text-light);
+}
+
+.content-preview {
+  padding: var(--spacing-sm);
+  background: white;
+  border: 1px solid var(--color-border);
+  border-radius: 4px;
+  margin-top: var(--spacing-xs);
+}
+
+.moderation-actions {
+  margin-top: var(--spacing-lg);
+}
+
+.moderation-actions h3 {
+  margin-bottom: var(--spacing-sm);
+}
+
+.error-text {
+  color: #991B1B;
+}
+
+.empty-state {
+  text-align: center;
+  padding: var(--spacing-lg);
+  color: var(--color-text-light);
+}
+
+.empty-state .text-muted {
+  font-size: 0.875rem;
+}
diff --git a/templates/admin/dashboard.html b/templates/admin/dashboard.html
index 02b52f8..e3f2abe 100644
--- a/templates/admin/dashboard.html
+++ b/templates/admin/dashboard.html
@@ -10,6 +10,14 @@
     
       + New Note
     
+    {% if config.WEBMENTION_ENABLED %}
+    
+      Webmentions
+      {% if webmention_pending_count > 0 %}
+      {{ webmention_pending_count }}
+      {% endif %}
+    
+    {% endif %}
   
 
   {% if notes %}
@@ -59,6 +67,20 @@
       {% endfor %}
     
   
+
+  {# Pagination (v1.6.0) #}
+  {% if total_pages > 1 %}
+  
+  {% endif %}
+
   {% else %}
   

No notes yet. Create your first note!

diff --git a/templates/admin/webmention_detail.html b/templates/admin/webmention_detail.html new file mode 100644 index 0000000..752fb09 --- /dev/null +++ b/templates/admin/webmention_detail.html @@ -0,0 +1,108 @@ +{% extends "admin/base.html" %} + +{% block title %}Webmention Detail - StarPunk Admin{% endblock %} + +{% block admin_content %} +
+

Webmention Detail

+ + + +
+ + +
+ Target: + {% if webmention.target_note_id %} + {{ webmention.target_url }} + {% else %} + {{ webmention.target_url }} (Homepage) + {% endif %} +
+ +
+ Type: + {{ webmention.mention_type }} +
+ +
+ Author: + {{ webmention.author_name or 'Anonymous' }} + {% if webmention.author_url %} + ({{ webmention.author_url }}) + {% endif %} +
+ + {% if webmention.author_photo %} +
+ Author Photo: + {{ webmention.author_name or 'Author' }} +
+ {% endif %} + + {% if webmention.content_snippet %} +
+ Content: +
{{ webmention.content_snippet|safe }}
+
+ {% endif %} + +
+ Validation Status: + {{ webmention.validation_status }} + {% if webmention.validation_error %} +
{{ webmention.validation_error }} + {% endif %} +
+ +
+ Moderation Status: + {{ webmention.moderation_status }} +
+ +
+ Received: + {{ webmention.received_at.strftime('%B %d, %Y at %I:%M %p') }} +
+ + {% if webmention.validated_at %} +
+ Validated: + {{ webmention.validated_at.strftime('%B %d, %Y at %I:%M %p') }} +
+ {% endif %} +
+ + {# Moderation Actions #} +
+

Actions

+
+ + +
+ +
+ + +
+ +
+ + +
+
+
+{% endblock %} diff --git a/templates/admin/webmentions.html b/templates/admin/webmentions.html new file mode 100644 index 0000000..0dc101b --- /dev/null +++ b/templates/admin/webmentions.html @@ -0,0 +1,125 @@ +{% extends "admin/base.html" %} + +{% block title %}Webmentions - StarPunk Admin{% endblock %} + +{% block admin_content %} +
+

Webmentions

+ + + + {# Filter tabs #} + + + {% if webmentions %} +
+
+ + + +
+ + + + + + + + + + + + + + + + {% for wm in webmentions %} + + + + + + + + + + + {% endfor %} + +
SourceTargetTypeAuthorStatusReceivedActions
{{ wm.source_url|truncate(40) }} + {% if wm.target_note_id %} + {{ wm.target_slug }} + {% else %} + Homepage + {% endif %} + {{ wm.mention_type }}{{ wm.author_name or 'Anonymous' }} + + {{ wm.moderation_status }} + + {{ wm.received_at.strftime('%b %d, %Y %H:%M') }} + + View + +
+
+ + {# Pagination #} + {% if total_pages > 1 %} + + {% endif %} + + {% else %} + {# Empty states #} + {% if status_filter %} +
+

No webmentions match the current filters.

+ Clear Filters +
+ {% else %} +
+

No webmentions received yet.

+

They will appear here when other sites mention your content.

+
+ {% endif %} + {% endif %} +
+ + +{% endblock %} diff --git a/templates/base.html b/templates/base.html index 23f81a2..b73cb41 100644 --- a/templates/base.html +++ b/templates/base.html @@ -8,6 +8,11 @@ + {# Webmention endpoint (v1.6.0) #} + {% if config.WEBMENTION_ENABLED %} + + {% endif %} + {# rel-me links from discovered author profile (v1.2.0 Phase 2) #} {% if author and author.rel_me_links %} {% for profile_url in author.rel_me_links %} @@ -30,7 +35,9 @@ Home RSS {% if g.me %} - Admin + Dashboard + {% else %} + Login {% endif %}
{{ note.title }} {% endif %} + {# Reply context (v1.6.0 Phase 4) - displayed if this is a reply post #} + {% if note.in_reply_to %} +
+ In reply to: +
+ {% if reply_context and reply_context.fetch_status == 'fetched' %} + {% if reply_context.content_snippet %} +

{{ reply_context.content_snippet }}

+ {% endif %} + + + {% if reply_context.author_name %}{{ reply_context.author_name }}{% endif %} + {% if reply_context.site_name %} on {{ reply_context.site_name }}{% endif %} + {% if not reply_context.author_name and not reply_context.site_name %}{{ note.in_reply_to }}{% endif %} + + + {% else %} + + {{ note.in_reply_to }} + + {% endif %} +
+
+ {% endif %} + {# u-photo placement: Per draft spec, u-photo must be direct child of h-entry, #} {# NOT inside e-content. Media is rendered ABOVE e-content to meet this requirement. #} {{ display_media(note.media) }} @@ -68,5 +93,118 @@ + + {# Webmentions section (v1.6.0 Phase 5) - only shown if approved webmentions exist #} + {% if webmentions %} +
+

Responses

+ + {% if replies %} +
+

{{ replies|length }} {{ 'Reply' if replies|length == 1 else 'Replies' }}

+ {% for reply in replies %} + + {% endfor %} +
+ {% endif %} + + {% if likes %} +
+

{{ likes|length }} {{ 'Like' if likes|length == 1 else 'Likes' }}

+
+ {% for wm in likes[:8] %} + + {% if wm.author_photo %} + {{ wm.author_name or '' }} + {% else %} + + {{ (wm.author_name or '?')[0]|upper }} + + {% endif %} + + {% endfor %} + {% if likes|length > 8 %} + +{{ likes|length - 8 }} others + {% endif %} +
+
+ {% endif %} + + {% if reposts %} +
+

{{ reposts|length }} {{ 'Repost' if reposts|length == 1 else 'Reposts' }}

+
+ {% for wm in reposts[:8] %} + + {% if wm.author_photo %} + {{ wm.author_name or '' }} + {% else %} + + {{ (wm.author_name or '?')[0]|upper }} + + {% endif %} + + {% endfor %} + {% if reposts|length > 8 %} + +{{ reposts|length - 8 }} others + {% endif %} +
+
+ {% endif %} + + {% if bookmarks %} +
+

{{ bookmarks|length }} {{ 'Bookmark' if bookmarks|length == 1 else 'Bookmarks' }}

+
+ {% for wm in bookmarks[:8] %} + + {% if wm.author_photo %} + {{ wm.author_name or '' }} + {% else %} + + {{ (wm.author_name or '?')[0]|upper }} + + {% endif %} + + {% endfor %} + {% if bookmarks|length > 8 %} + +{{ bookmarks|length - 8 }} others + {% endif %} +
+
+ {% endif %} + + {% if mentions %} +
+

{{ mentions|length }} {{ 'Mention' if mentions|length == 1 else 'Mentions' }}

+ {% for mention in mentions %} +
+ {{ mention.author_name or mention.source_url }} + {% if mention.content_snippet %} +

{{ mention.content_snippet|truncate(200) }}

+ {% endif %} +
+ {% endfor %} +
+ {% endif %} +
+ {% endif %} {% endblock %} From b84cf23e1a22c3552f999100c2157c920b4a8232 Mon Sep 17 00:00:00 2001 From: Phil Date: Sat, 31 Oct 2026 11:38:27 -0600 Subject: [PATCH 2/2] feat!: OIDC admin login and built-in IndieAuth server (v2.0.0) Admin login now uses OpenID Connect (PKCE, nonce, ID token verified against the provider JWKS) and only OIDC_ADMIN_SUB may log in. Micropub tokens are issued and verified by StarPunk itself, with a consent screen behind the OIDC session and a Connected Apps page to revoke them, so an external IndieAuth server (Gondulf) is no longer needed. Existing notes, media, tags, webmentions, author profile and sessions are unchanged. Migration 011 adds new tables only. BREAKING CHANGE: production requires OIDC_ISSUER, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET and OIDC_ADMIN_SUB. The ADMIN_ME page must point Micropub apps at StarPunk's IndieAuth endpoints. See ADR-064. Co-Authored-By: Claude Opus 5.5 --- .env.example | 23 +- CHANGELOG.md | 30 + README.md | 10 +- ...dmin-login-and-builtin-indieauth-server.md | 70 ++ .../v2.0.0/2026-10-31-oidc-migration.md | 56 ++ .../011_oidc_login_and_indieauth_server.sql | 49 ++ requirements.txt | 1 + starpunk/__init__.py | 4 +- starpunk/auth.py | 628 +++++++---------- starpunk/auth_external.py | 614 ----------------- starpunk/config.py | 40 +- starpunk/indieauth.py | 348 ++++++++++ starpunk/micropub.py | 2 +- starpunk/routes/__init__.py | 3 +- starpunk/routes/admin.py | 22 + starpunk/routes/auth.py | 161 ++--- starpunk/routes/indieauth.py | 228 +++++++ starpunk/routes/micropub.py | 7 +- templates/admin/authorize.html | 43 ++ templates/admin/base.html | 1 + templates/admin/login.html | 28 +- templates/admin/tokens.html | 44 ++ templates/base.html | 4 + tests/test_auth.py | 522 -------------- tests/test_auth_external.py | 637 ------------------ tests/test_auth_oidc.py | 243 +++++++ tests/test_indieauth.py | 329 +++++++++ tests/test_micropub.py | 24 +- tests/test_templates.py | 7 +- 29 files changed, 1824 insertions(+), 2354 deletions(-) create mode 100644 docs/decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md create mode 100644 docs/design/v2.0.0/2026-10-31-oidc-migration.md create mode 100644 migrations/011_oidc_login_and_indieauth_server.sql delete mode 100644 starpunk/auth_external.py create mode 100644 starpunk/indieauth.py create mode 100644 starpunk/routes/indieauth.py create mode 100644 templates/admin/authorize.html create mode 100644 templates/admin/tokens.html delete mode 100644 tests/test_auth_external.py create mode 100644 tests/test_auth_oidc.py create mode 100644 tests/test_indieauth.py diff --git a/.env.example b/.env.example index f97cdbf..0705511 100644 --- a/.env.example +++ b/.env.example @@ -22,11 +22,24 @@ SITE_DESCRIPTION=My personal IndieWeb site # AUTHENTICATION # ============================================================================= -# Your IndieWeb identity URL (REQUIRED) -# This is YOUR personal website URL that you authenticate with -# Example: https://yourname.com or https://github.com/yourname +# Your identity URL (REQUIRED) +# Your personal website. Used as the author h-card source and as the "me" +# value in Micropub tokens. It should link to this site's IndieAuth metadata +# (see docs/decisions/ADR-064) so Micropub apps can find StarPunk. ADMIN_ME=https://your-website.com +# Admin login via OpenID Connect (REQUIRED in production) +# Register StarPunk as a confidential client with your provider (e.g. Pocket ID) +# using the callback URL: /auth/callback +OIDC_ISSUER=https://id.example.com +OIDC_CLIENT_ID= +OIDC_CLIENT_SECRET= +# The provider's subject ("sub") of the one account allowed to log in. +# Pocket ID: the user's ID shown in the admin user list. +OIDC_ADMIN_SUB= +# Name shown on the login button (default: "single sign-on") +OIDC_PROVIDER_NAME=Pocket ID + # Session secret key (REQUIRED - GENERATE A RANDOM VALUE) # Generate with: python3 -c "import secrets; print(secrets.token_hex(32))" SESSION_SECRET=REPLACE_WITH_RANDOM_SECRET @@ -34,8 +47,8 @@ SESSION_SECRET=REPLACE_WITH_RANDOM_SECRET # Session lifetime in days (default: 30) SESSION_LIFETIME=30 -# IndieLogin service URL (usually don't change this) -INDIELOGIN_URL=https://indielogin.com +# Lifetime of Micropub access tokens StarPunk issues, in days (default: 90) +INDIEAUTH_TOKEN_LIFETIME_DAYS=90 # ============================================================================= # DATA STORAGE diff --git a/CHANGELOG.md b/CHANGELOG.md index 3983e76..edc07e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [2.0.0] - 2026-10-31 + +### Changed (breaking) + +- **Admin login uses OpenID Connect** instead of IndieAuth (ADR-064) + - Works with Pocket ID or any OIDC provider; authorization code flow with PKCE and nonce + - Only the account whose subject matches `OIDC_ADMIN_SUB` can log in + - New required settings: `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_ADMIN_SUB` + - `INDIELOGIN_URL` and `TOKEN_ENDPOINT` are ignored +- **Micropub tokens are issued by StarPunk**, not an external IndieAuth server + - Your `ADMIN_ME` page must point Micropub apps at StarPunk's + `/.well-known/oauth-authorization-server` (or its `/auth/authorize` and `/auth/token`) + - Apps authorized through an external server must be authorized again + +### Added + +- Built-in IndieAuth server: metadata, consent screen, token, revocation endpoints +- **Connected Apps** admin page (`/admin/tokens`) to review and revoke Micropub tokens +- Discovery links (`micropub`, `indieauth-metadata`, `authorization_endpoint`, `token_endpoint`) on every page +- Migration 011: `oidc_login_state`, `indieauth_codes`, `indieauth_tokens` + +### Removed + +- IndieAuth endpoint discovery and external token verification (`starpunk/auth_external.py`) + +### Notes + +- Existing notes, media, tags, webmentions, author profile and admin sessions are preserved +- v1.6.0 source (webmentions) recovered from the production image; it had not been committed + ## [1.5.0] - 2025-12-17 ### Added diff --git a/README.md b/README.md index be9a301..412eff5 100644 --- a/README.md +++ b/README.md @@ -27,7 +27,8 @@ StarPunk is designed for a single user who wants to: ## Features - **File-based storage**: Notes are markdown files, owned by you -- **IndieAuth authentication**: Use your own website as identity +- **OIDC admin login**: Sign in through your identity provider (e.g. Pocket ID) +- **Built-in IndieAuth server**: Approve Micropub apps without a separate auth service - **Micropub support**: Full W3C Micropub specification compliance - **Media attachments**: Upload and display images with your notes - **Microformats2**: Full h-entry, h-card, and h-feed markup for IndieWeb compatibility @@ -62,7 +63,7 @@ uv pip install -r requirements.txt # Configure cp .env.example .env -# Edit .env and set ADMIN_ME and SESSION_SECRET +# Edit .env and set ADMIN_ME, SESSION_SECRET and the OIDC_* values # Initialize database mkdir -p data/notes @@ -82,6 +83,8 @@ All configuration is in the `.env` file. Required settings: - `ADMIN_ME` - Your IndieWeb identity URL (e.g., https://yoursite.com) - `SESSION_SECRET` - Random secret key (generate with `python3 -c "import secrets; print(secrets.token_hex(32))"`) - `SITE_URL` - Public URL of your site +- `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` - OIDC client for admin login (callback: `/auth/callback`) +- `OIDC_ADMIN_SUB` - Subject ID of the one account allowed to log in See `.env.example` for all options. @@ -110,7 +113,7 @@ starpunk/ **Via Micropub Client**: 1. Configure client with your site URL -2. Authenticate via IndieAuth +2. Sign in with your OIDC provider 3. Publish from any Micropub-compatible app ### Backing Up Your Data @@ -192,7 +195,6 @@ Built with: - [python-markdown](https://python-markdown.github.io/) - Markdown processing - [feedgen](https://feedgen.kiesow.be/) - RSS generation - [httpx](https://www.python-httpx.org/) - HTTP client -- [IndieLogin](https://indielogin.com/) - Authentication service ## Contributing diff --git a/docs/decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md b/docs/decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md new file mode 100644 index 0000000..0195631 --- /dev/null +++ b/docs/decisions/ADR-064-oidc-admin-login-and-builtin-indieauth-server.md @@ -0,0 +1,70 @@ +# ADR-064: OIDC Admin Login and Built-in IndieAuth Server + +## Status + +Accepted (v2.0.0, 2026-10-31) + +Supersedes the login parts of ADR-021, ADR-025, ADR-027 and ADR-043, and the +external token verification of ADR-030 and ADR-036. + +## Context + +Up to v1.6.0 StarPunk was an IndieAuth *client*. Admin login discovered an +authorization endpoint from `ADMIN_ME` and used the authentication-only +flow; Micropub verified bearer tokens by calling the token endpoint +discovered from `ADMIN_ME`. In practice both pointed at Gondulf, a separate +self-hosted IndieAuth server. + +The operator now runs Pocket ID (OIDC, passkeys) for every other +self-hosted service and wants StarPunk to use it too. Pocket ID cannot act +as an IndieAuth server: IndieAuth clients identify themselves by URL +(`client_id` = their homepage) and are not pre-registered, while OIDC +clients must be registered with the provider. + +Micropub apps such as Quill and Indigenous only speak IndieAuth, so moving +login to OIDC alone would end Micropub posting. + +## Decision + +1. **Admin login uses OIDC** (authorization code flow, PKCE S256, nonce). + StarPunk is a confidential client. The ID token's signature (provider + JWKS), `iss`, `aud`, `exp` and `nonce` are verified, and only the + configured `OIDC_ADMIN_SUB` may log in. A successful login creates the + same local session as before, for `ADMIN_ME`. +2. **StarPunk becomes its own IndieAuth server** for Micropub clients: + `/.well-known/oauth-authorization-server`, `/auth/authorize` (consent + screen, admin session required, so approval is protected by OIDC), + `/auth/token` and `/auth/revoke`. Only `response_type=code` with PKCE + S256 is supported. Tokens are stored as SHA-256 hashes and verified + locally by `/micropub` and `/media`. +3. **`ADMIN_ME` stays** as the site owner's identity URL: it is the author + h-card source and the `me` in issued tokens. That page must advertise + StarPunk's IndieAuth metadata (or `authorization_endpoint` / + `token_endpoint` links) so Micropub apps discover StarPunk. +4. **New tables** (`oidc_login_state`, `indieauth_codes`, + `indieauth_tokens`, migration 011). The legacy `auth_state`, `tokens` + and `authorization_codes` tables are not reused because migration 004 + drops the last two after `INITIAL_SCHEMA_SQL` creates them. +5. Client `redirect_uri` must share the `client_id` origin, or be published + by the client (JSON `redirect_uris` or `rel="redirect_uri"`). The fetch + reuses the webmention SSRF guard. + +## Consequences + +- Gondulf is no longer needed and can be retired. +- Existing admin sessions stay valid (sessions are keyed by `ADMIN_ME`, which + does not change). Notes, media, tags and webmentions are untouched. +- Micropub apps must be re-authorized once, since their old tokens were + issued by Gondulf. Tokens are visible and revocable at `/admin/tokens`. +- Production requires `OIDC_ISSUER`, `OIDC_CLIENT_ID`, + `OIDC_CLIENT_SECRET`, `OIDC_ADMIN_SUB`. `INDIELOGIN_URL` and + `TOKEN_ENDPOINT` are ignored. +- New dependency: `PyJWT[crypto]`. +- Major version bump (2.0.0): configuration and endpoint discovery change + incompatibly. + +## Alternatives Considered + +- **Keep Gondulf for Micropub only**: two auth systems to run and patch. +- **Drop Micropub**: simplest, but loses posting from apps. +- **Manually created API tokens**: Quill and most apps require IndieAuth. diff --git a/docs/design/v2.0.0/2026-10-31-oidc-migration.md b/docs/design/v2.0.0/2026-10-31-oidc-migration.md new file mode 100644 index 0000000..63eae5d --- /dev/null +++ b/docs/design/v2.0.0/2026-10-31-oidc-migration.md @@ -0,0 +1,56 @@ +# v2.0.0 Implementation Report: OIDC Login and Built-in IndieAuth Server + +Date: 2026-10-31 +Decision: ADR-064 + +## Summary + +Admin login moved from IndieAuth (via Gondulf) to OIDC (Pocket ID). +StarPunk now issues and verifies its own Micropub tokens, so Gondulf is no +longer needed. No data migration is required: notes, media, tags, +webmentions, the author profile and admin sessions are unchanged. + +## Source recovery + +Production ran `starpunk:v1.6.0-rc.2`, but the v1.6.0 code was never +committed (`main` was at v1.5.0). The application code was copied out of +the running container's `/app` and committed as `v1.6.0-rc.2` before any +v2.0.0 changes. The v1.6.0 tests and docs were not in the image, so ADR-063 +(webmentions) and the v1.6.0 design folder are still missing. + +## Changes + +| Area | Change | +|---|---| +| `starpunk/auth.py` | OIDC client: discovery (cached), PKCE S256, nonce, ID token check against the provider JWKS, `OIDC_ADMIN_SUB` check. Session functions unchanged. | +| `starpunk/indieauth.py` | New: authorization codes, access tokens (hashed), client `redirect_uri` checks, revocation. | +| `starpunk/routes/auth.py` | Login is a single "Sign in with ..." button; callback handles provider errors and `next`. | +| `starpunk/routes/indieauth.py` | New: metadata, consent, approve, token, legacy token verify, revoke. | +| `starpunk/routes/micropub.py` | Verifies tokens locally. | +| `starpunk/routes/admin.py`, `templates/admin/tokens.html` | Connected Apps page with revoke. | +| `templates/base.html` | Discovery links built from `SITE_URL` (not the request host, which is `http://` behind the proxy). | +| `migrations/011_*.sql` | `oidc_login_state`, `indieauth_codes`, `indieauth_tokens`. | +| `starpunk/auth_external.py` | Removed. | + +## Testing + +- New: `tests/test_auth_oidc.py` (real RS256-signed ID tokens: bad audience, issuer, + key, expiry, nonce, subject; state reuse; routes) and `tests/test_indieauth.py` + (validation, PKCE, single-use codes, consent, full Micropub post with an issued + token, revocation, admin page). +- `tests/test_auth.py` keeps the session tests; IndieLogin flow tests removed. +- Full suite: 905 passed. Remaining failures predate this work and are in the + recovered v1.6.0 baseline: seven in `test_media_upload.py` (image + validation, HEIC, MPO) and one or two timing-sensitive tests in + `test_migration_race_condition.py` that fail on a different test each run. +- Migration rehearsed on a copy of the production database: 011 applied, + row counts for notes, media, tags, sessions and author profile unchanged. + +## Deployment notes + +- Pocket ID client "StarPunk": confidential, PKCE on, callback + `https://starpunk.thesatelliteoflove.com/auth/callback`. +- The container needs `id.thesatelliteoflove.com` mapped to Caddy in + `extra_hosts` (hairpin NAT does not work from the `lava` network). +- `thesatelliteoflove.com` (static file in `/opt/stacks/caddy/site/tsol/`) + must advertise StarPunk's IndieAuth endpoints instead of Gondulf's. diff --git a/migrations/011_oidc_login_and_indieauth_server.sql b/migrations/011_oidc_login_and_indieauth_server.sql new file mode 100644 index 0000000..4e32b56 --- /dev/null +++ b/migrations/011_oidc_login_and_indieauth_server.sql @@ -0,0 +1,49 @@ +-- Migration 011: OIDC admin login + built-in IndieAuth server +-- Version: 2.0.0 +-- Per ADR-064: Replace IndieAuth login with OIDC, issue Micropub tokens locally +-- +-- New tables only. The legacy auth_state, tokens and authorization_codes +-- tables are left alone: INITIAL_SCHEMA_SQL recreates tokens and +-- authorization_codes on every start while migration 004 drops them, so +-- nothing new can depend on them. + +-- Pending OIDC logins (state, nonce and PKCE verifier for one round trip) +CREATE TABLE IF NOT EXISTS oidc_login_state ( + state TEXT PRIMARY KEY, + nonce TEXT NOT NULL, + code_verifier TEXT NOT NULL, + next_url TEXT, + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + expires_at TIMESTAMP NOT NULL +); + +CREATE INDEX IF NOT EXISTS idx_oidc_login_state_expires ON oidc_login_state(expires_at); + +-- Authorization codes issued to IndieAuth (Micropub) clients +CREATE TABLE IF NOT EXISTS indieauth_codes ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + code_hash TEXT UNIQUE NOT NULL, + client_id TEXT NOT NULL, + redirect_uri TEXT NOT NULL, + scope TEXT NOT NULL DEFAULT '', + code_challenge TEXT NOT NULL, + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + expires_at TIMESTAMP NOT NULL, + used_at TIMESTAMP +); + +CREATE INDEX IF NOT EXISTS idx_indieauth_codes_expires ON indieauth_codes(expires_at); + +-- Access tokens issued to IndieAuth (Micropub) clients +CREATE TABLE IF NOT EXISTS indieauth_tokens ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + token_hash TEXT UNIQUE NOT NULL, + client_id TEXT NOT NULL, + scope TEXT NOT NULL, + created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP, + expires_at TIMESTAMP NOT NULL, + last_used_at TIMESTAMP, + revoked_at TIMESTAMP +); + +CREATE INDEX IF NOT EXISTS idx_indieauth_tokens_expires ON indieauth_tokens(expires_at); diff --git a/requirements.txt b/requirements.txt index 4aeed68..a97e85d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -39,3 +39,4 @@ pillow-heif==0.18.* # HTML Sanitization (v1.6.0 - Webmention content) nh3==0.2.* +PyJWT[crypto]==2.10.* diff --git a/starpunk/__init__.py b/starpunk/__init__.py index a0cadeb..a15dbda 100644 --- a/starpunk/__init__.py +++ b/starpunk/__init__.py @@ -436,5 +436,5 @@ def create_app(config=None): # Package version (Semantic Versioning 2.0.0) # See docs/standards/versioning-strategy.md for details -__version__ = "1.6.0" -__version_info__ = (1, 6, 0) +__version__ = "2.0.0" +__version_info__ = (2, 0, 0) diff --git a/starpunk/auth.py b/starpunk/auth.py index 37caf28..8093311 100644 --- a/starpunk/auth.py +++ b/starpunk/auth.py @@ -1,20 +1,21 @@ """ Authentication module for StarPunk -Implements IndieLogin authentication for admin access using indielogin.com -as a delegated authentication provider. No passwords are stored locally. +Admin login uses OpenID Connect (authorization code flow with PKCE) against +a configured provider such as Pocket ID. Exactly one OIDC subject +(OIDC_ADMIN_SUB) may log in; a successful login creates a local session +for the site owner's identity URL (ADMIN_ME). No passwords are stored. Security features: -- CSRF protection via state tokens -- Secure session tokens (cryptographically random) -- Token hashing in database (SHA-256) +- CSRF protection via single-use state tokens +- PKCE (S256) and nonce binding of the ID token to the login attempt +- ID token signature, issuer, audience and expiry checks +- Session tokens hashed in the database (SHA-256) - HttpOnly, Secure, SameSite cookies -- Single-admin authorization -- Automatic session cleanup Functions: - initiate_login: Start IndieLogin authentication flow - handle_callback: Process IndieLogin callback + initiate_login: Start the OIDC login flow + handle_callback: Finish the OIDC login flow and create a session create_session: Create authenticated session verify_session: Check if session is valid destroy_session: Logout and cleanup @@ -24,153 +25,50 @@ Exceptions: AuthError: Base authentication exception InvalidStateError: CSRF state validation failed UnauthorizedError: User not authorized as admin - IndieLoginError: External service error + OIDCError: Identity provider error """ +import base64 import hashlib -import logging import secrets +import time from datetime import datetime, timedelta from functools import wraps -from typing import Any, Dict, Optional +from typing import Any, Dict, Optional, Tuple from urllib.parse import urlencode import httpx +import jwt from flask import current_app, g, redirect, request, session, url_for -from starpunk.auth_external import discover_endpoints, DiscoveryError, normalize_url from starpunk.database import get_db -from starpunk.utils import is_valid_url + +# Cached provider metadata: {issuer: (fetched_at, metadata)} +_METADATA_CACHE: Dict[str, Tuple[float, dict]] = {} +_METADATA_TTL = 3600 +# One JWKS client per jwks_uri; PyJWKClient caches the keys itself +_JWKS_CLIENTS: Dict[str, jwt.PyJWKClient] = {} + +LOGIN_STATE_MINUTES = 10 # Custom exceptions class AuthError(Exception): """Base exception for authentication errors""" - pass - class InvalidStateError(AuthError): """CSRF state validation failed""" - pass - class UnauthorizedError(AuthError): """User not authorized as admin""" - pass + +class OIDCError(AuthError): + """Identity provider error""" -class IndieLoginError(AuthError): - """IndieLogin service error""" - - pass - - -# Logging helper functions -def _redact_token(value: str, show_chars: int = 6) -> str: - """ - Redact sensitive token for logging - - Shows first N and last 4 characters with asterisks in between. - - Args: - value: Token to redact - show_chars: Number of characters to show at start (default: 6) - - Returns: - Redacted token string like "abc123...********...xyz9" - """ - if not value or len(value) <= (show_chars + 4): - return "***REDACTED***" - - return f"{value[:show_chars]}...{'*' * 8}...{value[-4:]}" - - -def _log_http_request(method: str, url: str, data: dict, headers: dict = None) -> None: - """ - Log HTTP request details at DEBUG level - - Automatically redacts sensitive parameters (code, state, authorization) - - Args: - method: HTTP method (GET, POST, etc.) - url: Request URL - data: Request data/parameters - headers: Optional request headers - """ - if not current_app.logger.isEnabledFor(logging.DEBUG): - return - - # Redact sensitive data - safe_data = data.copy() - if "code" in safe_data: - safe_data["code"] = _redact_token(safe_data["code"]) - if "state" in safe_data: - safe_data["state"] = _redact_token(safe_data["state"], 8) - if "code_verifier" in safe_data: - safe_data["code_verifier"] = _redact_token(safe_data["code_verifier"]) - - current_app.logger.debug( - f"IndieAuth HTTP Request:\n" - f" Method: {method}\n" - f" URL: {url}\n" - f" Data: {safe_data}" - ) - - if headers: - safe_headers = { - k: v - for k, v in headers.items() - if k.lower() not in ["authorization", "cookie"] - } - current_app.logger.debug(f" Headers: {safe_headers}") - - -def _log_http_response(status_code: int, headers: dict, body: str) -> None: - """ - Log HTTP response details at DEBUG level - - Automatically redacts sensitive response data - - Args: - status_code: HTTP status code - headers: Response headers - body: Response body (JSON string or text) - """ - if not current_app.logger.isEnabledFor(logging.DEBUG): - return - - # Parse and redact JSON body if present - safe_body = body - try: - import json - - data = json.loads(body) - if "access_token" in data: - data["access_token"] = _redact_token(data["access_token"]) - if "code" in data: - data["code"] = _redact_token(data["code"]) - safe_body = json.dumps(data, indent=2) - except (json.JSONDecodeError, TypeError): - # Not JSON or parsing failed, log as-is (likely error message) - pass - - # Redact sensitive headers - safe_headers = { - k: v for k, v in headers.items() if k.lower() not in ["set-cookie", "authorization"] - } - - current_app.logger.debug( - f"IndieAuth HTTP Response:\n" - f" Status: {status_code}\n" - f" Headers: {safe_headers}\n" - f" Body: {safe_body}" - ) - - -# Helper functions def _hash_token(token: str) -> str: """ Hash token using SHA-256 @@ -185,323 +83,264 @@ def _hash_token(token: str) -> str: def _generate_state_token() -> str: - """ - Generate CSRF state token - - Returns: - URL-safe random token - """ + """Generate a URL-safe random token""" return secrets.token_urlsafe(32) -def _verify_state_token(state: str) -> bool: +def _pkce_challenge(verifier: str) -> str: + """S256 PKCE challenge for a verifier (RFC 7636)""" + digest = hashlib.sha256(verifier.encode("ascii")).digest() + return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii") + + +def _redirect_uri() -> str: + """OIDC redirect URI registered with the provider""" + return current_app.config["SITE_URL"].rstrip("/") + "/auth/callback" + + +def _safe_next_url(next_url: Optional[str]) -> Optional[str]: + """Only allow redirects back to this site after login""" + if not next_url: + return None + site = current_app.config["SITE_URL"].rstrip("/") + if next_url.startswith(site + "/"): + return next_url + if next_url.startswith("/") and not next_url.startswith("//"): + return next_url + return None + + +def _cleanup_expired_sessions() -> None: + """Remove expired sessions and pending login state""" + db = get_db(current_app) + db.execute("DELETE FROM sessions WHERE expires_at <= datetime('now')") + db.execute("DELETE FROM oidc_login_state WHERE expires_at <= datetime('now')") + db.commit() + + +def get_oidc_metadata() -> dict: """ - Verify and consume CSRF state token. + Fetch (and cache) the provider's OpenID configuration + + Raises: + OIDCError: Discovery failed or the issuer does not match + """ + issuer = current_app.config.get("OIDC_ISSUER", "").rstrip("/") + if not issuer: + raise OIDCError("OIDC_ISSUER is not configured") + + cached = _METADATA_CACHE.get(issuer) + if cached and time.time() - cached[0] < _METADATA_TTL: + return cached[1] + + url = f"{issuer}/.well-known/openid-configuration" + try: + response = httpx.get(url, timeout=10.0) + response.raise_for_status() + metadata = response.json() + except (httpx.HTTPError, ValueError) as e: + raise OIDCError(f"OIDC discovery failed: {e}") + + if metadata.get("issuer", "").rstrip("/") != issuer: + raise OIDCError( + f"OIDC issuer mismatch: expected {issuer}, got {metadata.get('issuer')}" + ) + for key in ("authorization_endpoint", "token_endpoint", "jwks_uri"): + if not metadata.get(key): + raise OIDCError(f"OIDC metadata is missing {key}") + + _METADATA_CACHE[issuer] = (time.time(), metadata) + return metadata + + +def _get_signing_key(metadata: dict, id_token: str): + """Resolve the key that signed an ID token from the provider's JWKS""" + jwks_uri = metadata["jwks_uri"] + client = _JWKS_CLIENTS.get(jwks_uri) + if client is None: + client = jwt.PyJWKClient(jwks_uri, timeout=10) + _JWKS_CLIENTS[jwks_uri] = client + return client.get_signing_key_from_jwt(id_token).key + + +def _validate_id_token(metadata: dict, id_token: str, nonce: str) -> dict: + """ + Verify the ID token signature and standard claims (OIDC Core 3.1.3.7) + + Raises: + OIDCError: Token is invalid + """ + algorithms = metadata.get("id_token_signing_alg_values_supported") or ["RS256"] + algorithms = [alg for alg in algorithms if alg != "none"] + try: + key = _get_signing_key(metadata, id_token) + claims = jwt.decode( + id_token, + key, + algorithms=algorithms, + audience=current_app.config["OIDC_CLIENT_ID"], + issuer=metadata["issuer"], + options={"require": ["exp", "iat", "sub", "iss", "aud"]}, + leeway=60, + ) + except jwt.PyJWTError as e: + raise OIDCError(f"Invalid ID token: {e}") + + if not nonce or not secrets.compare_digest(str(claims.get("nonce", "")), nonce): + raise OIDCError("ID token nonce does not match login request") + + return claims + + +# Core authentication functions +def initiate_login(next_url: Optional[str] = None) -> str: + """ + Start the OIDC authorization code flow Args: - state: State token to verify + next_url: Where to send the admin after login (same site only) Returns: - True if valid, False if invalid or expired - """ - db = get_db(current_app) + Redirect URL to the provider's authorization endpoint - # Check if state exists and not expired - result = db.execute( + Raises: + OIDCError: Provider discovery failed + """ + metadata = get_oidc_metadata() + + state = _generate_state_token() + nonce = secrets.token_urlsafe(32) + code_verifier = secrets.token_urlsafe(64) + + db = get_db(current_app) + db.execute( """ - SELECT 1 FROM auth_state + INSERT INTO oidc_login_state (state, nonce, code_verifier, next_url, expires_at) + VALUES (?, ?, ?, ?, ?) + """, + ( + state, + nonce, + code_verifier, + _safe_next_url(next_url), + datetime.utcnow() + timedelta(minutes=LOGIN_STATE_MINUTES), + ), + ) + db.commit() + + params = { + "response_type": "code", + "client_id": current_app.config["OIDC_CLIENT_ID"], + "redirect_uri": _redirect_uri(), + "scope": "openid", + "state": state, + "nonce": nonce, + "code_challenge": _pkce_challenge(code_verifier), + "code_challenge_method": "S256", + } + + current_app.logger.info("Auth: OIDC login initiated") + return f"{metadata['authorization_endpoint']}?{urlencode(params)}" + + +def _consume_login_state(state: str) -> Optional[dict]: + """Fetch and delete a pending login (single use)""" + db = get_db(current_app) + row = db.execute( + """ + SELECT nonce, code_verifier, next_url FROM oidc_login_state WHERE state = ? AND expires_at > datetime('now') """, (state,), ).fetchone() - - if not result: - return False - - # Delete state (single-use) - db.execute("DELETE FROM auth_state WHERE state = ?", (state,)) + db.execute("DELETE FROM oidc_login_state WHERE state = ?", (state,)) db.commit() - - return True + return dict(row) if row else None -def _cleanup_expired_sessions() -> None: - """Remove expired sessions and state tokens""" - db = get_db(current_app) - - # Delete expired sessions - db.execute( - """ - DELETE FROM sessions - WHERE expires_at <= datetime('now') +def handle_callback( + code: str, state: str, iss: Optional[str] = None +) -> Tuple[str, Optional[str]]: """ - ) - - # Delete expired state tokens - db.execute( - """ - DELETE FROM auth_state - WHERE expires_at <= datetime('now') - """ - ) - - db.commit() - - -# Core authentication functions -def initiate_login(me_url: str) -> str: - """ - Initiate IndieAuth authentication flow with endpoint discovery. - - Per W3C IndieAuth spec, discovers authorization_endpoint from user's - profile URL rather than using a hardcoded service. + Finish the OIDC flow: exchange the code, verify the ID token, check + the subject is the configured admin, and create a session. Args: - me_url: User's IndieWeb identity URL - - Returns: - Redirect URL to discovered authorization endpoint - - Raises: - ValueError: Invalid me_url format - DiscoveryError: Failed to discover endpoints from profile - """ - # Validate URL format - if not is_valid_url(me_url): - raise ValueError(f"Invalid URL format: {me_url}") - - current_app.logger.debug(f"Auth: Validating me URL: {me_url}") - - # Discover authorization endpoint from user's profile URL - # Per IndieAuth spec: clients MUST discover endpoints, not hardcode them - try: - endpoints = discover_endpoints(me_url) - except DiscoveryError as e: - current_app.logger.error(f"Auth: Endpoint discovery failed for {me_url}: {e}") - raise - - auth_endpoint = endpoints.get('authorization_endpoint') - if not auth_endpoint: - raise DiscoveryError( - f"No authorization_endpoint found at {me_url}. " - "Ensure your profile has IndieAuth link elements or headers." - ) - - current_app.logger.info(f"Auth: Discovered authorization_endpoint: {auth_endpoint}") - - # Generate CSRF state token - state = _generate_state_token() - current_app.logger.debug(f"Auth: Generated state token: {_redact_token(state, 8)}") - - # Store state in database (5-minute expiry) - db = get_db(current_app) - expires_at = datetime.utcnow() + timedelta(minutes=5) - redirect_uri = f"{current_app.config['SITE_URL']}auth/callback" - - db.execute( - """ - INSERT INTO auth_state (state, expires_at, redirect_uri) - VALUES (?, ?, ?) - """, - (state, expires_at, redirect_uri), - ) - db.commit() - - # Build authorization URL - # Per W3C IndieAuth spec: use response_type=id for authentication-only flow - # (identity verification without access token). This allows code redemption - # at the authorization_endpoint rather than requiring token_endpoint. - params = { - "me": me_url, - "client_id": current_app.config["SITE_URL"], - "redirect_uri": redirect_uri, - "state": state, - "response_type": "id", - } - - current_app.logger.debug( - f"Auth: Building authorization URL with params:\n" - f" me: {me_url}\n" - f" client_id: {current_app.config['SITE_URL']}\n" - f" redirect_uri: {redirect_uri}\n" - f" state: {_redact_token(state, 8)}\n" - f" response_type: id (authentication-only flow)" - ) - - auth_url = f"{auth_endpoint}?{urlencode(params)}" - - current_app.logger.debug(f"Auth: Complete authorization URL: {auth_url}") - current_app.logger.info(f"Auth: Authentication initiated for {me_url}") - - return auth_url - - -def handle_callback(code: str, state: str, iss: Optional[str] = None) -> Optional[str]: - """ - Handle IndieAuth callback with endpoint discovery. - - Discovers authorization_endpoint from ADMIN_ME profile and exchanges - authorization code for identity verification. - - Per IndieAuth spec: Authentication-only flows POST to the authorization - endpoint (not token endpoint) and do not include grant_type. - - Args: - code: Authorization code from authorization server + code: Authorization code from the provider state: CSRF state token - iss: Issuer identifier (optional, for security validation) + iss: Issuer from the redirect (RFC 9207), checked when present Returns: - Session token if successful, None otherwise + (session_token, next_url) Raises: InvalidStateError: State token validation failed - UnauthorizedError: User not authorized as admin - IndieLoginError: Code exchange failed + UnauthorizedError: Subject is not the configured admin + OIDCError: Provider or token error """ - current_app.logger.debug(f"Auth: Verifying state token: {_redact_token(state, 8)}") - - # Verify state token (CSRF protection) - if not _verify_state_token(state): - current_app.logger.warning( - "Auth: Invalid state token received (possible CSRF or expired token)" - ) + pending = _consume_login_state(state) + if not pending: + current_app.logger.warning("Auth: Invalid or expired OIDC state") raise InvalidStateError("Invalid or expired state token") - current_app.logger.debug("Auth: State token valid") + metadata = get_oidc_metadata() - # Discover authorization endpoint from ADMIN_ME profile - admin_me = current_app.config.get("ADMIN_ME") - if not admin_me: - current_app.logger.error("Auth: ADMIN_ME not configured") - raise IndieLoginError("ADMIN_ME not configured") + if iss and iss.rstrip("/") != metadata["issuer"].rstrip("/"): + raise OIDCError(f"Unexpected issuer in callback: {iss}") - try: - endpoints = discover_endpoints(admin_me) - except DiscoveryError as e: - current_app.logger.error(f"Auth: Endpoint discovery failed: {e}") - raise IndieLoginError(f"Failed to discover endpoints: {e}") - - # Use authorization_endpoint for authentication-only flow (identity verification) - # Per IndieAuth spec: auth-only flows POST to authorization_endpoint, not token_endpoint - auth_endpoint = endpoints.get('authorization_endpoint') - if not auth_endpoint: - raise IndieLoginError( - f"No authorization_endpoint found at {admin_me}. " - "Ensure your profile has IndieAuth endpoints configured." - ) - - current_app.logger.debug(f"Auth: Using authorization_endpoint: {auth_endpoint}") - - # Verify issuer if provided (security check - optional) - if iss: - current_app.logger.debug(f"Auth: Issuer provided: {iss}") - - # Prepare code verification request - # Note: grant_type is NOT included for authentication-only flows per IndieAuth spec - token_exchange_data = { - "code": code, - "client_id": current_app.config["SITE_URL"], - "redirect_uri": f"{current_app.config['SITE_URL']}auth/callback", - } - - # Log the request - _log_http_request( - method="POST", - url=auth_endpoint, - data=token_exchange_data, - ) - - current_app.logger.debug( - "Auth: Sending code verification request to authorization endpoint:\n" - " Method: POST\n" - " URL: %s\n" - " Data: code=%s, client_id=%s, redirect_uri=%s", - auth_endpoint, - _redact_token(code), - token_exchange_data["client_id"], - token_exchange_data["redirect_uri"], - ) - - # Exchange code for identity at authorization endpoint (authentication-only flow) try: response = httpx.post( - auth_endpoint, - data=token_exchange_data, + metadata["token_endpoint"], + data={ + "grant_type": "authorization_code", + "code": code, + "redirect_uri": _redirect_uri(), + "code_verifier": pending["code_verifier"], + }, + auth=( + current_app.config["OIDC_CLIENT_ID"], + current_app.config["OIDC_CLIENT_SECRET"], + ), timeout=10.0, ) - - current_app.logger.debug( - "Auth: Received code verification response:\n" - " Status: %d\n" - " Headers: %s\n" - " Body: %s", - response.status_code, - {k: v for k, v in dict(response.headers).items() - if k.lower() not in ["set-cookie", "authorization"]}, - _redact_token(response.text) if response.text else "(empty)", - ) - - _log_http_response( - status_code=response.status_code, - headers=dict(response.headers), - body=response.text, - ) - - response.raise_for_status() except httpx.RequestError as e: - current_app.logger.error(f"Auth: Authorization endpoint request failed: {e}") - raise IndieLoginError(f"Failed to verify code: {e}") - except httpx.HTTPStatusError as e: + raise OIDCError(f"Token request failed: {e}") + + if response.status_code != 200: current_app.logger.error( - f"Auth: Authorization endpoint returned error: {e.response.status_code} - {e.response.text}" - ) - raise IndieLoginError( - f"Authorization endpoint returned error: {e.response.status_code}" + f"Auth: OIDC token endpoint returned {response.status_code}: {response.text[:200]}" ) + raise OIDCError(f"Token endpoint returned {response.status_code}") - # Parse response try: - data = response.json() - except Exception as e: - current_app.logger.error(f"Auth: Failed to parse authorization endpoint response: {e}") - raise IndieLoginError("Invalid JSON response from authorization endpoint") + id_token = response.json().get("id_token") + except ValueError: + raise OIDCError("Token endpoint returned invalid JSON") + if not id_token: + raise OIDCError("Token endpoint returned no id_token") - me = data.get("me") + claims = _validate_id_token(metadata, id_token, pending["nonce"]) + admin_sub = current_app.config.get("OIDC_ADMIN_SUB", "") + if not admin_sub or not secrets.compare_digest(claims["sub"], admin_sub): + current_app.logger.warning(f"Auth: Unauthorized OIDC subject {claims['sub']}") + raise UnauthorizedError("This account is not the site admin") + + me = current_app.config.get("ADMIN_ME") if not me: - current_app.logger.error("Auth: No identity returned from authorization endpoint") - raise IndieLoginError("No identity returned from authorization endpoint") + raise OIDCError("ADMIN_ME not configured") - current_app.logger.debug(f"Auth: Received identity: {me}") - - # Verify this is the admin user - current_app.logger.info(f"Auth: Verifying admin authorization for me={me}") - - # Normalize URLs for comparison (handles trailing slashes and case differences) - # This is correct per IndieAuth spec - the returned 'me' is the canonical form - if normalize_url(me) != normalize_url(admin_me): - current_app.logger.warning( - f"Auth: Unauthorized login attempt: {me} (expected {admin_me})" - ) - raise UnauthorizedError(f"User {me} is not authorized") - - current_app.logger.debug("Auth: Admin verification passed") - - # Create session session_token = create_session(me) - # Trigger author profile discovery (v1.2.0 Phase 2) - # Per Q14: Never block login, always allow fallback + # Refresh the author h-card; never block login on it try: from starpunk.author_discovery import get_author_profile - author_profile = get_author_profile(me, refresh=True) - current_app.logger.info(f"Author profile refreshed for {me}") + + get_author_profile(me, refresh=True) except Exception as e: current_app.logger.warning(f"Author discovery failed: {e}") - # Continue login anyway - never block per Q14 - return session_token + return session_token, pending["next_url"] def create_session(me: str) -> str: @@ -567,7 +406,6 @@ def verify_session(token: str) -> Optional[Dict[str, Any]]: current_app.logger.debug("Auth: No session token provided") return None - current_app.logger.debug(f"Auth: Verifying session token: {_redact_token(token)}") token_hash = _hash_token(token) diff --git a/starpunk/auth_external.py b/starpunk/auth_external.py deleted file mode 100644 index 66be222..0000000 --- a/starpunk/auth_external.py +++ /dev/null @@ -1,614 +0,0 @@ -""" -External IndieAuth Token Verification with Endpoint Discovery - -This module handles verification of bearer tokens issued by external -IndieAuth providers. Following the IndieAuth specification, endpoints -are discovered dynamically from the user's profile URL, not hardcoded. - -For StarPunk V1 (single-user CMS), we always discover endpoints from -ADMIN_ME since only the site owner can post content. - -Key Components: - EndpointCache: Simple in-memory cache for discovered endpoints and tokens - verify_external_token: Main entry point for token verification - discover_endpoints: Discovers IndieAuth endpoints from profile URL - -Configuration (via Flask app.config): - ADMIN_ME: Site owner's profile URL (required) - DEBUG: Allow HTTP endpoints in debug mode - -ADR: ADR-031 IndieAuth Endpoint Discovery Implementation -Date: 2025-11-24 -Version: v1.0.0-rc.5 -""" - -import hashlib -import logging -import re -import time -from typing import Dict, Optional, Any -from urllib.parse import urljoin, urlparse - -import httpx -from bs4 import BeautifulSoup -from flask import current_app - - -# Timeouts -DISCOVERY_TIMEOUT = 5.0 # Profile fetch (cached, so can be slower) -VERIFICATION_TIMEOUT = 3.0 # Token verification (every request) - -# Cache TTLs -ENDPOINT_CACHE_TTL = 3600 # 1 hour for endpoints -TOKEN_CACHE_TTL = 300 # 5 minutes for token verifications - - -class EndpointCache: - """ - Simple in-memory cache for endpoint discovery and token verification - - V1 single-user implementation: We only cache one user's endpoints - since StarPunk V1 is explicitly single-user (only ADMIN_ME can post). - - When V2 adds multi-user support, this will need refactoring to - cache endpoints per profile URL. - """ - - def __init__(self): - # Endpoint cache (single-user V1) - self.endpoints: Optional[Dict[str, str]] = None - self.endpoints_expire: float = 0 - - # Token verification cache (token_hash -> (info, expiry)) - self.token_cache: Dict[str, tuple[Dict[str, Any], float]] = {} - - def get_endpoints(self, ignore_expiry: bool = False) -> Optional[Dict[str, str]]: - """ - Get cached endpoints if still valid - - Args: - ignore_expiry: Return cached endpoints even if expired (grace period) - - Returns: - Cached endpoints dict or None if not cached or expired - """ - if self.endpoints is None: - return None - - if ignore_expiry or time.time() < self.endpoints_expire: - return self.endpoints - - return None - - def set_endpoints(self, endpoints: Dict[str, str], ttl: int = ENDPOINT_CACHE_TTL): - """Cache discovered endpoints""" - self.endpoints = endpoints - self.endpoints_expire = time.time() + ttl - - def get_token_info(self, token_hash: str) -> Optional[Dict[str, Any]]: - """Get cached token verification if still valid""" - if token_hash in self.token_cache: - info, expiry = self.token_cache[token_hash] - if time.time() < expiry: - return info - else: - # Expired, remove from cache - del self.token_cache[token_hash] - return None - - def set_token_info(self, token_hash: str, info: Dict[str, Any], ttl: int = TOKEN_CACHE_TTL): - """Cache token verification result""" - expiry = time.time() + ttl - self.token_cache[token_hash] = (info, expiry) - - -# Global cache instance (singleton for V1) -_cache = EndpointCache() - - -class DiscoveryError(Exception): - """Raised when endpoint discovery fails""" - pass - - -class TokenVerificationError(Exception): - """Raised when token verification fails""" - pass - - -def verify_external_token(token: str) -> Optional[Dict[str, Any]]: - """ - Verify bearer token with external IndieAuth provider - - This is the main entry point for token verification. For StarPunk V1 - (single-user), we always discover endpoints from ADMIN_ME since only - the site owner can post content. - - Process: - 1. Check token verification cache - 2. Discover endpoints from ADMIN_ME (with caching) - 3. Verify token with discovered endpoint - 4. Validate token belongs to ADMIN_ME - 5. Cache successful verification - - Args: - token: Bearer token to verify - - Returns: - Dict with token info (me, client_id, scope) if valid - None if token is invalid or verification fails - - Token info dict contains: - me: User's profile URL - client_id: Client application URL - scope: Space-separated list of scopes - """ - admin_me = current_app.config.get("ADMIN_ME") - - if not admin_me: - current_app.logger.error( - "ADMIN_ME not configured. Cannot verify token ownership." - ) - return None - - # Check token cache first - token_hash = _hash_token(token) - cached_info = _cache.get_token_info(token_hash) - if cached_info: - current_app.logger.debug("Token verification cache hit") - return cached_info - - # Discover endpoints from ADMIN_ME (V1 single-user assumption) - try: - endpoints = discover_endpoints(admin_me) - except DiscoveryError as e: - current_app.logger.error(f"Endpoint discovery failed: {e}") - return None - - token_endpoint = endpoints.get('token_endpoint') - if not token_endpoint: - current_app.logger.error("No token endpoint found in discovery") - return None - - # Verify token with discovered endpoint - try: - token_info = _verify_with_endpoint(token_endpoint, token) - except TokenVerificationError as e: - current_app.logger.warning(f"Token verification failed: {e}") - return None - - # Validate token belongs to admin (single-user security check) - token_me = token_info.get('me', '') - if normalize_url(token_me) != normalize_url(admin_me): - current_app.logger.warning( - f"Token 'me' mismatch: {token_me} != {admin_me}" - ) - return None - - # Cache successful verification - _cache.set_token_info(token_hash, token_info) - - current_app.logger.debug(f"Token verified successfully for {token_me}") - return token_info - - -def discover_endpoints(profile_url: str) -> Dict[str, str]: - """ - Discover IndieAuth endpoints from a profile URL - - Implements IndieAuth endpoint discovery per W3C spec: - https://www.w3.org/TR/indieauth/#discovery-by-clients - - Discovery priority: - 1. HTTP Link headers (highest priority) - 2. HTML link elements - - Args: - profile_url: User's profile URL (their IndieWeb identity) - - Returns: - Dict with discovered endpoints: - { - 'authorization_endpoint': 'https://...', - 'token_endpoint': 'https://...' - } - - Raises: - DiscoveryError: If discovery fails or no endpoints found - """ - # Check cache first - cached_endpoints = _cache.get_endpoints() - if cached_endpoints: - current_app.logger.debug("Endpoint discovery cache hit") - return cached_endpoints - - # Validate profile URL - _validate_profile_url(profile_url) - - try: - # Fetch profile with discovery - endpoints = _fetch_and_parse(profile_url) - - # Cache successful discovery - _cache.set_endpoints(endpoints) - - return endpoints - - except Exception as e: - # Check cache even if expired (grace period for network failures) - cached = _cache.get_endpoints(ignore_expiry=True) - if cached: - current_app.logger.warning( - f"Using expired cache due to discovery failure: {e}" - ) - return cached - - # No cache available, must fail - raise DiscoveryError(f"Endpoint discovery failed: {e}") - - -def _fetch_and_parse(profile_url: str) -> Dict[str, str]: - """ - Fetch profile URL and parse endpoints from headers and HTML - - Args: - profile_url: User's profile URL - - Returns: - Dict with discovered endpoints - - Raises: - DiscoveryError: If fetch fails or no endpoints found - """ - try: - response = httpx.get( - profile_url, - timeout=DISCOVERY_TIMEOUT, - follow_redirects=True, - headers={ - 'Accept': 'text/html,application/xhtml+xml', - 'User-Agent': f'StarPunk/{current_app.config.get("VERSION", "1.0")}' - } - ) - response.raise_for_status() - - except httpx.TimeoutException: - raise DiscoveryError(f"Timeout fetching profile: {profile_url}") - except httpx.HTTPStatusError as e: - raise DiscoveryError(f"HTTP {e.response.status_code} fetching profile") - except httpx.RequestError as e: - raise DiscoveryError(f"Network error fetching profile: {e}") - - endpoints = {} - - # 1. Parse HTTP Link headers (highest priority) - link_header = response.headers.get('Link', '') - if link_header: - link_endpoints = _parse_link_header(link_header, profile_url) - endpoints.update(link_endpoints) - - # 2. Parse HTML link elements - content_type = response.headers.get('Content-Type', '') - if 'text/html' in content_type or 'application/xhtml+xml' in content_type: - try: - html_endpoints = _parse_html_links(response.text, profile_url) - # Merge: Link headers take priority (so update HTML first) - html_endpoints.update(endpoints) - endpoints = html_endpoints - except Exception as e: - current_app.logger.warning(f"HTML parsing failed: {e}") - # Continue with Link header endpoints if HTML parsing fails - - # Validate we found at least one endpoint - # - authorization_endpoint: Required for authentication-only flows (admin login) - # - token_endpoint: Required for Micropub token verification - # Having at least one allows the appropriate flow to work - if 'token_endpoint' not in endpoints and 'authorization_endpoint' not in endpoints: - raise DiscoveryError( - f"No IndieAuth endpoints found at {profile_url}. " - "Ensure your profile has authorization_endpoint or token_endpoint configured." - ) - - # Validate endpoint URLs - for rel, url in endpoints.items(): - _validate_endpoint_url(url, rel) - - current_app.logger.info( - f"Discovered endpoints from {profile_url}: " - f"token={endpoints.get('token_endpoint')}, " - f"auth={endpoints.get('authorization_endpoint')}" - ) - - return endpoints - - -def _parse_link_header(header: str, base_url: str) -> Dict[str, str]: - """ - Parse HTTP Link header for IndieAuth endpoints - - Basic RFC 8288 support - handles simple Link headers. - Limitations: Only supports quoted rel values, single Link headers. - - Example: - Link: ; rel="token_endpoint" - - Args: - header: Link header value - base_url: Base URL for resolving relative URLs - - Returns: - Dict with discovered endpoints - """ - endpoints = {} - - # Pattern: ; rel="relation" - # Note: Simplified - doesn't handle all RFC 8288 edge cases - pattern = r'<([^>]+)>;\s*rel="([^"]+)"' - matches = re.findall(pattern, header) - - for url, rel in matches: - if rel == 'authorization_endpoint': - endpoints['authorization_endpoint'] = urljoin(base_url, url) - elif rel == 'token_endpoint': - endpoints['token_endpoint'] = urljoin(base_url, url) - - return endpoints - - -def _parse_html_links(html: str, base_url: str) -> Dict[str, str]: - """ - Extract IndieAuth endpoints from HTML link elements - - Looks for: - - - - Args: - html: HTML content - base_url: Base URL for resolving relative URLs - - Returns: - Dict with discovered endpoints - """ - endpoints = {} - - try: - soup = BeautifulSoup(html, 'html.parser') - - # Find all link elements (check both head and body - be liberal) - for link in soup.find_all('link', rel=True): - rel = link.get('rel') - href = link.get('href') - - if not href: - continue - - # rel can be a list or string - if isinstance(rel, list): - rel = ' '.join(rel) - - # Check for IndieAuth endpoints - if 'authorization_endpoint' in rel: - endpoints['authorization_endpoint'] = urljoin(base_url, href) - elif 'token_endpoint' in rel: - endpoints['token_endpoint'] = urljoin(base_url, href) - - except Exception as e: - current_app.logger.warning(f"HTML parsing error: {e}") - # Return what we found so far - - return endpoints - - -def _verify_with_endpoint(endpoint: str, token: str) -> Dict[str, Any]: - """ - Verify token with the discovered token endpoint - - Makes GET request to endpoint with Authorization header. - Implements retry logic for network errors only. - - Args: - endpoint: Token endpoint URL - token: Bearer token to verify - - Returns: - Token info dict from endpoint - - Raises: - TokenVerificationError: If verification fails - """ - headers = { - 'Authorization': f'Bearer {token}', - 'Accept': 'application/json', - } - - max_retries = 3 - for attempt in range(max_retries): - try: - response = httpx.get( - endpoint, - headers=headers, - timeout=VERIFICATION_TIMEOUT, - follow_redirects=True, - ) - - # Handle HTTP status codes - if response.status_code == 200: - token_info = response.json() - - # Validate required fields - if 'me' not in token_info: - raise TokenVerificationError("Token response missing 'me' field") - - return token_info - - # Client errors - don't retry - elif response.status_code in [400, 401, 403, 404]: - raise TokenVerificationError( - f"Token verification failed: HTTP {response.status_code}" - ) - - # Server errors - retry - elif response.status_code in [500, 502, 503, 504]: - if attempt < max_retries - 1: - wait_time = 2 ** attempt # Exponential backoff - current_app.logger.debug( - f"Server error {response.status_code}, retrying in {wait_time}s..." - ) - time.sleep(wait_time) - continue - else: - raise TokenVerificationError( - f"Token endpoint error: HTTP {response.status_code}" - ) - - # Other status codes - else: - raise TokenVerificationError( - f"Unexpected response: HTTP {response.status_code}" - ) - - except httpx.TimeoutException: - if attempt < max_retries - 1: - wait_time = 2 ** attempt - current_app.logger.debug(f"Timeout, retrying in {wait_time}s...") - time.sleep(wait_time) - continue - else: - raise TokenVerificationError("Token verification timeout") - - except httpx.NetworkError as e: - if attempt < max_retries - 1: - wait_time = 2 ** attempt - current_app.logger.debug(f"Network error, retrying in {wait_time}s...") - time.sleep(wait_time) - continue - else: - raise TokenVerificationError(f"Network error: {e}") - - except Exception as e: - # Don't retry for unexpected errors - raise TokenVerificationError(f"Verification failed: {e}") - - # Should never reach here, but just in case - raise TokenVerificationError("Maximum retries exceeded") - - -def _validate_profile_url(url: str) -> None: - """ - Validate profile URL format and security requirements - - Args: - url: Profile URL to validate - - Raises: - DiscoveryError: If URL is invalid or insecure - """ - parsed = urlparse(url) - - # Must be absolute - if not parsed.scheme or not parsed.netloc: - raise DiscoveryError(f"Invalid profile URL format: {url}") - - # HTTPS required in production - if not current_app.debug and parsed.scheme != 'https': - raise DiscoveryError( - f"HTTPS required for profile URLs in production. Got: {url}" - ) - - # Allow localhost only in debug mode - if not current_app.debug and parsed.hostname in ['localhost', '127.0.0.1', '::1']: - raise DiscoveryError( - "Localhost URLs not allowed in production" - ) - - -def _validate_endpoint_url(url: str, rel: str) -> None: - """ - Validate discovered endpoint URL - - Args: - url: Endpoint URL to validate - rel: Endpoint relation (for error messages) - - Raises: - DiscoveryError: If URL is invalid or insecure - """ - parsed = urlparse(url) - - # Must be absolute - if not parsed.scheme or not parsed.netloc: - raise DiscoveryError(f"Invalid {rel} URL format: {url}") - - # HTTPS required in production - if not current_app.debug and parsed.scheme != 'https': - raise DiscoveryError( - f"HTTPS required for {rel} in production. Got: {url}" - ) - - # Allow localhost only in debug mode - if not current_app.debug and parsed.hostname in ['localhost', '127.0.0.1', '::1']: - raise DiscoveryError( - f"Localhost not allowed for {rel} in production" - ) - - -def normalize_url(url: str) -> str: - """ - Normalize URL for comparison - - Removes trailing slash and converts to lowercase. - Used only for comparison, not for storage. - - Args: - url: URL to normalize - - Returns: - Normalized URL - """ - return url.rstrip('/').lower() - - -def _hash_token(token: str) -> str: - """ - Hash token for secure caching - - Uses SHA-256 to prevent tokens from appearing in logs - and to create fixed-length cache keys. - - Args: - token: Bearer token - - Returns: - SHA-256 hash of token (hex) - """ - return hashlib.sha256(token.encode()).hexdigest() - - -def check_scope(required_scope: str, token_scope: str) -> bool: - """ - Check if token has required scope - - Scopes are space-separated in token_scope string. - Any scope in the list satisfies the requirement. - - Args: - required_scope: Scope needed (e.g., "create") - token_scope: Space-separated scope string from token - - Returns: - True if token has required scope, False otherwise - - Examples: - >>> check_scope("create", "create update") - True - >>> check_scope("create", "read") - False - >>> check_scope("create", "") - False - """ - if not token_scope: - return False - - scopes = token_scope.split() - return required_scope in scopes diff --git a/starpunk/config.py b/starpunk/config.py index c38be42..aa1035d 100644 --- a/starpunk/config.py +++ b/starpunk/config.py @@ -35,24 +35,23 @@ def load_config(app, config_override=None): app.config["SESSION_SECRET"] = os.getenv("SESSION_SECRET") app.config["SESSION_LIFETIME"] = int(os.getenv("SESSION_LIFETIME", "30")) - # DEPRECATED: TOKEN_ENDPOINT no longer used (v1.0.0-rc.5+) - # Endpoints are now discovered from ADMIN_ME profile (ADR-031) - if 'TOKEN_ENDPOINT' in os.environ: - app.logger.warning( - "TOKEN_ENDPOINT is deprecated and will be ignored. " - "Remove it from your configuration. " - "Endpoints are now discovered automatically from your ADMIN_ME profile. " - "See docs/migration/fix-hardcoded-endpoints.md for details." - ) + # Admin login via OpenID Connect (v2.0.0, ADR-064) + # ADMIN_ME stays the site owner's identity URL (h-card, Micropub "me"); + # OIDC decides who may log in as that owner. + app.config["OIDC_ISSUER"] = os.getenv("OIDC_ISSUER", "").rstrip("/") + app.config["OIDC_CLIENT_ID"] = os.getenv("OIDC_CLIENT_ID", "") + app.config["OIDC_CLIENT_SECRET"] = os.getenv("OIDC_CLIENT_SECRET", "") + app.config["OIDC_ADMIN_SUB"] = os.getenv("OIDC_ADMIN_SUB", "") + app.config["OIDC_PROVIDER_NAME"] = os.getenv("OIDC_PROVIDER_NAME", "single sign-on") - # DEPRECATED: INDIELOGIN_URL no longer used (hotfix 2025-12-17) - # Authorization endpoint is now discovered from ADMIN_ME profile per IndieAuth spec - if 'INDIELOGIN_URL' in os.environ: - app.logger.warning( - "INDIELOGIN_URL is deprecated and will be ignored. " - "Remove it from your configuration. " - "The authorization endpoint is now discovered automatically from your ADMIN_ME profile." - ) + # Micropub access tokens issued by StarPunk's IndieAuth server (v2.0.0) + app.config["INDIEAUTH_TOKEN_LIFETIME_DAYS"] = int( + os.getenv("INDIEAUTH_TOKEN_LIFETIME_DAYS", "90") + ) + + for legacy in ("TOKEN_ENDPOINT", "INDIELOGIN_URL"): + if legacy in os.environ: + app.logger.warning(f"{legacy} is no longer used and will be ignored.") # Validate required configuration if not app.config["SESSION_SECRET"]: @@ -246,6 +245,13 @@ def validate_config(app): "Set ADMIN_ME=https://your-site.com in .env" ) + # Production mode: OIDC admin login must be configured + # (tests configure OIDC per test, so skip the check there) + if not app.config.get("TESTING"): + for field in ("OIDC_ISSUER", "OIDC_CLIENT_ID", "OIDC_CLIENT_SECRET", "OIDC_ADMIN_SUB"): + if not app.config.get(field): + errors.append(f"Production mode requires {field} to be set (see .env.example)") + # If there are validation errors, fail fast with clear message if errors: error_msg = "\n".join([ diff --git a/starpunk/indieauth.py b/starpunk/indieauth.py new file mode 100644 index 0000000..8d6d05c --- /dev/null +++ b/starpunk/indieauth.py @@ -0,0 +1,348 @@ +""" +Built-in IndieAuth authorization server for StarPunk (v2.0.0, ADR-064) + +Micropub clients (Quill, Indigenous, ...) obtain tokens through IndieAuth. +StarPunk issues them itself: the site owner approves a client after logging +in with OIDC, and StarPunk hands out an authorization code and then an +access token. Tokens are stored hashed and checked locally by /micropub. + +Only the authorization code flow with PKCE (S256) is supported, per the +current IndieAuth spec: https://indieauth.spec.indieweb.org/ +""" + +import base64 +import hashlib +import secrets +from datetime import datetime, timedelta +from typing import Any, Dict, List, Optional +from urllib.parse import urljoin, urlparse + +import httpx +from bs4 import BeautifulSoup +from flask import current_app + +from starpunk.database import get_db + +CODE_LIFETIME_MINUTES = 10 +SUPPORTED_SCOPES = ["create", "update", "delete", "media", "profile"] + + +class AuthorizationRequestError(Exception): + """ + Invalid authorization request + + redirectable=False means the client_id or redirect_uri cannot be trusted, + so the error must be shown to the user instead of sent to the client. + """ + + def __init__(self, error: str, description: str, redirectable: bool = True): + super().__init__(description) + self.error = error + self.description = description + self.redirectable = redirectable + + +class InvalidGrantError(Exception): + """Authorization code is invalid, expired, used, or does not match""" + + +def _hash(value: str) -> str: + return hashlib.sha256(value.encode()).hexdigest() + + +def issuer() -> str: + """Issuer identifier (RFC 9207): the site URL with trailing slash""" + return current_app.config["SITE_URL"].rstrip("/") + "/" + + +def site_url_for(endpoint: str) -> str: + """Absolute URL built from SITE_URL (request host/scheme is unreliable behind a proxy)""" + from flask import url_for + + return current_app.config["SITE_URL"].rstrip("/") + url_for(endpoint) + + +def admin_me() -> str: + """The single identity StarPunk issues tokens for""" + return current_app.config["ADMIN_ME"] + + +def check_scope(required_scope: str, token_scope: str) -> bool: + """True if required_scope is one of the space-separated token scopes""" + return bool(token_scope) and required_scope in token_scope.split() + + +def _is_http_url(url: str) -> bool: + parsed = urlparse(url or "") + return parsed.scheme in ("http", "https") and bool(parsed.netloc) and not parsed.fragment + + +def _same_origin(a: str, b: str) -> bool: + pa, pb = urlparse(a), urlparse(b) + return (pa.scheme, pa.hostname, pa.port) == (pb.scheme, pb.hostname, pb.port) + + +def fetch_client_redirect_uris(client_id: str) -> List[str]: + """ + Fetch the redirect URIs a client publishes at its client_id URL + + Supports a JSON client metadata document ("redirect_uris") and the older + HTML/Link header form (rel="redirect_uri"). Returns [] on any failure. + """ + from starpunk.webmention_ssrf import SSRFBlockedError, validate_url_for_fetch + + try: + if not current_app.config.get("DEV_MODE"): + validate_url_for_fetch(client_id) + response = httpx.get( + client_id, + timeout=5.0, + follow_redirects=True, + headers={"Accept": "application/json, text/html;q=0.9"}, + ) + except (httpx.HTTPError, SSRFBlockedError, ValueError) as e: + current_app.logger.info(f"IndieAuth: could not fetch client {client_id}: {e}") + return [] + + if response.status_code != 200: + return [] + + base = str(response.url) + uris: List[str] = [] + + if "json" in response.headers.get("Content-Type", ""): + try: + data = response.json() + except ValueError: + return [] + if isinstance(data, dict) and isinstance(data.get("redirect_uris"), list): + uris.extend(u for u in data["redirect_uris"] if isinstance(u, str)) + return uris + + link = response.links.get("redirect_uri") + if link and link.get("url"): + uris.append(urljoin(base, link["url"])) + + soup = BeautifulSoup(response.text[:500_000], "html.parser") + for tag in soup.find_all(["link", "a"], href=True): + if "redirect_uri" in (tag.get("rel") or []): + uris.append(urljoin(base, tag["href"])) + return uris + + +def validate_authorization_request(params: Dict[str, str]) -> Dict[str, Any]: + """ + Validate an IndieAuth authorization request + + Args: + params: Query (or form) parameters from the client + + Returns: + Normalized request: client_id, redirect_uri, state, scopes, + code_challenge + + Raises: + AuthorizationRequestError + """ + client_id = (params.get("client_id") or "").strip() + redirect_uri = (params.get("redirect_uri") or "").strip() + + # client_id / redirect_uri problems are never redirected to the client + if not _is_http_url(client_id): + raise AuthorizationRequestError( + "invalid_request", "client_id must be an http(s) URL", redirectable=False + ) + if not redirect_uri or urlparse(redirect_uri).fragment: + raise AuthorizationRequestError( + "invalid_request", "redirect_uri is missing or invalid", redirectable=False + ) + if not _same_origin(client_id, redirect_uri): + if redirect_uri not in fetch_client_redirect_uris(client_id): + raise AuthorizationRequestError( + "invalid_request", + "redirect_uri is not registered by this client", + redirectable=False, + ) + + if params.get("response_type", "code") != "code": + raise AuthorizationRequestError( + "unsupported_response_type", "Only response_type=code is supported" + ) + if not params.get("state"): + raise AuthorizationRequestError("invalid_request", "state is required") + + code_challenge = params.get("code_challenge") or "" + if not code_challenge: + raise AuthorizationRequestError("invalid_request", "PKCE code_challenge is required") + if params.get("code_challenge_method", "S256") != "S256": + raise AuthorizationRequestError( + "invalid_request", "Only code_challenge_method=S256 is supported" + ) + + scopes = [s for s in (params.get("scope") or "").split() if s] + + return { + "client_id": client_id, + "redirect_uri": redirect_uri, + "state": params["state"], + "scopes": scopes, + "code_challenge": code_challenge, + } + + +def create_authorization_code( + client_id: str, redirect_uri: str, scope: str, code_challenge: str +) -> str: + """Issue a single-use authorization code (stored hashed)""" + code = secrets.token_urlsafe(32) + db = get_db(current_app) + db.execute("DELETE FROM indieauth_codes WHERE expires_at <= datetime('now')") + db.execute( + """ + INSERT INTO indieauth_codes + (code_hash, client_id, redirect_uri, scope, code_challenge, expires_at) + VALUES (?, ?, ?, ?, ?, ?) + """, + ( + _hash(code), + client_id, + redirect_uri, + scope, + code_challenge, + datetime.utcnow() + timedelta(minutes=CODE_LIFETIME_MINUTES), + ), + ) + db.commit() + return code + + +def redeem_authorization_code( + code: str, client_id: str, redirect_uri: str, code_verifier: str +) -> Dict[str, Any]: + """ + Redeem an authorization code exactly once + + Returns: + {"me": ..., "scope": ..., "client_id": ...} + + Raises: + InvalidGrantError + """ + if not code or not code_verifier: + raise InvalidGrantError("code and code_verifier are required") + + db = get_db(current_app) + # Atomic single use: only the first redemption flips used_at + cursor = db.execute( + """ + UPDATE indieauth_codes SET used_at = datetime('now') + WHERE code_hash = ? AND used_at IS NULL AND expires_at > datetime('now') + """, + (_hash(code),), + ) + db.commit() + if cursor.rowcount != 1: + raise InvalidGrantError("Authorization code is invalid, expired or already used") + + row = db.execute( + "SELECT client_id, redirect_uri, scope, code_challenge FROM indieauth_codes WHERE code_hash = ?", + (_hash(code),), + ).fetchone() + + if row["client_id"] != client_id or row["redirect_uri"] != redirect_uri: + raise InvalidGrantError("client_id or redirect_uri does not match the code") + + digest = hashlib.sha256(code_verifier.encode("ascii", "ignore")).digest() + challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii") + if not secrets.compare_digest(challenge, row["code_challenge"]): + raise InvalidGrantError("PKCE verification failed") + + return {"me": admin_me(), "scope": row["scope"], "client_id": row["client_id"]} + + +def create_access_token(client_id: str, scope: str) -> Dict[str, Any]: + """Issue an access token (stored hashed); returns the token response""" + token = secrets.token_urlsafe(32) + lifetime_days = current_app.config.get("INDIEAUTH_TOKEN_LIFETIME_DAYS", 90) + expires_at = datetime.utcnow() + timedelta(days=lifetime_days) + + db = get_db(current_app) + db.execute( + """ + INSERT INTO indieauth_tokens (token_hash, client_id, scope, expires_at) + VALUES (?, ?, ?, ?) + """, + (_hash(token), client_id, scope, expires_at), + ) + db.commit() + + current_app.logger.info(f"IndieAuth: token issued to {client_id} (scope: {scope})") + return { + "access_token": token, + "token_type": "Bearer", + "scope": scope, + "me": admin_me(), + "expires_in": lifetime_days * 86400, + } + + +def verify_access_token(token: str) -> Optional[Dict[str, Any]]: + """ + Check a bearer token issued by StarPunk + + Returns: + {"me", "client_id", "scope"} if active, otherwise None + """ + if not token: + return None + db = get_db(current_app) + row = db.execute( + """ + SELECT id, client_id, scope FROM indieauth_tokens + WHERE token_hash = ? AND revoked_at IS NULL AND expires_at > datetime('now') + """, + (_hash(token),), + ).fetchone() + if not row: + return None + + db.execute( + "UPDATE indieauth_tokens SET last_used_at = datetime('now') WHERE id = ?", + (row["id"],), + ) + db.commit() + return {"me": admin_me(), "client_id": row["client_id"], "scope": row["scope"]} + + +def revoke_access_token(token: str) -> None: + """Revoke a token by value (unknown tokens are ignored, per RFC 7009)""" + db = get_db(current_app) + db.execute( + "UPDATE indieauth_tokens SET revoked_at = datetime('now') WHERE token_hash = ? AND revoked_at IS NULL", + (_hash(token or ""),), + ) + db.commit() + + +def revoke_token_by_id(token_id: int) -> None: + """Revoke a token from the admin UI""" + db = get_db(current_app) + db.execute( + "UPDATE indieauth_tokens SET revoked_at = datetime('now') WHERE id = ? AND revoked_at IS NULL", + (token_id,), + ) + db.commit() + + +def list_active_tokens() -> List[Dict[str, Any]]: + """Tokens that can still be used, newest first""" + db = get_db(current_app) + rows = db.execute( + """ + SELECT id, client_id, scope, created_at, expires_at, last_used_at + FROM indieauth_tokens + WHERE revoked_at IS NULL AND expires_at > datetime('now') + ORDER BY created_at DESC + """ + ).fetchall() + return [dict(r) for r in rows] diff --git a/starpunk/micropub.py b/starpunk/micropub.py index 86bbff2..bbd1ec2 100644 --- a/starpunk/micropub.py +++ b/starpunk/micropub.py @@ -29,7 +29,7 @@ from typing import Optional from flask import Request, current_app, jsonify from starpunk.notes import create_note, get_note, InvalidNoteDataError, NoteNotFoundError -from starpunk.auth_external import check_scope +from starpunk.indieauth import check_scope # Custom Exceptions diff --git a/starpunk/routes/__init__.py b/starpunk/routes/__init__.py index 0ac464a..2bcada9 100644 --- a/starpunk/routes/__init__.py +++ b/starpunk/routes/__init__.py @@ -7,7 +7,7 @@ admin, auth, and (conditionally) dev auth routes. from flask import Flask -from starpunk.routes import admin, auth, micropub, public, search, webmention +from starpunk.routes import admin, auth, indieauth, micropub, public, search, webmention def register_routes(app: Flask) -> None: @@ -29,6 +29,7 @@ def register_routes(app: Flask) -> None: # Register auth routes app.register_blueprint(auth.bp) + app.register_blueprint(indieauth.bp) # Register Micropub routes app.register_blueprint(micropub.bp) diff --git a/starpunk/routes/admin.py b/starpunk/routes/admin.py index 057b0ac..d51884a 100644 --- a/starpunk/routes/admin.py +++ b/starpunk/routes/admin.py @@ -816,3 +816,25 @@ def webmention_bulk_action(): logger.error(f"Error performing bulk action: {e}") flash(f"Error: {e}", "error") return redirect(url_for("admin.webmentions")) + + +# Connected Micropub apps (v2.0.0) + +@bp.route("/tokens") +@require_auth +def tokens(): + """List active IndieAuth tokens. Template: templates/admin/tokens.html""" + from starpunk.indieauth import list_active_tokens + + return render_template("admin/tokens.html", tokens=list_active_tokens(), user_me=g.me) + + +@bp.route("/tokens//revoke", methods=["POST"]) +@require_auth +def revoke_token(token_id): + """Revoke one IndieAuth token""" + from starpunk.indieauth import revoke_token_by_id + + revoke_token_by_id(token_id) + flash("App access revoked", "success") + return redirect(url_for("admin.tokens")) diff --git a/starpunk/routes/auth.py b/starpunk/routes/auth.py index a968e79..db42839 100644 --- a/starpunk/routes/auth.py +++ b/starpunk/routes/auth.py @@ -1,15 +1,14 @@ """ Authentication routes for StarPunk -Handles IndieLogin authentication flow including login form, OAuth callback, -logout functionality, and IndieAuth endpoints for Micropub clients. +Admin login form, OIDC start/callback, and logout. +The IndieAuth server endpoints for Micropub clients live in routes/indieauth.py. """ from flask import ( Blueprint, current_app, flash, - jsonify, redirect, render_template, request, @@ -18,8 +17,9 @@ from flask import ( ) from starpunk.auth import ( - IndieLoginError, + AuthError, InvalidStateError, + OIDCError, UnauthorizedError, destroy_session, handle_callback, @@ -27,167 +27,104 @@ from starpunk.auth import ( require_auth, verify_session, ) -from starpunk.auth_external import DiscoveryError # Create blueprint bp = Blueprint("auth", __name__, url_prefix="/auth") +SESSION_COOKIE = "starpunk_session" + @bp.route("/login", methods=["GET"]) def login_form(): """ - Display login form - - If user is already authenticated, redirects to admin dashboard. - Otherwise shows login form for IndieLogin authentication. - - Returns: - Redirect to dashboard if authenticated, otherwise login template + Show the login page, or go to the dashboard if already logged in Template: templates/admin/login.html """ - # Check if already logged in - session_token = request.cookies.get("starpunk_session") + session_token = request.cookies.get(SESSION_COOKIE) if session_token and verify_session(session_token): - return redirect(url_for("admin.dashboard")) + return redirect(session.pop("next", None) or url_for("admin.dashboard")) return render_template("admin/login.html") @bp.route("/login", methods=["POST"]) def login_initiate(): - """ - Initiate IndieLogin authentication flow - - Validates the submitted 'me' URL and redirects to IndieLogin.com - for authentication. - - Form data: - me: User's personal website URL - - Returns: - Redirect to IndieLogin.com or back to login form on error - - Raises: - Flashes error message and redirects on validation failure - """ - me_url = request.form.get("me", "").strip() - - if not me_url: - flash("Please enter your website URL", "error") - return redirect(url_for("auth.login_form")) - + """Start OIDC login and redirect to the identity provider""" try: - # Initiate IndieAuth flow - auth_url = initiate_login(me_url) - return redirect(auth_url) - except ValueError as e: - flash(str(e), "error") - return redirect(url_for("auth.login_form")) - except DiscoveryError as e: - current_app.logger.error(f"Endpoint discovery failed for {me_url}: {e}") - flash("Unable to verify your profile URL. Please check that it's correct and try again.", "error") + return redirect(initiate_login(session.pop("next", None))) + except OIDCError as e: + current_app.logger.error(f"OIDC login could not start: {e}") + flash("The identity provider is unavailable. Please try again later.", "error") return redirect(url_for("auth.login_form")) @bp.route("/callback") def callback(): """ - Handle IndieLogin callback - - Processes the OAuth callback from IndieLogin.com, validates the - authorization code, state token, and issuer, then creates an - authenticated session using PKCE verification. + Handle the identity provider's redirect Query parameters: - code: Authorization code from IndieLogin - state: CSRF state token - iss: Issuer identifier (should be https://indielogin.com/) - - Returns: - Redirect to admin dashboard on success, login form on failure + code, state: Authorization response + iss: Issuer identifier (RFC 9207) + error, error_description: Provider-reported failure Sets: - session cookie (HttpOnly, Secure, SameSite=Lax, 30 day expiry) + session cookie (HttpOnly, Secure, SameSite=Lax) """ + if request.args.get("error"): + current_app.logger.warning( + f"OIDC provider returned error: {request.args.get('error')} " + f"{request.args.get('error_description', '')}" + ) + flash("Login was cancelled or refused by the identity provider", "error") + return redirect(url_for("auth.login_form")) + code = request.args.get("code") state = request.args.get("state") - iss = request.args.get("iss") # Extract issuer parameter - if not code or not state: flash("Missing authentication parameters", "error") return redirect(url_for("auth.login_form")) try: - # Handle callback and create session with PKCE verification - session_token = handle_callback(code, state, iss) # Pass issuer - - # Create response with redirect - response = redirect(url_for("admin.dashboard")) - - # Set secure session cookie - secure = current_app.config.get("SITE_URL", "").startswith("https://") - response.set_cookie( - "starpunk_session", - session_token, - httponly=True, - secure=secure, - samesite="Lax", - max_age=30 * 24 * 60 * 60, # 30 days - ) - - flash("Login successful!", "success") - return response - - except InvalidStateError as e: - current_app.logger.error(f"Invalid state error: {e}") - flash("Authentication failed: Invalid state token (possible CSRF)", "error") + session_token, next_url = handle_callback(code, state, request.args.get("iss")) + except InvalidStateError: + flash("Login expired or was already used. Please try again.", "error") return redirect(url_for("auth.login_form")) - - except UnauthorizedError as e: - current_app.logger.error(f"Unauthorized: {e}") + except UnauthorizedError: flash("Authentication failed: Not authorized as admin", "error") return redirect(url_for("auth.login_form")) - - except IndieLoginError as e: - current_app.logger.error(f"IndieLogin error: {e}") - flash(f"Authentication failed: {e}", "error") + except AuthError as e: + current_app.logger.error(f"OIDC login failed: {e}") + flash("Authentication failed. Please try again.", "error") return redirect(url_for("auth.login_form")) - except Exception as e: - current_app.logger.error(f"Unexpected auth error: {e}") - flash("Authentication failed: An unexpected error occurred", "error") - return redirect(url_for("auth.login_form")) + response = redirect(next_url or url_for("admin.dashboard")) + response.set_cookie( + SESSION_COOKIE, + session_token, + httponly=True, + secure=current_app.config.get("SITE_URL", "").startswith("https://"), + samesite="Lax", + max_age=current_app.config.get("SESSION_LIFETIME", 30) * 24 * 60 * 60, + ) + if not next_url: + flash("Login successful!", "success") + return response @bp.route("/logout", methods=["POST"]) @require_auth def logout(): - """ - Logout and destroy session - - Destroys the user's session and clears the session cookie. - Requires authentication (user must be logged in to logout). - - Returns: - Redirect to homepage with session cookie cleared - - Decorator: @require_auth - """ - session_token = request.cookies.get("starpunk_session") - - # Destroy session in database + """Destroy the session and clear the cookie""" + session_token = request.cookies.get(SESSION_COOKIE) if session_token: try: destroy_session(session_token) except Exception as e: current_app.logger.error(f"Error destroying session: {e}") - # Clear cookie and redirect response = redirect(url_for("public.index")) - response.delete_cookie("starpunk_session") - + response.delete_cookie(SESSION_COOKIE) flash("Logged out successfully", "success") return response - - diff --git a/starpunk/routes/indieauth.py b/starpunk/routes/indieauth.py new file mode 100644 index 0000000..d8c12dc --- /dev/null +++ b/starpunk/routes/indieauth.py @@ -0,0 +1,228 @@ +""" +IndieAuth server routes for StarPunk (v2.0.0, ADR-064) + +Endpoints: + GET /.well-known/oauth-authorization-server Server metadata + GET /auth/authorize Consent screen (admin login required) + POST /auth/authorize Profile-only code redemption + POST /auth/authorize/approve Consent decision + POST /auth/token Code -> access token (and legacy revoke) + GET /auth/token Legacy token verification + POST /auth/revoke Token revocation (RFC 7009) +""" + +from urllib.parse import urlencode, urlparse, urlunparse, parse_qsl + +from flask import ( + Blueprint, + current_app, + jsonify, + redirect, + render_template, + request, + session, + url_for, +) + +from starpunk.auth import verify_session +from starpunk.indieauth import ( + SUPPORTED_SCOPES, + AuthorizationRequestError, + InvalidGrantError, + create_access_token, + create_authorization_code, + issuer, + redeem_authorization_code, + revoke_access_token, + site_url_for, + validate_authorization_request, + verify_access_token, +) +from starpunk.micropub import extract_bearer_token + +bp = Blueprint("indieauth", __name__) + +# Parameters carried from the consent screen back to the approve handler +_REQUEST_FIELDS = ( + "response_type", + "client_id", + "redirect_uri", + "state", + "code_challenge", + "code_challenge_method", + "scope", +) + + +def _json(payload: dict, status: int = 200): + response = jsonify(payload) + response.status_code = status + response.headers["Cache-Control"] = "no-store" + return response + + +def _oauth_error(error: str, description: str, status: int = 400): + return _json({"error": error, "error_description": description}, status) + + +def _redirect_with(redirect_uri: str, params: dict): + """Append params to redirect_uri, keeping any query it already has""" + parts = urlparse(redirect_uri) + query = parse_qsl(parts.query, keep_blank_values=True) + list(params.items()) + return redirect(urlunparse(parts._replace(query=urlencode(query)))) + + +def _admin_session(): + return verify_session(request.cookies.get("starpunk_session")) + + +def _request_error_page(error: AuthorizationRequestError): + return ( + render_template("admin/authorize.html", request_error=error.description), + 400, + ) + + +@bp.route("/.well-known/oauth-authorization-server") +def metadata(): + """IndieAuth server metadata""" + return _json( + { + "issuer": issuer(), + "authorization_endpoint": site_url_for("indieauth.authorize"), + "token_endpoint": site_url_for("indieauth.token"), + "revocation_endpoint": site_url_for("indieauth.revoke"), + "revocation_endpoint_auth_methods_supported": ["none"], + "scopes_supported": SUPPORTED_SCOPES, + "response_types_supported": ["code"], + "grant_types_supported": ["authorization_code"], + "code_challenge_methods_supported": ["S256"], + "authorization_response_iss_parameter_supported": True, + } + ) + + +@bp.route("/auth/authorize", methods=["GET"]) +def authorize(): + """Show the consent screen to the logged-in admin""" + try: + auth_request = validate_authorization_request(request.args.to_dict()) + except AuthorizationRequestError as e: + if not e.redirectable: + return _request_error_page(e) + return _redirect_with( + request.args["redirect_uri"], + { + "error": e.error, + "error_description": e.description, + "state": request.args.get("state", ""), + "iss": issuer(), + }, + ) + + if not _admin_session(): + # Come back here after logging in with OIDC + session["next"] = request.url + return redirect(url_for("auth.login_form")) + + return render_template( + "admin/authorize.html", + auth_request=auth_request, + fields={k: request.args.get(k, "") for k in _REQUEST_FIELDS}, + me=current_app.config["ADMIN_ME"], + ) + + +@bp.route("/auth/authorize/approve", methods=["POST"]) +def approve(): + """Record the admin's consent decision and redirect to the client""" + if not _admin_session(): + return redirect(url_for("auth.login_form")) + + params = {k: request.form.get(k, "") for k in _REQUEST_FIELDS} + try: + auth_request = validate_authorization_request(params) + except AuthorizationRequestError as e: + return _request_error_page(e) + + if request.form.get("decision") != "approve": + return _redirect_with( + auth_request["redirect_uri"], + {"error": "access_denied", "state": auth_request["state"], "iss": issuer()}, + ) + + # Only scopes that were both requested and left checked + granted = [s for s in auth_request["scopes"] if s in request.form.getlist("scope_granted")] + code = create_authorization_code( + auth_request["client_id"], + auth_request["redirect_uri"], + " ".join(granted), + auth_request["code_challenge"], + ) + current_app.logger.info( + f"IndieAuth: approved {auth_request['client_id']} (scope: {' '.join(granted) or 'none'})" + ) + return _redirect_with( + auth_request["redirect_uri"], + {"code": code, "state": auth_request["state"], "iss": issuer()}, + ) + + +def _redeem_from_form(): + return redeem_authorization_code( + request.form.get("code", ""), + request.form.get("client_id", ""), + request.form.get("redirect_uri", ""), + request.form.get("code_verifier", ""), + ) + + +@bp.route("/auth/authorize", methods=["POST"]) +def authorize_redeem(): + """Profile-only flow: redeem a code for the user's identity""" + if request.form.get("grant_type", "authorization_code") != "authorization_code": + return _oauth_error("unsupported_grant_type", "Only authorization_code is supported") + try: + result = _redeem_from_form() + except InvalidGrantError as e: + return _oauth_error("invalid_grant", str(e)) + return _json({"me": result["me"]}) + + +@bp.route("/auth/token", methods=["POST"]) +def token(): + """Exchange an authorization code for an access token""" + if request.form.get("action") == "revoke": + # Legacy IndieAuth revocation + revoke_access_token(request.form.get("token", "")) + return _json({}) + + if request.form.get("grant_type") != "authorization_code": + return _oauth_error("unsupported_grant_type", "Only authorization_code is supported") + + try: + result = _redeem_from_form() + except InvalidGrantError as e: + return _oauth_error("invalid_grant", str(e)) + + if not result["scope"]: + # Spec: a code issued without scope cannot be used for an access token + return _oauth_error("invalid_grant", "No scope was granted; use the authorization endpoint") + + return _json(create_access_token(result["client_id"], result["scope"])) + + +@bp.route("/auth/token", methods=["GET"]) +def token_verify(): + """Legacy token verification for clients that still call it""" + info = verify_access_token(extract_bearer_token(request)) + if not info: + return _oauth_error("unauthorized", "Invalid or expired access token", 401) + return _json(info) + + +@bp.route("/auth/revoke", methods=["POST"]) +def revoke(): + """RFC 7009 token revocation (always 200)""" + revoke_access_token(request.form.get("token", "")) + return _json({}) diff --git a/starpunk/routes/micropub.py b/starpunk/routes/micropub.py index 724de68..12cffa0 100644 --- a/starpunk/routes/micropub.py +++ b/starpunk/routes/micropub.py @@ -17,6 +17,7 @@ References: - W3C Micropub Specification: https://www.w3.org/TR/micropub/ - ADR-028: Micropub Implementation Strategy - ADR-029: Micropub IndieAuth Integration Strategy + - ADR-064: Tokens are issued and verified by StarPunk itself """ from flask import Blueprint, current_app, request, make_response @@ -28,7 +29,7 @@ from starpunk.micropub import ( handle_create, handle_query, ) -from starpunk.auth_external import verify_external_token, check_scope +from starpunk.indieauth import verify_access_token, check_scope # Create blueprint bp = Blueprint("micropub", __name__) @@ -71,7 +72,7 @@ def micropub_endpoint(): if not token: return error_response("unauthorized", "No access token provided", 401) - token_info = verify_external_token(token) + token_info = verify_access_token(token) if not token_info: return error_response("unauthorized", "Invalid or expired access token", 401) @@ -140,7 +141,7 @@ def media_endpoint(): if not token: return error_response("unauthorized", "No access token provided", 401) - token_info = verify_external_token(token) + token_info = verify_access_token(token) if not token_info: return error_response("unauthorized", "Invalid or expired access token", 401) diff --git a/templates/admin/authorize.html b/templates/admin/authorize.html new file mode 100644 index 0000000..f4300d0 --- /dev/null +++ b/templates/admin/authorize.html @@ -0,0 +1,43 @@ +{% extends "base.html" %} + +{% block title %}Authorize App - StarPunk{% endblock %} + +{% block content %} + +{% endblock %} diff --git a/templates/admin/base.html b/templates/admin/base.html index 58bb4b5..27aeebb 100644 --- a/templates/admin/base.html +++ b/templates/admin/base.html @@ -6,6 +6,7 @@ Dashboard New Note Metrics + Connected Apps
diff --git a/templates/admin/login.html b/templates/admin/login.html index 63fb9fb..43df359 100644 --- a/templates/admin/login.html +++ b/templates/admin/login.html @@ -5,23 +5,10 @@ {% block content %} {% endif %} - -
{% endblock %} diff --git a/templates/admin/tokens.html b/templates/admin/tokens.html new file mode 100644 index 0000000..94f26be --- /dev/null +++ b/templates/admin/tokens.html @@ -0,0 +1,44 @@ +{% extends "admin/base.html" %} + +{% block title %}Connected Apps - StarPunk Admin{% endblock %} + +{% block admin_content %} +
+

Connected Apps

+

Micropub apps you have approved. Revoke any you no longer use.

+ + {% if tokens %} + + + + + + + + + + + + + {% for t in tokens %} + + + + + + + + + {% endfor %} + +
AppScopeApprovedLast usedExpires
{{ t.client_id }}{{ t.scope }}{{ t.created_at }}{{ t.last_used_at or "never" }}{{ t.expires_at }} +
+ +
+
+ {% else %} +

No apps connected.

+ {% endif %} +
+{% endblock %} diff --git a/templates/base.html b/templates/base.html index b73cb41..c9d39f8 100644 --- a/templates/base.html +++ b/templates/base.html @@ -11,6 +11,10 @@ {# Webmention endpoint (v1.6.0) #} {% if config.WEBMENTION_ENABLED %} + + + + {% endif %} {# rel-me links from discovered author profile (v1.2.0 Phase 2) #} diff --git a/tests/test_auth.py b/tests/test_auth.py index 555957b..85fedef 100644 --- a/tests/test_auth.py +++ b/tests/test_auth.py @@ -12,21 +12,11 @@ import pytest from flask import g from starpunk.auth import ( - AuthError, - IndieLoginError, - InvalidStateError, - UnauthorizedError, _cleanup_expired_sessions, _generate_state_token, _hash_token, - _log_http_request, - _log_http_response, - _redact_token, - _verify_state_token, create_session, destroy_session, - handle_callback, - initiate_login, require_auth, verify_session, ) @@ -104,45 +94,6 @@ class TestHelpers: assert len(set(tokens)) == 10 -class TestStateTokenVerification: - def test_verify_valid_state_token(self, app, db): - """Test verifying a valid state token""" - with app.app_context(): - state = secrets.token_urlsafe(32) - expires_at = datetime.utcnow() + timedelta(minutes=5) - - db.execute( - "INSERT INTO auth_state (state, expires_at) VALUES (?, ?)", - (state, expires_at), - ) - db.commit() - - assert _verify_state_token(state) is True - - # Token should be deleted after verification - result = db.execute( - "SELECT 1 FROM auth_state WHERE state = ?", (state,) - ).fetchone() - assert result is None - - def test_verify_invalid_state_token(self, app): - """Test verifying an invalid state token""" - with app.app_context(): - assert _verify_state_token("invalid-token") is False - - def test_verify_expired_state_token(self, app, db): - """Test verifying an expired state token""" - with app.app_context(): - state = secrets.token_urlsafe(32) - expires_at = datetime.utcnow() - timedelta(minutes=5) - - db.execute( - "INSERT INTO auth_state (state, expires_at) VALUES (?, ?)", - (state, expires_at), - ) - db.commit() - - assert _verify_state_token(state) is False class TestCleanup: @@ -170,25 +121,6 @@ class TestCleanup: ).fetchone() assert result is None - def test_cleanup_expired_auth_state(self, app, db): - """Test cleanup of expired auth state""" - with app.app_context(): - state = secrets.token_urlsafe(32) - expires_at = datetime.utcnow() - timedelta(minutes=10) - - db.execute( - "INSERT INTO auth_state (state, expires_at) VALUES (?, ?)", - (state, expires_at), - ) - db.commit() - - _cleanup_expired_sessions() - - # Expired state should be deleted - result = db.execute( - "SELECT 1 FROM auth_state WHERE state = ?", (state,) - ).fetchone() - assert result is None def test_cleanup_keeps_valid_sessions(self, app, db): """Test that cleanup keeps valid sessions""" @@ -214,185 +146,8 @@ class TestCleanup: assert result is not None -class TestInitiateLogin: - @patch("starpunk.auth.discover_endpoints") - def test_initiate_login_success(self, mock_discover, app, db): - """Test successful login initiation""" - mock_discover.return_value = { - 'authorization_endpoint': 'https://auth.example.com/authorize', - 'token_endpoint': 'https://auth.example.com/token' - } - - with app.app_context(): - me_url = "https://example.com" - auth_url = initiate_login(me_url) - - # Changed: Check for discovered endpoint instead of indielogin.com - assert "auth.example.com/authorize" in auth_url - assert "me=https%3A%2F%2Fexample.com" in auth_url - assert "client_id=" in auth_url - assert "redirect_uri=" in auth_url - assert "state=" in auth_url - # Per W3C IndieAuth: response_type=id for authentication-only (identity verification) - assert "response_type=id" in auth_url - - # State should be stored in database - result = db.execute("SELECT COUNT(*) as count FROM auth_state").fetchone() - assert result["count"] > 0 - - def test_initiate_login_invalid_url(self, app): - """Test login initiation with invalid URL""" - with app.app_context(): - with pytest.raises(ValueError, match="Invalid URL format"): - initiate_login("not-a-url") - - @patch("starpunk.auth.discover_endpoints") - def test_initiate_login_stores_state(self, mock_discover, app, db): - """Test that state token is stored""" - mock_discover.return_value = { - 'authorization_endpoint': 'https://auth.example.com/authorize', - 'token_endpoint': 'https://auth.example.com/token' - } - - with app.app_context(): - me_url = "https://example.com" - auth_url = initiate_login(me_url) - - # Extract state from URL - state_param = [p for p in auth_url.split("&") if p.startswith("state=")][0] - state = state_param.split("=")[1] - - # State should exist in database - result = db.execute( - "SELECT expires_at FROM auth_state WHERE state = ?", (state,) - ).fetchone() - assert result is not None -class TestHandleCallback: - @patch("starpunk.auth.discover_endpoints") - @patch("starpunk.auth.httpx.post") - def test_handle_callback_success(self, mock_post, mock_discover, app, db, client): - """Test successful callback handling""" - mock_discover.return_value = { - 'authorization_endpoint': 'https://auth.example.com/authorize', - 'token_endpoint': 'https://auth.example.com/token' - } - - with app.test_request_context(): - # Setup state token - state = secrets.token_urlsafe(32) - expires_at = datetime.utcnow() + timedelta(minutes=5) - db.execute( - "INSERT INTO auth_state (state, expires_at) VALUES (?, ?)", - (state, expires_at), - ) - db.commit() - - # Mock authorization endpoint response - mock_response = MagicMock() - mock_response.json.return_value = {"me": "https://example.com"} - mock_post.return_value = mock_response - - # Handle callback - code = "test-code" - session_token = handle_callback(code, state) - - assert session_token is not None - assert isinstance(session_token, str) - - # Session should be created - token_hash = _hash_token(session_token) - result = db.execute( - "SELECT me FROM sessions WHERE session_token_hash = ?", (token_hash,) - ).fetchone() - assert result is not None - assert result["me"] == "https://example.com" - - def test_handle_callback_invalid_state(self, app): - """Test callback with invalid state""" - with app.app_context(): - with pytest.raises(InvalidStateError): - handle_callback("code", "invalid-state") - - @patch("starpunk.auth.discover_endpoints") - @patch("starpunk.auth.httpx.post") - def test_handle_callback_unauthorized_user(self, mock_post, mock_discover, app, db): - """Test callback with unauthorized user""" - mock_discover.return_value = { - 'authorization_endpoint': 'https://auth.example.com/authorize', - 'token_endpoint': 'https://auth.example.com/token' - } - - with app.app_context(): - # Setup state token - state = secrets.token_urlsafe(32) - expires_at = datetime.utcnow() + timedelta(minutes=5) - db.execute( - "INSERT INTO auth_state (state, expires_at) VALUES (?, ?)", - (state, expires_at), - ) - db.commit() - - # Mock authorization endpoint response with different user - mock_response = MagicMock() - mock_response.json.return_value = {"me": "https://attacker.com"} - mock_post.return_value = mock_response - - with pytest.raises(UnauthorizedError): - handle_callback("code", state) - - @patch("starpunk.auth.discover_endpoints") - @patch("starpunk.auth.httpx.post") - def test_handle_callback_indielogin_error(self, mock_post, mock_discover, app, db): - """Test callback with authorization endpoint error""" - mock_discover.return_value = { - 'authorization_endpoint': 'https://auth.example.com/authorize', - 'token_endpoint': 'https://auth.example.com/token' - } - - with app.app_context(): - # Setup state token - state = secrets.token_urlsafe(32) - expires_at = datetime.utcnow() + timedelta(minutes=5) - db.execute( - "INSERT INTO auth_state (state, expires_at) VALUES (?, ?)", - (state, expires_at), - ) - db.commit() - - # Mock authorization endpoint error - mock_post.side_effect = httpx.RequestError("Connection failed") - - with pytest.raises(IndieLoginError): - handle_callback("code", state) - - @patch("starpunk.auth.discover_endpoints") - @patch("starpunk.auth.httpx.post") - def test_handle_callback_no_identity(self, mock_post, mock_discover, app, db): - """Test callback with no identity in response""" - mock_discover.return_value = { - 'authorization_endpoint': 'https://auth.example.com/authorize', - 'token_endpoint': 'https://auth.example.com/token' - } - - with app.app_context(): - # Setup state token - state = secrets.token_urlsafe(32) - expires_at = datetime.utcnow() + timedelta(minutes=5) - db.execute( - "INSERT INTO auth_state (state, expires_at) VALUES (?, ?)", - (state, expires_at), - ) - db.commit() - - # Mock authorization endpoint response without 'me' field - mock_response = MagicMock() - mock_response.json.return_value = {} - mock_post.return_value = mock_response - - with pytest.raises(IndieLoginError, match="No identity returned"): - handle_callback("code", state) class TestCreateSession: @@ -625,23 +380,6 @@ class TestSecurityFeatures: assert result["session_token_hash"] != session_token assert len(result["session_token_hash"]) == 64 # SHA-256 hex length - def test_state_tokens_are_single_use(self, app, db): - """Test that state tokens can only be used once""" - with app.app_context(): - state = secrets.token_urlsafe(32) - expires_at = datetime.utcnow() + timedelta(minutes=5) - - db.execute( - "INSERT INTO auth_state (state, expires_at) VALUES (?, ?)", - (state, expires_at), - ) - db.commit() - - # First verification should succeed - assert _verify_state_token(state) is True - - # Second verification should fail (token deleted) - assert _verify_state_token(state) is False def test_session_expiry(self, app, db, client): """Test that sessions expire correctly""" @@ -668,273 +406,13 @@ class TestSecurityFeatures: assert delta.total_seconds() <= 86401 # At most 1 day + 1 second -class TestExceptionHierarchy: - def test_exception_inheritance(self): - """Test that custom exceptions inherit correctly""" - assert issubclass(InvalidStateError, AuthError) - assert issubclass(UnauthorizedError, AuthError) - assert issubclass(IndieLoginError, AuthError) - assert issubclass(AuthError, Exception) - - def test_exception_messages(self): - """Test that exceptions can carry messages""" - error = InvalidStateError("Test message") - assert str(error) == "Test message" - - error = UnauthorizedError("Unauthorized") - assert str(error) == "Unauthorized" - - error = IndieLoginError("Service error") - assert str(error) == "Service error" -class TestLoggingHelpers: - def test_redact_token_normal(self): - """Test token redaction for normal-length tokens""" - token = "abcdefghijklmnopqrstuvwxyz" - result = _redact_token(token, 6) - assert result == "abcdef...********...wxyz" - - def test_redact_token_short(self): - """Test token redaction for short tokens""" - token = "short" - result = _redact_token(token, 6) - assert result == "***REDACTED***" - - def test_redact_token_empty(self): - """Test token redaction for empty tokens""" - result = _redact_token("", 6) - assert result == "***REDACTED***" - - result = _redact_token(None, 6) - assert result == "***REDACTED***" - - def test_redact_token_custom_length(self): - """Test token redaction with custom show_chars""" - token = "abcdefghijklmnopqrstuvwxyz" - result = _redact_token(token, 8) - assert result == "abcdefgh...********...wxyz" - - def test_log_http_request_redacts_code(self, app, caplog): - """Test that code parameter is redacted in request logs""" - import logging - - with app.app_context(): - # Set DEBUG level for logging - app.logger.setLevel(logging.DEBUG) - - with caplog.at_level(logging.DEBUG): - _log_http_request( - method="POST", - url="https://indielogin.com/auth", - data={"code": "sensitive_code_12345"}, - ) - - # Should log but with redacted code - assert "sensitive_code_12345" not in caplog.text - assert "sensit...********...2345" in caplog.text - - def test_log_http_request_redacts_state(self, app, caplog): - """Test that state parameter is redacted in request logs""" - import logging - - with app.app_context(): - app.logger.setLevel(logging.DEBUG) - - with caplog.at_level(logging.DEBUG): - _log_http_request( - method="POST", - url="https://indielogin.com/auth", - data={"state": "state_token_123456789"}, - ) - - # Should log but with redacted state (8 chars shown at start) - assert "state_token_123456789" not in caplog.text - assert "state_to...********...6789" in caplog.text - - def test_log_http_request_not_logged_at_info(self, app, caplog): - """Test that HTTP requests are not logged at INFO level""" - import logging - - with app.app_context(): - app.logger.setLevel(logging.INFO) - - with caplog.at_level(logging.INFO): - _log_http_request( - method="POST", - url="https://indielogin.com/auth", - data={"code": "test_code"}, - ) - - # Should not log anything - assert "IndieAuth HTTP Request" not in caplog.text - - def test_log_http_response_redacts_tokens(self, app, caplog): - """Test that response tokens are redacted""" - import logging - - with app.app_context(): - app.logger.setLevel(logging.DEBUG) - - with caplog.at_level(logging.DEBUG): - _log_http_response( - status_code=200, - headers={"content-type": "application/json"}, - body='{"access_token": "secret_token_xyz789"}', - ) - - # Should log but with redacted token - assert "secret_token_xyz789" not in caplog.text - assert "secret...********...z789" in caplog.text - - def test_log_http_response_handles_non_json(self, app, caplog): - """Test that non-JSON responses are logged as-is""" - import logging - - with app.app_context(): - app.logger.setLevel(logging.DEBUG) - - with caplog.at_level(logging.DEBUG): - _log_http_response( - status_code=500, headers={}, body="Internal Server Error" - ) - - # Should log the plain text body - assert "Internal Server Error" in caplog.text - - def test_log_http_response_redacts_sensitive_headers(self, app, caplog): - """Test that sensitive headers are redacted""" - import logging - - with app.app_context(): - app.logger.setLevel(logging.DEBUG) - - with caplog.at_level(logging.DEBUG): - _log_http_response( - status_code=200, - headers={ - "content-type": "application/json", - "set-cookie": "sensitive_cookie", - "authorization": "Bearer token", - }, - body='{"me": "https://example.com"}', - ) - - # Should log content-type but not sensitive headers - assert "content-type" in caplog.text - assert "set-cookie" not in caplog.text - assert "authorization" not in caplog.text - assert "sensitive_cookie" not in caplog.text -class TestLoggingIntegration: - @patch("starpunk.auth.discover_endpoints") - def test_initiate_login_logs_at_debug(self, mock_discover, app, db, caplog): - """Test that initiate_login logs at DEBUG level""" - import logging - mock_discover.return_value = { - 'authorization_endpoint': 'https://auth.example.com/authorize', - 'token_endpoint': 'https://auth.example.com/token' - } - with app.app_context(): - app.logger.setLevel(logging.DEBUG) - with caplog.at_level(logging.DEBUG): - me_url = "https://example.com" - initiate_login(me_url) - # Should see DEBUG logs - assert "Validating me URL" in caplog.text - assert "Generated state token" in caplog.text - assert "Building authorization URL" in caplog.text - # Should see INFO log - assert "Authentication initiated" in caplog.text - @patch("starpunk.auth.discover_endpoints") - def test_initiate_login_info_level(self, mock_discover, app, db, caplog): - """Test that initiate_login only shows milestones at INFO level""" - import logging - - mock_discover.return_value = { - 'authorization_endpoint': 'https://auth.example.com/authorize', - 'token_endpoint': 'https://auth.example.com/token' - } - - with app.app_context(): - app.logger.setLevel(logging.INFO) - - with caplog.at_level(logging.INFO): - me_url = "https://example.com" - initiate_login(me_url) - - # Should see INFO milestone - assert "Authentication initiated" in caplog.text - - # Should NOT see DEBUG details - assert "Validating me URL" not in caplog.text - assert "Generated state token" not in caplog.text - - @patch("starpunk.auth.discover_endpoints") - @patch("starpunk.auth.httpx.post") - def test_handle_callback_logs_http_details(self, mock_post, mock_discover, app, db, client, caplog): - """Test that handle_callback logs HTTP request/response at DEBUG""" - import logging - - mock_discover.return_value = { - 'authorization_endpoint': 'https://auth.example.com/authorize', - 'token_endpoint': 'https://auth.example.com/token' - } - - with app.test_request_context(): - app.logger.setLevel(logging.DEBUG) - - # Setup state token - state = secrets.token_urlsafe(32) - expires_at = datetime.utcnow() + timedelta(minutes=5) - db.execute( - "INSERT INTO auth_state (state, expires_at) VALUES (?, ?)", - (state, expires_at), - ) - db.commit() - - # Mock authorization endpoint response - mock_response = MagicMock() - mock_response.status_code = 200 - mock_response.headers = {"content-type": "application/json"} - mock_response.text = '{"me": "https://example.com"}' - mock_response.json.return_value = {"me": "https://example.com"} - mock_post.return_value = mock_response - - with caplog.at_level(logging.DEBUG): - code = "test_authorization_code" - handle_callback(code, state) - - # Should see HTTP request/response logs - assert "IndieAuth HTTP Request" in caplog.text - assert "IndieAuth HTTP Response" in caplog.text - - # Code should be redacted - assert "test_authorization_code" not in caplog.text - assert "test_a...********...code" in caplog.text - - def test_create_session_logs_details(self, app, db, client, caplog): - """Test that create_session logs session details at DEBUG""" - import logging - - with app.test_request_context(): - app.logger.setLevel(logging.DEBUG) - - with caplog.at_level(logging.DEBUG): - me = "https://example.com" - create_session(me) - - # Should see DEBUG logs - assert "Session token generated" in caplog.text - assert "Session expiry" in caplog.text - assert "Request metadata" in caplog.text - - # Should see INFO log - assert "Session created" in caplog.text diff --git a/tests/test_auth_external.py b/tests/test_auth_external.py deleted file mode 100644 index 06a7db2..0000000 --- a/tests/test_auth_external.py +++ /dev/null @@ -1,637 +0,0 @@ -""" -Tests for external IndieAuth token verification with endpoint discovery - -Tests cover: -- Endpoint discovery from HTTP Link headers -- Endpoint discovery from HTML link elements -- Token verification with discovered endpoints -- Caching behavior for endpoints and tokens -- Error handling and edge cases -- HTTPS validation -- URL normalization - -ADR: ADR-031 IndieAuth Endpoint Discovery Implementation -""" - -import hashlib -import time -from unittest.mock import Mock, patch -import pytest -import httpx - -from starpunk.auth_external import ( - verify_external_token, - discover_endpoints, - check_scope, - normalize_url, - _parse_link_header, - _parse_html_links, - _cache, - DiscoveryError, - TokenVerificationError, - ENDPOINT_CACHE_TTL, - TOKEN_CACHE_TTL, -) - - -# Test Fixtures -# ------------- - -@pytest.fixture -def mock_profile_html(): - """HTML profile with IndieAuth link elements""" - return """ - - - - - - Test Profile - - -

Hello World

- - - """ - - -@pytest.fixture -def mock_profile_html_relative(): - """HTML profile with relative URLs""" - return """ - - - - - - - - - """ - - -@pytest.fixture -def mock_link_headers(): - """HTTP Link headers with IndieAuth endpoints""" - return ( - '; rel="authorization_endpoint", ' - '; rel="token_endpoint"' - ) - - -@pytest.fixture -def mock_token_response(): - """Valid token verification response""" - return { - 'me': 'https://alice.example.com/', - 'client_id': 'https://app.example.com/', - 'scope': 'create update', - } - - -@pytest.fixture(autouse=True) -def clear_cache(): - """Clear cache before each test""" - _cache.endpoints = None - _cache.endpoints_expire = 0 - _cache.token_cache.clear() - yield - # Clear after test too - _cache.endpoints = None - _cache.endpoints_expire = 0 - _cache.token_cache.clear() - - -# Endpoint Discovery Tests -# ------------------------- - -def test_parse_link_header_both_endpoints(mock_link_headers): - """Parse Link header with both authorization and token endpoints""" - endpoints = _parse_link_header(mock_link_headers, 'https://alice.example.com/') - - assert endpoints['authorization_endpoint'] == 'https://auth.example.com/authorize' - assert endpoints['token_endpoint'] == 'https://auth.example.com/token' - - -def test_parse_link_header_single_endpoint(): - """Parse Link header with only token endpoint""" - header = '; rel="token_endpoint"' - endpoints = _parse_link_header(header, 'https://alice.example.com/') - - assert endpoints['token_endpoint'] == 'https://auth.example.com/token' - assert 'authorization_endpoint' not in endpoints - - -def test_parse_link_header_relative_url(): - """Parse Link header with relative URL""" - header = '; rel="token_endpoint"' - endpoints = _parse_link_header(header, 'https://alice.example.com/') - - assert endpoints['token_endpoint'] == 'https://alice.example.com/auth/token' - - -def test_parse_html_links_both_endpoints(mock_profile_html): - """Parse HTML with both authorization and token endpoints""" - endpoints = _parse_html_links(mock_profile_html, 'https://alice.example.com/') - - assert endpoints['authorization_endpoint'] == 'https://auth.example.com/authorize' - assert endpoints['token_endpoint'] == 'https://auth.example.com/token' - - -def test_parse_html_links_relative_urls(mock_profile_html_relative): - """Parse HTML with relative endpoint URLs""" - endpoints = _parse_html_links( - mock_profile_html_relative, - 'https://alice.example.com/' - ) - - assert endpoints['authorization_endpoint'] == 'https://alice.example.com/auth/authorize' - assert endpoints['token_endpoint'] == 'https://alice.example.com/auth/token' - - -def test_parse_html_links_empty(): - """Parse HTML with no IndieAuth links""" - html = '' - endpoints = _parse_html_links(html, 'https://alice.example.com/') - - assert endpoints == {} - - -def test_parse_html_links_malformed(): - """Parse malformed HTML gracefully""" - html = ' - - - ''' - endpoints = _parse_html_links(html, 'https://alice.example.com/') - - assert endpoints['authorization_endpoint'] == 'https://auth.example.com/authorize' - - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_from_html(mock_get, app_with_admin_me, mock_profile_html): - """Discover endpoints from HTML link elements""" - mock_response = Mock() - mock_response.status_code = 200 - mock_response.headers = {'Content-Type': 'text/html'} - mock_response.text = mock_profile_html - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - endpoints = discover_endpoints('https://alice.example.com/') - - assert endpoints['token_endpoint'] == 'https://auth.example.com/token' - assert endpoints['authorization_endpoint'] == 'https://auth.example.com/authorize' - - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_from_link_header(mock_get, app_with_admin_me, mock_link_headers): - """Discover endpoints from HTTP Link headers""" - mock_response = Mock() - mock_response.status_code = 200 - mock_response.headers = { - 'Content-Type': 'text/html', - 'Link': mock_link_headers - } - mock_response.text = '' - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - endpoints = discover_endpoints('https://alice.example.com/') - - assert endpoints['token_endpoint'] == 'https://auth.example.com/token' - - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_link_header_priority(mock_get, app_with_admin_me, mock_profile_html, mock_link_headers): - """Link headers take priority over HTML link elements""" - mock_response = Mock() - mock_response.status_code = 200 - mock_response.headers = { - 'Content-Type': 'text/html', - 'Link': '; rel="token_endpoint"' - } - # HTML has different endpoint - mock_response.text = mock_profile_html - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - endpoints = discover_endpoints('https://alice.example.com/') - - # Link header should win - assert endpoints['token_endpoint'] == 'https://different.example.com/token' - - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_no_token_endpoint(mock_get, app_with_admin_me): - """Raise error if no IndieAuth endpoints found""" - mock_response = Mock() - mock_response.status_code = 200 - mock_response.headers = {'Content-Type': 'text/html'} - mock_response.text = '' - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - with pytest.raises(DiscoveryError) as exc_info: - discover_endpoints('https://alice.example.com/') - - assert 'No IndieAuth endpoints found' in str(exc_info.value) - - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_http_error(mock_get, app_with_admin_me): - """Handle HTTP errors during discovery""" - mock_get.side_effect = httpx.HTTPStatusError( - "404 Not Found", - request=Mock(), - response=Mock(status_code=404) - ) - - with app_with_admin_me.app_context(): - with pytest.raises(DiscoveryError) as exc_info: - discover_endpoints('https://alice.example.com/') - - assert 'HTTP 404' in str(exc_info.value) - - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_timeout(mock_get, app_with_admin_me): - """Handle timeout during discovery""" - mock_get.side_effect = httpx.TimeoutException("Timeout") - - with app_with_admin_me.app_context(): - with pytest.raises(DiscoveryError) as exc_info: - discover_endpoints('https://alice.example.com/') - - assert 'Timeout' in str(exc_info.value) - - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_network_error(mock_get, app_with_admin_me): - """Handle network errors during discovery""" - mock_get.side_effect = httpx.NetworkError("Connection failed") - - with app_with_admin_me.app_context(): - with pytest.raises(DiscoveryError) as exc_info: - discover_endpoints('https://alice.example.com/') - - assert 'Network error' in str(exc_info.value) - - -# HTTPS Validation Tests -# ----------------------- - -def test_discover_endpoints_http_not_allowed_production(app_with_admin_me): - """HTTP profile URLs not allowed in production""" - with app_with_admin_me.app_context(): - app_with_admin_me.config['DEBUG'] = False - - with pytest.raises(DiscoveryError) as exc_info: - discover_endpoints('http://alice.example.com/') - - assert 'HTTPS required' in str(exc_info.value) - - -def test_discover_endpoints_http_allowed_debug(app_with_admin_me): - """HTTP profile URLs allowed in debug mode""" - with app_with_admin_me.app_context(): - app_with_admin_me.config['DEBUG'] = True - - # Should validate without raising (mock would be needed for full test) - # Just test validation doesn't raise - from starpunk.auth_external import _validate_profile_url - _validate_profile_url('http://localhost:5000/') - - -def test_discover_endpoints_localhost_not_allowed_production(app_with_admin_me): - """Localhost URLs not allowed in production""" - with app_with_admin_me.app_context(): - app_with_admin_me.config['DEBUG'] = False - - with pytest.raises(DiscoveryError) as exc_info: - discover_endpoints('https://localhost/') - - assert 'Localhost' in str(exc_info.value) - - -# Caching Tests -# ------------- - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_caching(mock_get, app_with_admin_me, mock_profile_html): - """Discovered endpoints are cached""" - mock_response = Mock() - mock_response.status_code = 200 - mock_response.headers = {'Content-Type': 'text/html'} - mock_response.text = mock_profile_html - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - # First call - should fetch - endpoints1 = discover_endpoints('https://alice.example.com/') - - # Second call - should use cache - endpoints2 = discover_endpoints('https://alice.example.com/') - - # Should only call httpx.get once - assert mock_get.call_count == 1 - assert endpoints1 == endpoints2 - - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_cache_expiry(mock_get, app_with_admin_me, mock_profile_html): - """Endpoint cache expires after TTL""" - mock_response = Mock() - mock_response.status_code = 200 - mock_response.headers = {'Content-Type': 'text/html'} - mock_response.text = mock_profile_html - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - # First call - discover_endpoints('https://alice.example.com/') - - # Expire cache manually - _cache.endpoints_expire = time.time() - 1 - - # Second call should fetch again - discover_endpoints('https://alice.example.com/') - - assert mock_get.call_count == 2 - - -@patch('starpunk.auth_external.httpx.get') -def test_discover_endpoints_grace_period(mock_get, app_with_admin_me, mock_profile_html): - """Use expired cache on network failure (grace period)""" - # First call succeeds - mock_response = Mock() - mock_response.status_code = 200 - mock_response.headers = {'Content-Type': 'text/html'} - mock_response.text = mock_profile_html - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - endpoints1 = discover_endpoints('https://alice.example.com/') - - # Expire cache - _cache.endpoints_expire = time.time() - 1 - - # Second call fails, but should use expired cache - mock_get.side_effect = httpx.NetworkError("Connection failed") - - endpoints2 = discover_endpoints('https://alice.example.com/') - - # Should return cached endpoints despite network failure - assert endpoints1 == endpoints2 - - -# Token Verification Tests -# ------------------------- - -@patch('starpunk.auth_external.discover_endpoints') -@patch('starpunk.auth_external.httpx.get') -def test_verify_external_token_success(mock_get, mock_discover, app_with_admin_me, mock_token_response): - """Successfully verify token with discovered endpoint""" - # Mock discovery - mock_discover.return_value = { - 'token_endpoint': 'https://auth.example.com/token' - } - - # Mock token verification - mock_response = Mock() - mock_response.status_code = 200 - mock_response.json.return_value = mock_token_response - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - token_info = verify_external_token('test-token-123') - - assert token_info is not None - assert token_info['me'] == 'https://alice.example.com/' - assert token_info['scope'] == 'create update' - - -@patch('starpunk.auth_external.discover_endpoints') -@patch('starpunk.auth_external.httpx.get') -def test_verify_external_token_wrong_me(mock_get, mock_discover, app_with_admin_me): - """Reject token for different user""" - mock_discover.return_value = { - 'token_endpoint': 'https://auth.example.com/token' - } - - # Token for wrong user - mock_response = Mock() - mock_response.status_code = 200 - mock_response.json.return_value = { - 'me': 'https://bob.example.com/', # Not ADMIN_ME - 'scope': 'create', - } - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - token_info = verify_external_token('test-token-123') - - # Should reject - assert token_info is None - - -@patch('starpunk.auth_external.discover_endpoints') -@patch('starpunk.auth_external.httpx.get') -def test_verify_external_token_401(mock_get, mock_discover, app_with_admin_me): - """Handle 401 Unauthorized from token endpoint""" - mock_discover.return_value = { - 'token_endpoint': 'https://auth.example.com/token' - } - - mock_response = Mock() - mock_response.status_code = 401 - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - token_info = verify_external_token('invalid-token') - - assert token_info is None - - -@patch('starpunk.auth_external.discover_endpoints') -@patch('starpunk.auth_external.httpx.get') -def test_verify_external_token_missing_me(mock_get, mock_discover, app_with_admin_me): - """Reject token response missing 'me' field""" - mock_discover.return_value = { - 'token_endpoint': 'https://auth.example.com/token' - } - - mock_response = Mock() - mock_response.status_code = 200 - mock_response.json.return_value = { - 'scope': 'create', - # Missing 'me' field - } - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - token_info = verify_external_token('test-token') - - assert token_info is None - - -@patch('starpunk.auth_external.discover_endpoints') -@patch('starpunk.auth_external.httpx.get') -def test_verify_external_token_retry_on_500(mock_get, mock_discover, app_with_admin_me, mock_token_response): - """Retry token verification on 500 server error""" - mock_discover.return_value = { - 'token_endpoint': 'https://auth.example.com/token' - } - - # First call: 500 error - error_response = Mock() - error_response.status_code = 500 - - # Second call: success - success_response = Mock() - success_response.status_code = 200 - success_response.json.return_value = mock_token_response - - mock_get.side_effect = [error_response, success_response] - - with app_with_admin_me.app_context(): - with patch('time.sleep'): # Skip sleep delay - token_info = verify_external_token('test-token') - - assert token_info is not None - assert mock_get.call_count == 2 - - -@patch('starpunk.auth_external.discover_endpoints') -@patch('starpunk.auth_external.httpx.get') -def test_verify_external_token_no_retry_on_403(mock_get, mock_discover, app_with_admin_me): - """Don't retry on 403 Forbidden (client error)""" - mock_discover.return_value = { - 'token_endpoint': 'https://auth.example.com/token' - } - - mock_response = Mock() - mock_response.status_code = 403 - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - token_info = verify_external_token('test-token') - - assert token_info is None - # Should only call once (no retries) - assert mock_get.call_count == 1 - - -@patch('starpunk.auth_external.discover_endpoints') -@patch('starpunk.auth_external.httpx.get') -def test_verify_external_token_caching(mock_get, mock_discover, app_with_admin_me, mock_token_response): - """Token verifications are cached""" - mock_discover.return_value = { - 'token_endpoint': 'https://auth.example.com/token' - } - - mock_response = Mock() - mock_response.status_code = 200 - mock_response.json.return_value = mock_token_response - mock_get.return_value = mock_response - - with app_with_admin_me.app_context(): - # First call - token_info1 = verify_external_token('test-token') - - # Second call should use cache - token_info2 = verify_external_token('test-token') - - assert token_info1 == token_info2 - # Should only verify once - assert mock_get.call_count == 1 - - -@patch('starpunk.auth_external.discover_endpoints') -def test_verify_external_token_no_admin_me(mock_discover, app): - """Fail if ADMIN_ME not configured""" - with app.app_context(): - # app fixture has no ADMIN_ME - token_info = verify_external_token('test-token') - - assert token_info is None - # Should not even attempt discovery - mock_discover.assert_not_called() - - -# URL Normalization Tests -# ------------------------ - -def test_normalize_url_removes_trailing_slash(): - """Normalize URL removes trailing slash""" - assert normalize_url('https://example.com/') == 'https://example.com' - assert normalize_url('https://example.com') == 'https://example.com' - - -def test_normalize_url_lowercase(): - """Normalize URL converts to lowercase""" - assert normalize_url('https://Example.COM/') == 'https://example.com' - assert normalize_url('HTTPS://EXAMPLE.COM') == 'https://example.com' - - -def test_normalize_url_path_preserved(): - """Normalize URL preserves path""" - assert normalize_url('https://example.com/path/') == 'https://example.com/path' - assert normalize_url('https://Example.com/Path') == 'https://example.com/path' - - -# Scope Checking Tests -# --------------------- - -def test_check_scope_present(): - """Check scope returns True when scope is present""" - assert check_scope('create', 'create update delete') is True - assert check_scope('create', 'create') is True - - -def test_check_scope_missing(): - """Check scope returns False when scope is missing""" - assert check_scope('create', 'update delete') is False - assert check_scope('create', '') is False - assert check_scope('create', 'created') is False # Partial match - - -def test_check_scope_empty(): - """Check scope handles empty scope string""" - assert check_scope('create', '') is False - assert check_scope('create', None) is False - - -# Fixtures -# -------- - -@pytest.fixture -def app(): - """Create test Flask app without ADMIN_ME""" - from flask import Flask - app = Flask(__name__) - app.config['TESTING'] = True - app.config['DEBUG'] = False - return app - - -@pytest.fixture -def app_with_admin_me(): - """Create test Flask app with ADMIN_ME configured""" - from flask import Flask - app = Flask(__name__) - app.config['TESTING'] = True - app.config['DEBUG'] = False - app.config['ADMIN_ME'] = 'https://alice.example.com/' - app.config['VERSION'] = '1.0.0-test' - return app diff --git a/tests/test_auth_oidc.py b/tests/test_auth_oidc.py new file mode 100644 index 0000000..8183564 --- /dev/null +++ b/tests/test_auth_oidc.py @@ -0,0 +1,243 @@ +""" +Tests for OIDC admin login (starpunk/auth.py, v2.0.0) +""" + +import time +from unittest.mock import MagicMock, patch +from urllib.parse import parse_qs, urlparse + +import jwt +import pytest +from cryptography.hazmat.primitives.asymmetric import rsa + +from starpunk import auth +from starpunk.auth import ( + InvalidStateError, + OIDCError, + UnauthorizedError, + _pkce_challenge, + handle_callback, + initiate_login, + verify_session, +) + +ISSUER = "https://id.example.com" +CLIENT_ID = "starpunk-client" +ADMIN_SUB = "admin-sub-123" + +METADATA = { + "issuer": ISSUER, + "authorization_endpoint": f"{ISSUER}/authorize", + "token_endpoint": f"{ISSUER}/api/oidc/token", + "jwks_uri": f"{ISSUER}/.well-known/jwks.json", + "id_token_signing_alg_values_supported": ["RS256"], +} + +PRIVATE_KEY = rsa.generate_private_key(public_exponent=65537, key_size=2048) +OTHER_KEY = rsa.generate_private_key(public_exponent=65537, key_size=2048) + + +@pytest.fixture +def app(tmp_path): + from starpunk import create_app + + data = tmp_path / "data" + return create_app( + { + "TESTING": True, + "SITE_URL": "https://blog.example.com", + "ADMIN_ME": "https://example.com", + "SESSION_SECRET": "test-secret", + "DATA_PATH": data, + "NOTES_PATH": data / "notes", + "DATABASE_PATH": data / "starpunk.db", + "OIDC_ISSUER": ISSUER, + "OIDC_CLIENT_ID": CLIENT_ID, + "OIDC_CLIENT_SECRET": "secret", + "OIDC_ADMIN_SUB": ADMIN_SUB, + } + ) + + +@pytest.fixture(autouse=True) +def provider(): + """Fake identity provider: discovery, JWKS key and token endpoint""" + auth._METADATA_CACHE.clear() + metadata_response = MagicMock(status_code=200) + metadata_response.json.return_value = METADATA + metadata_response.raise_for_status.return_value = None + with patch("starpunk.auth.httpx.get", return_value=metadata_response) as get, patch( + "starpunk.auth._get_signing_key", return_value=PRIVATE_KEY.public_key() + ), patch("starpunk.auth.httpx.post") as post, patch( + "starpunk.author_discovery.get_author_profile" + ): + yield {"get": get, "post": post} + + +def make_id_token(nonce, sub=ADMIN_SUB, aud=CLIENT_ID, iss=ISSUER, key=PRIVATE_KEY, exp_in=300): + now = int(time.time()) + claims = {"iss": iss, "aud": aud, "sub": sub, "iat": now, "exp": now + exp_in, "nonce": nonce} + return jwt.encode(claims, key, algorithm="RS256") + + +def start_login(app, next_url=None): + """Run initiate_login and return (state, nonce) from the stored row""" + with app.test_request_context(): + url = initiate_login(next_url) + query = parse_qs(urlparse(url).query) + return query["state"][0], query["nonce"][0], query + + +def token_response(provider, id_token, status=200): + response = MagicMock(status_code=status, text="") + response.json.return_value = {"id_token": id_token, "access_token": "x"} + provider["post"].return_value = response + + +class TestInitiateLogin: + def test_redirects_to_provider_with_pkce(self, app): + with app.test_request_context(): + url = initiate_login() + parsed = urlparse(url) + query = parse_qs(parsed.query) + assert f"{parsed.scheme}://{parsed.netloc}{parsed.path}" == METADATA["authorization_endpoint"] + assert query["client_id"] == [CLIENT_ID] + assert query["redirect_uri"] == ["https://blog.example.com/auth/callback"] + assert query["response_type"] == ["code"] + assert query["scope"] == ["openid"] + assert query["code_challenge_method"] == ["S256"] + assert query["state"][0] and query["nonce"][0] + + def test_stores_verifier_matching_challenge(self, app): + state, _, query = start_login(app) + from starpunk.database import get_db + + with app.app_context(): + row = get_db(app).execute( + "SELECT code_verifier FROM oidc_login_state WHERE state = ?", (state,) + ).fetchone() + assert _pkce_challenge(row["code_verifier"]) == query["code_challenge"][0] + + def test_rejects_offsite_next_url(self, app): + state, _, _ = start_login(app, "https://evil.example/steal") + from starpunk.database import get_db + + with app.app_context(): + row = get_db(app).execute( + "SELECT next_url FROM oidc_login_state WHERE state = ?", (state,) + ).fetchone() + assert row["next_url"] is None + + def test_issuer_mismatch_fails(self, app, provider): + provider["get"].return_value.json.return_value = {**METADATA, "issuer": "https://other"} + with app.test_request_context(), pytest.raises(OIDCError): + initiate_login() + + +class TestHandleCallback: + def test_success_creates_admin_session(self, app, provider): + state, nonce, _ = start_login(app, "/admin/new") + token_response(provider, make_id_token(nonce)) + + with app.test_request_context(): + session_token, next_url = handle_callback("code", state, ISSUER) + assert verify_session(session_token)["me"] == "https://example.com" + assert next_url == "/admin/new" + + sent = provider["post"].call_args + assert sent.kwargs["data"]["grant_type"] == "authorization_code" + assert sent.kwargs["data"]["code_verifier"] + assert sent.kwargs["auth"] == (CLIENT_ID, "secret") + + def test_state_is_single_use(self, app, provider): + state, nonce, _ = start_login(app) + token_response(provider, make_id_token(nonce)) + with app.test_request_context(): + handle_callback("code", state) + with pytest.raises(InvalidStateError): + handle_callback("code", state) + + def test_unknown_state(self, app): + with app.test_request_context(), pytest.raises(InvalidStateError): + handle_callback("code", "nope") + + def test_wrong_subject_is_unauthorized(self, app, provider): + state, nonce, _ = start_login(app) + token_response(provider, make_id_token(nonce, sub="someone-else")) + with app.test_request_context(), pytest.raises(UnauthorizedError): + handle_callback("code", state) + + @pytest.mark.parametrize( + "kwargs", + [ + {"aud": "another-client"}, + {"iss": "https://evil.example"}, + {"key": OTHER_KEY}, + {"exp_in": -3600}, + ], + ) + def test_invalid_id_token_rejected(self, app, provider, kwargs): + state, nonce, _ = start_login(app) + token_response(provider, make_id_token(nonce, **kwargs)) + with app.test_request_context(), pytest.raises(OIDCError): + handle_callback("code", state) + + def test_nonce_mismatch_rejected(self, app, provider): + state, _, _ = start_login(app) + token_response(provider, make_id_token("wrong-nonce")) + with app.test_request_context(), pytest.raises(OIDCError): + handle_callback("code", state) + + def test_callback_issuer_mismatch_rejected(self, app, provider): + state, nonce, _ = start_login(app) + token_response(provider, make_id_token(nonce)) + with app.test_request_context(), pytest.raises(OIDCError): + handle_callback("code", state, "https://evil.example") + + def test_token_endpoint_error(self, app, provider): + state, _, _ = start_login(app) + token_response(provider, None, status=400) + with app.test_request_context(), pytest.raises(OIDCError): + handle_callback("code", state) + + +class TestRoutes: + def test_login_page_shows_sso_button(self, app): + response = app.test_client().get("/auth/login") + assert response.status_code == 200 + assert b"Sign in with" in response.data + assert b'name="me"' not in response.data + + def test_login_post_redirects_to_provider(self, app): + response = app.test_client().post("/auth/login") + assert response.status_code == 302 + assert response.headers["Location"].startswith(METADATA["authorization_endpoint"]) + + def test_callback_sets_cookie_and_returns_to_next(self, app, provider): + client = app.test_client() + with client.session_transaction() as s: + s["next"] = "https://blog.example.com/admin/tokens" + login = client.post("/auth/login") + query = parse_qs(urlparse(login.headers["Location"]).query) + token_response(provider, make_id_token(query["nonce"][0])) + + response = client.get(f"/auth/callback?code=abc&state={query['state'][0]}&iss={ISSUER}") + assert response.status_code == 302 + assert response.headers["Location"] == "https://blog.example.com/admin/tokens" + cookie = response.headers["Set-Cookie"] + assert "starpunk_session=" in cookie and "HttpOnly" in cookie and "Secure" in cookie + + def test_callback_wrong_user_gets_no_cookie(self, app, provider): + client = app.test_client() + login = client.post("/auth/login") + query = parse_qs(urlparse(login.headers["Location"]).query) + token_response(provider, make_id_token(query["nonce"][0], sub="intruder")) + + response = client.get(f"/auth/callback?code=abc&state={query['state'][0]}") + assert response.headers["Location"].endswith("/auth/login") + assert "starpunk_session" not in response.headers.get("Set-Cookie", "") + + def test_callback_provider_error(self, app): + response = app.test_client().get("/auth/callback?error=access_denied") + assert response.status_code == 302 + assert response.headers["Location"].endswith("/auth/login") diff --git a/tests/test_indieauth.py b/tests/test_indieauth.py new file mode 100644 index 0000000..5835809 --- /dev/null +++ b/tests/test_indieauth.py @@ -0,0 +1,329 @@ +""" +Tests for the built-in IndieAuth server (starpunk/indieauth.py, v2.0.0) +""" + +import base64 +import hashlib +import secrets +from unittest.mock import MagicMock, patch +from urllib.parse import parse_qs, urlencode, urlparse + +import pytest + +from starpunk.auth import create_session +from starpunk.indieauth import ( + AuthorizationRequestError, + InvalidGrantError, + check_scope, + create_access_token, + create_authorization_code, + fetch_client_redirect_uris, + redeem_authorization_code, + validate_authorization_request, + verify_access_token, +) + +CLIENT_ID = "https://quill.example/" +REDIRECT_URI = "https://quill.example/auth/callback" + + +def challenge_for(verifier): + digest = hashlib.sha256(verifier.encode()).digest() + return base64.urlsafe_b64encode(digest).rstrip(b"=").decode() + + +@pytest.fixture +def app(tmp_path): + from starpunk import create_app + + data = tmp_path / "data" + return create_app( + { + "TESTING": True, + "SITE_URL": "https://blog.example.com", + "ADMIN_ME": "https://example.com", + "SESSION_SECRET": "test-secret", + "DATA_PATH": data, + "NOTES_PATH": data / "notes", + "DATABASE_PATH": data / "starpunk.db", + } + ) + + +@pytest.fixture +def client(app): + return app.test_client() + + +@pytest.fixture +def admin_client(app): + """Test client with a valid admin session cookie""" + client = app.test_client() + with app.test_request_context(): + token = create_session("https://example.com") + client.set_cookie("starpunk_session", token) + return client + + +def auth_params(verifier="v" * 50, **overrides): + params = { + "response_type": "code", + "client_id": CLIENT_ID, + "redirect_uri": REDIRECT_URI, + "state": "client-state", + "code_challenge": challenge_for(verifier), + "code_challenge_method": "S256", + "scope": "create media", + } + params.update(overrides) + return params + + +def approve(admin_client, granted=("create", "media"), **overrides): + form = auth_params(**overrides) + form["decision"] = "approve" + form["scope_granted"] = list(granted) + response = admin_client.post("/auth/authorize/approve", data=form) + assert response.status_code == 302 + return parse_qs(urlparse(response.headers["Location"]).query) + + +class TestValidation: + def test_valid_request(self, app): + with app.test_request_context(): + result = validate_authorization_request(auth_params()) + assert result["scopes"] == ["create", "media"] + + @pytest.mark.parametrize( + "overrides", + [{"client_id": "not-a-url"}, {"redirect_uri": ""}, {"client_id": "ftp://x.example/"}], + ) + def test_untrusted_client_errors_are_not_redirected(self, app, overrides): + with app.test_request_context(), pytest.raises(AuthorizationRequestError) as e: + validate_authorization_request(auth_params(**overrides)) + assert e.value.redirectable is False + + def test_missing_pkce_is_redirectable_error(self, app): + with app.test_request_context(), pytest.raises(AuthorizationRequestError) as e: + validate_authorization_request(auth_params(code_challenge="")) + assert e.value.redirectable is True + + def test_plain_pkce_rejected(self, app): + with app.test_request_context(), pytest.raises(AuthorizationRequestError): + validate_authorization_request(auth_params(code_challenge_method="plain")) + + def test_cross_origin_redirect_needs_client_registration(self, app): + params = auth_params(redirect_uri="https://evil.example/cb") + with app.test_request_context(), patch( + "starpunk.indieauth.fetch_client_redirect_uris", return_value=[] + ), pytest.raises(AuthorizationRequestError) as e: + validate_authorization_request(params) + assert e.value.redirectable is False + + def test_cross_origin_redirect_allowed_when_published(self, app): + params = auth_params(redirect_uri="app://callback") + with app.test_request_context(), patch( + "starpunk.indieauth.fetch_client_redirect_uris", return_value=["app://callback"] + ): + assert validate_authorization_request(params)["redirect_uri"] == "app://callback" + + +class TestClientMetadata: + def _response(self, content_type, body, links=None): + response = MagicMock(status_code=200, text=body, url="https://quill.example/") + response.headers = {"Content-Type": content_type} + response.links = links or {} + response.json.return_value = __import__("json").loads(body) if "json" in content_type else None + return response + + def test_json_metadata(self, app): + body = '{"client_id": "https://quill.example/", "redirect_uris": ["app://cb"]}' + with app.test_request_context(), patch( + "starpunk.webmention_ssrf.validate_url_for_fetch" + ), patch("starpunk.indieauth.httpx.get", return_value=self._response("application/json", body)): + assert fetch_client_redirect_uris(CLIENT_ID) == ["app://cb"] + + def test_html_link(self, app): + body = '' + with app.test_request_context(), patch( + "starpunk.webmention_ssrf.validate_url_for_fetch" + ), patch("starpunk.indieauth.httpx.get", return_value=self._response("text/html", body)): + assert fetch_client_redirect_uris(CLIENT_ID) == ["https://quill.example/cb"] + + +class TestCodesAndTokens: + def test_full_exchange(self, app): + verifier = secrets.token_urlsafe(50) + with app.test_request_context(): + code = create_authorization_code(CLIENT_ID, REDIRECT_URI, "create", challenge_for(verifier)) + result = redeem_authorization_code(code, CLIENT_ID, REDIRECT_URI, verifier) + assert result == {"me": "https://example.com", "scope": "create", "client_id": CLIENT_ID} + + token = create_access_token(CLIENT_ID, "create") + info = verify_access_token(token["access_token"]) + assert info["me"] == "https://example.com" + assert info["scope"] == "create" + + def test_code_single_use(self, app): + verifier = "v" * 50 + with app.test_request_context(): + code = create_authorization_code(CLIENT_ID, REDIRECT_URI, "create", challenge_for(verifier)) + redeem_authorization_code(code, CLIENT_ID, REDIRECT_URI, verifier) + with pytest.raises(InvalidGrantError): + redeem_authorization_code(code, CLIENT_ID, REDIRECT_URI, verifier) + + @pytest.mark.parametrize( + "client_id,redirect_uri,verifier", + [ + ("https://other.example/", REDIRECT_URI, "v" * 50), + (CLIENT_ID, "https://quill.example/other", "v" * 50), + (CLIENT_ID, REDIRECT_URI, "wrong-verifier"), + ], + ) + def test_code_mismatch_rejected(self, app, client_id, redirect_uri, verifier): + with app.test_request_context(): + code = create_authorization_code(CLIENT_ID, REDIRECT_URI, "create", challenge_for("v" * 50)) + with pytest.raises(InvalidGrantError): + redeem_authorization_code(code, client_id, redirect_uri, verifier) + + def test_token_stored_hashed(self, app): + from starpunk.database import get_db + + with app.test_request_context(): + token = create_access_token(CLIENT_ID, "create")["access_token"] + rows = get_db(app).execute("SELECT token_hash FROM indieauth_tokens").fetchall() + assert token not in [r["token_hash"] for r in rows] + + def test_unknown_token(self, app): + with app.test_request_context(): + assert verify_access_token("nope") is None + assert verify_access_token("") is None + + def test_check_scope(self): + assert check_scope("create", "create media") + assert not check_scope("create", "media") + assert not check_scope("create", "") + + +class TestEndpoints: + def test_metadata(self, client): + data = client.get("/.well-known/oauth-authorization-server").get_json() + assert data["issuer"] == "https://blog.example.com/" + assert data["authorization_endpoint"] == "https://blog.example.com/auth/authorize" + assert data["token_endpoint"] == "https://blog.example.com/auth/token" + assert data["code_challenge_methods_supported"] == ["S256"] + + def test_discovery_links_on_homepage(self, client): + html = client.get("/").data.decode() + assert 'rel="indieauth-metadata"' in html + assert 'rel="micropub"' in html + + def test_authorize_requires_login(self, client): + response = client.get("/auth/authorize?" + urlencode(auth_params())) + assert response.status_code == 302 + assert response.headers["Location"].endswith("/auth/login") + with client.session_transaction() as s: + assert "/auth/authorize?" in s["next"] + + def test_authorize_shows_consent(self, admin_client): + response = admin_client.get("/auth/authorize?" + urlencode(auth_params())) + assert response.status_code == 200 + assert b"quill.example" in response.data + assert b'value="create"' in response.data + + def test_authorize_bad_client_shows_error_page(self, admin_client): + response = admin_client.get("/auth/authorize?" + urlencode(auth_params(client_id="nope"))) + assert response.status_code == 400 + + def test_approve_requires_login(self, client): + response = client.post("/auth/authorize/approve", data={**auth_params(), "decision": "approve"}) + assert response.headers["Location"].endswith("/auth/login") + + def test_deny(self, admin_client): + form = {**auth_params(), "decision": "deny"} + query = parse_qs(urlparse(admin_client.post("/auth/authorize/approve", data=form).headers["Location"]).query) + assert query["error"] == ["access_denied"] + assert query["state"] == ["client-state"] + + def test_full_micropub_flow(self, admin_client, client): + verifier = "v" * 50 + query = approve(admin_client, granted=["create"]) + assert query["state"] == ["client-state"] + assert query["iss"] == ["https://blog.example.com/"] + + response = client.post( + "/auth/token", + data={ + "grant_type": "authorization_code", + "code": query["code"][0], + "client_id": CLIENT_ID, + "redirect_uri": REDIRECT_URI, + "code_verifier": verifier, + }, + ) + assert response.status_code == 200 + assert response.headers["Cache-Control"] == "no-store" + body = response.get_json() + assert body["me"] == "https://example.com" + assert body["scope"] == "create" # media was unchecked + + token = body["access_token"] + micropub = client.post( + "/micropub", + data={"h": "entry", "content": "Posted through the built-in IndieAuth server"}, + headers={"Authorization": f"Bearer {token}"}, + ) + assert micropub.status_code == 201 + + verify = client.get("/auth/token", headers={"Authorization": f"Bearer {token}"}) + assert verify.get_json()["client_id"] == CLIENT_ID + + client.post("/auth/revoke", data={"token": token}) + again = client.post( + "/micropub", + data={"h": "entry", "content": "should fail"}, + headers={"Authorization": f"Bearer {token}"}, + ) + assert again.status_code == 401 + + def test_profile_only_code_cannot_get_token(self, admin_client, client): + query = approve(admin_client, granted=[], scope="") + form = { + "grant_type": "authorization_code", + "code": query["code"][0], + "client_id": CLIENT_ID, + "redirect_uri": REDIRECT_URI, + "code_verifier": "v" * 50, + } + assert client.post("/auth/token", data=form).get_json()["error"] == "invalid_grant" + + def test_profile_only_redemption(self, admin_client, client): + query = approve(admin_client, granted=[], scope="") + response = client.post( + "/auth/authorize", + data={ + "grant_type": "authorization_code", + "code": query["code"][0], + "client_id": CLIENT_ID, + "redirect_uri": REDIRECT_URI, + "code_verifier": "v" * 50, + }, + ) + assert response.get_json() == {"me": "https://example.com"} + + def test_unsupported_grant(self, client): + assert client.post("/auth/token", data={"grant_type": "password"}).status_code == 400 + + def test_admin_can_list_and_revoke(self, app, admin_client): + with app.test_request_context(): + token = create_access_token(CLIENT_ID, "create")["access_token"] + page = admin_client.get("/admin/tokens") + assert page.status_code == 200 and b"quill.example" in page.data + + from starpunk.database import get_db + + with app.app_context(): + token_id = get_db(app).execute("SELECT id FROM indieauth_tokens").fetchone()["id"] + admin_client.post(f"/admin/tokens/{token_id}/revoke") + with app.test_request_context(): + assert verify_access_token(token) is None diff --git a/tests/test_micropub.py b/tests/test_micropub.py index 7cf482c..2482b8b 100644 --- a/tests/test_micropub.py +++ b/tests/test_micropub.py @@ -69,7 +69,7 @@ def test_micropub_no_token(client): def test_micropub_invalid_token(client, mock_invalid_token): """Test Micropub endpoint rejects invalid tokens""" - with patch('starpunk.routes.micropub.verify_external_token', mock_invalid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_invalid_token): response = client.post( '/micropub', data={'h': 'entry', 'content': 'Test post'}, @@ -84,7 +84,7 @@ def test_micropub_invalid_token(client, mock_invalid_token): def test_micropub_insufficient_scope(client, mock_read_only_token): """Test Micropub endpoint rejects token without create scope""" - with patch('starpunk.routes.micropub.verify_external_token', mock_read_only_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_read_only_token): response = client.post( '/micropub', data={'h': 'entry', 'content': 'Test post'}, @@ -101,7 +101,7 @@ def test_micropub_insufficient_scope(client, mock_read_only_token): def test_micropub_create_note_form(client, app, mock_valid_token): """Test creating a note via form-encoded request""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): response = client.post( '/micropub', data={ @@ -126,7 +126,7 @@ def test_micropub_create_note_form(client, app, mock_valid_token): def test_micropub_create_note_json(client, app, mock_valid_token): """Test creating a note via JSON request""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): response = client.post( '/micropub', json={ @@ -150,7 +150,7 @@ def test_micropub_create_note_json(client, app, mock_valid_token): def test_micropub_create_with_name(client, app, mock_valid_token): """Test creating a note with a title (name property)""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): response = client.post( '/micropub', json={ @@ -170,7 +170,7 @@ def test_micropub_create_with_name(client, app, mock_valid_token): def test_micropub_create_with_categories(client, app, mock_valid_token): """Test creating a note with tags (category property)""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): response = client.post( '/micropub', json={ @@ -190,7 +190,7 @@ def test_micropub_create_with_categories(client, app, mock_valid_token): def test_micropub_create_with_custom_slug_form(client, app, mock_valid_token): """Test creating a note with custom slug via form-encoded request""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): response = client.post( '/micropub', data={ @@ -218,7 +218,7 @@ def test_micropub_create_with_custom_slug_form(client, app, mock_valid_token): def test_micropub_create_with_custom_slug_json(client, app, mock_valid_token): """Test creating a note with custom slug via JSON request""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): response = client.post( '/micropub', json={ @@ -251,7 +251,7 @@ def test_micropub_create_with_custom_slug_json(client, app, mock_valid_token): def test_micropub_query_config(client, mock_valid_token): """Test q=config endpoint""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): response = client.get( '/micropub?q=config', headers={'Authorization': 'Bearer valid_token'} @@ -266,7 +266,7 @@ def test_micropub_query_config(client, mock_valid_token): def test_micropub_query_source(client, mock_valid_token): """Test q=source endpoint""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): # First create a note create_response = client.post( '/micropub', @@ -297,7 +297,7 @@ def test_micropub_query_source(client, mock_valid_token): def test_micropub_missing_content(client, mock_valid_token): """Test creating note without content fails""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): response = client.post( '/micropub', json={ @@ -314,7 +314,7 @@ def test_micropub_missing_content(client, mock_valid_token): def test_micropub_unsupported_action(client, mock_valid_token): """Test unsupported actions (update, delete) return error""" - with patch('starpunk.routes.micropub.verify_external_token', mock_valid_token): + with patch('starpunk.routes.micropub.verify_access_token', mock_valid_token): # Test update response = client.post( '/micropub', diff --git a/tests/test_templates.py b/tests/test_templates.py index 519495a..bb96183 100644 --- a/tests/test_templates.py +++ b/tests/test_templates.py @@ -212,11 +212,12 @@ class TestAdminTemplates: assert response.status_code == 200 assert b"