Compare commits

..
8 Commits
Author SHA1 Message Date
PhilandClaude Opus 5.5 94e8c672df release: v2.0.2 (CI registry login)
Build Container / build (push) Successful in 18s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 12:20:01 -06:00
PhilandClaude Opus 5.5 011f7cc87d ci: Log in to the registry with a write:package token
The automatic Actions token is refused by the container registry
(run 107: unauthorized). Use the REGISTRY_TOKEN repository secret.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 12:13:43 -06:00
PhilandClaude Opus 5.5 f46130569f Merge branch 'fix/v2.0.1-ci-and-feed-urls' for v2.0.1 release
Build Container / build (push) Failing after 12s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 12:12:29 -06:00
PhilandClaude Opus 5.5 b4e6cf3cc3 fix: Build absolute URLs from SITE_URL, not the request (v2.0.1)
Behind Caddy the app is reached over plain HTTP, so url_for(_external=True)
produced http:// links on the https site: the RSS/OPML <link>s and the
microformats u-url/u-uid permalinks that IndieWeb parsers treat as
canonical. Templates now use absolute_url_for(), shared with the
IndieAuth metadata.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 12:12:28 -06:00
PhilandClaude Opus 5.5 2d0568d9c2 Build the container image with the server's rootless BuildKit
The runner no longer has a Docker daemon (it gave every workflow root on
the server), and this workflow never worked anyway: it logged in to
gitea:3000, which the daemon couldn't resolve. Log in to
git.thesatelliteoflove.com and build through the BuildKit socket instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 11:53:59 -06:00
PhilandClaude Opus 5.5 f117913797 Merge branch 'feature/v2.0.0-oidc' for v2.0.0 release
Build Container / build (push) Failing after 2m38s
Includes the v1.6.0-rc.2 source recovered from production.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 11:45:20 -06:00
PhilandClaude Opus 5.5 b84cf23e1a 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 <noreply@anthropic.com>
2026-10-31 11:38:27 -06:00
PhilandClaude Opus 5.5 d3fa5b7a2a 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 <noreply@anthropic.com>
2026-10-31 11:17:51 -06:00
52 changed files with 5911 additions and 2477 deletions

No files matched your search

+18 -5
View File
@@ -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: <SITE_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
+26 -42
View File
@@ -1,58 +1,42 @@
# Gitea Actions workflow for StarPunk
# Builds and pushes container images on version tags
# Builds and pushes container images on version tags.
#
# The runner has no Docker daemon (that would give workflows root on the
# server). Images are built by the rootless BuildKit container next to it,
# reached through its socket.
name: Build Container
on:
# Trigger on version tags
push:
tags:
- 'v[0-9]+.[0-9]+.[0-9]+'
# Allow manual trigger from Gitea UI
workflow_dispatch:
env:
REGISTRY: git.thesatelliteoflove.com
BUILDKIT: unix:///run/buildkit/buildkit/buildkitd.sock
jobs:
build:
runs-on: docker
steps:
- name: Install dependencies
run: |
if command -v apk > /dev/null; then
apk add --no-cache nodejs npm docker git
elif command -v apt-get > /dev/null; then
apt-get update && apt-get install -y nodejs npm docker.io git
elif command -v yum > /dev/null; then
yum install -y nodejs npm docker git
fi
run: apk add --no-cache nodejs git docker-cli docker-cli-buildx
- name: Checkout
uses: actions/checkout@v4
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Extract registry URL
id: registry
run: |
# Extract hostname from server URL (remove protocol)
REGISTRY_URL=$(echo "${{ github.server_url }}" | sed 's|https://||' | sed 's|http://||')
echo "url=${REGISTRY_URL}" >> $GITHUB_OUTPUT
- name: Login to Gitea Container Registry
uses: docker/login-action@v3
with:
registry: ${{ steps.registry.outputs.url }}
username: ${{ github.actor }}
password: ${{ secrets.GITHUB_TOKEN }}
# The automatic Actions token can't log in to the container registry, so
# this uses a personal access token with only the write:package scope,
# stored as the repository secret REGISTRY_TOKEN.
- name: Log in to the Gitea registry
run: echo "${{ secrets.REGISTRY_TOKEN }}" | docker login "$REGISTRY" -u "${{ github.repository_owner }}" --password-stdin
- name: Use the BuildKit socket
run: docker buildx create --name ci --driver remote "$BUILDKIT" --use
- name: Build and push
uses: docker/build-push-action@v5
with:
context: .
file: ./Containerfile
push: true
tags: |
${{ steps.registry.outputs.url }}/${{ github.repository }}:${{ github.ref_name }}
${{ steps.registry.outputs.url }}/${{ github.repository }}:latest
cache-from: type=gha
cache-to: type=gha,mode=max
run: |
image="$REGISTRY/$(echo '${{ github.repository }}' | tr '[:upper:]' '[:lower:]')"
docker buildx build --push -f Containerfile \
-t "$image:${{ github.ref_name }}" -t "$image:latest" .
- name: Clean up
if: always()
run: |
docker buildx rm ci || true
docker logout "$REGISTRY" || true
+48
View File
@@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
## [2.0.2] - 2026-10-31
### Fixed
- Container builds in Gitea Actions log in to the registry with the
`REGISTRY_TOKEN` secret (a `write:package` token); the automatic Actions
token is refused by the registry. No application changes.
## [2.0.1] - 2026-10-31
### Fixed
- Page links built from the request said `http://` behind an HTTPS reverse proxy
(RSS/OPML `<link>`s and microformats `u-url`/`u-uid` permalinks). All absolute
URLs in templates now come from `SITE_URL` via `absolute_url_for()`.
- Container builds in Gitea Actions: build through the server's rootless BuildKit
and log in to the public registry name (the old workflow never succeeded).
## [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
+6 -4
View File
@@ -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: `<SITE_URL>/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
@@ -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.
@@ -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.
+79
View File
@@ -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);
@@ -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);
+4
View File
@@ -36,3 +36,7 @@ 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.*
PyJWT[crypto]==2.10.*
+112 -4
View File
@@ -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
@@ -187,6 +191,10 @@ def create_app(config=None):
register_routes(app)
# Template context processor - Inject author profile (v1.2.0 Phase 2)
from starpunk.utils import absolute_url_for
app.jinja_env.globals["absolute_url_for"] = absolute_url_for
@app.context_processor
def inject_author():
"""
@@ -211,12 +219,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'] = '</webmention>; rel="webmention"'
return response
# Register centralized error handlers
from starpunk.errors import register_error_handlers
@@ -237,6 +310,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 +421,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__ = "2.0.2"
__version_info__ = (2, 0, 2)
+233 -395
View File
@@ -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)
-614
View File
@@ -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: <https://auth.example.com/token>; rel="token_endpoint"
Args:
header: Link header value
base_url: Base URL for resolving relative URLs
Returns:
Dict with discovered endpoints
"""
endpoints = {}
# Pattern: <url>; 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:
<link rel="authorization_endpoint" href="...">
<link rel="token_endpoint" href="...">
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
+38 -17
View File
@@ -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"]:
@@ -110,6 +109,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)
@@ -231,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([
+342
View File
@@ -0,0 +1,342 @@
"""
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
from starpunk.utils import absolute_url_for
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 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]
+141 -56
View File
@@ -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 {
+1 -1
View File
@@ -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
+2
View File
@@ -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
+134 -11
View File
@@ -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
+210
View File
@@ -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()
+329
View File
@@ -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
+6 -1
View File
@@ -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, 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)
@@ -39,6 +40,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(
+242 -4
View File
@@ -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,204 @@ 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/<int:id>")
@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/<int:id>/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"))
# 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/<int:token_id>/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"))
+49 -112
View File
@@ -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
+228
View File
@@ -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,
validate_authorization_request,
verify_access_token,
)
from starpunk.micropub import extract_bearer_token
from starpunk.utils import absolute_url_for
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": absolute_url_for("indieauth.authorize"),
"token_endpoint": absolute_url_for("indieauth.token"),
"revocation_endpoint": absolute_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({})
+4 -3
View File
@@ -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)
+35 -1
View File
@@ -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/<tag>")
+272
View File
@@ -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
+12
View File
@@ -681,3 +681,15 @@ def parse_iso8601(date_string: str) -> datetime:
# Parse using fromisoformat
return datetime.fromisoformat(date_string)
def absolute_url_for(endpoint: str, **values) -> str:
"""
Absolute URL for an endpoint, built from SITE_URL
Use instead of url_for(..., _external=True): behind a reverse proxy the
request arrives over plain HTTP, so _external URLs would say http://.
"""
from flask import current_app, url_for
return current_app.config["SITE_URL"].rstrip("/") + url_for(endpoint, **values)
+373
View File
@@ -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
}
+295
View File
@@ -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
+198
View File
@@ -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 <a href> elements, exclude <pre> and <code> 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 <a href> elements only
- Exclude links in <pre> and <code> blocks
- Return in document order
Args:
html_content: Rendered HTML content
exclude_code_blocks: If True, skip links in <pre> and <code> (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 <pre> and <code> elements before extracting links
for element in doc.xpath('//pre | //code'):
element.getparent().remove(element)
# Extract all <a href> 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
+113
View File
@@ -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)
+787
View File
@@ -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 → <link rel="webmention"> → <a rel="webmention">
- 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 <link> and <a> 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: <URL>; 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 <link> or <a> 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 <link rel="webmention"> first
links = doc.xpath('//link[@rel="webmention"]/@href')
if links:
from urllib.parse import urljoin
return urljoin(base_url, links[0])
# Check <a rel="webmention">
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)
}
+262
View File
@@ -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;
}
+43
View File
@@ -0,0 +1,43 @@
{% extends "base.html" %}
{% block title %}Authorize App - StarPunk{% endblock %}
{% block content %}
<div class="login-container authorize">
{% if request_error %}
<h2>Cannot authorize this app</h2>
<p>{{ request_error }}</p>
<p><a href="/">Return to homepage</a></p>
{% else %}
<h2>Authorize app</h2>
<p>
<strong>{{ auth_request.client_id }}</strong> wants to sign in as
<strong>{{ me }}</strong>.
</p>
<p><small>After approval you will be sent to {{ auth_request.redirect_uri }}</small></p>
<form action="{{ url_for('indieauth.approve') }}" method="POST" class="login-form">
{% for name, value in fields.items() %}
<input type="hidden" name="{{ name }}" value="{{ value }}">
{% endfor %}
{% if auth_request.scopes %}
<fieldset>
<legend>Permissions requested</legend>
{% for scope in auth_request.scopes %}
<label>
<input type="checkbox" name="scope_granted" value="{{ scope }}" checked>
{{ scope }}
</label><br>
{% endfor %}
</fieldset>
{% else %}
<p>This app only wants to confirm your identity. It cannot post.</p>
{% endif %}
<button type="submit" name="decision" value="approve" class="button button-primary">Approve</button>
<button type="submit" name="decision" value="deny" class="button button-secondary">Deny</button>
</form>
{% endif %}
</div>
{% endblock %}
+1
View File
@@ -6,6 +6,7 @@
<a href="{{ url_for('admin.dashboard') }}">Dashboard</a>
<a href="{{ url_for('admin.new_note_form') }}">New Note</a>
<a href="{{ url_for('admin.metrics_dashboard') }}">Metrics</a>
<a href="{{ url_for('admin.tokens') }}">Connected Apps</a>
<form action="{{ url_for('auth.logout') }}" method="POST" class="logout-form">
<button type="submit" class="button button-secondary">Logout</button>
</form>
+22
View File
@@ -10,6 +10,14 @@
<a href="{{ url_for('admin.new_note_form') }}" class="button button-primary">
+ New Note
</a>
{% if config.WEBMENTION_ENABLED %}
<a href="{{ url_for('admin.webmentions') }}" class="button">
Webmentions
{% if webmention_pending_count > 0 %}
<span class="badge">{{ webmention_pending_count }}</span>
{% endif %}
</a>
{% endif %}
</div>
{% if notes %}
@@ -59,6 +67,20 @@
{% endfor %}
</tbody>
</table>
{# Pagination (v1.6.0) #}
{% if total_pages > 1 %}
<nav class="pagination">
{% if page > 1 %}
<a href="?page={{ page - 1 }}" class="button">Previous</a>
{% endif %}
<span>Page {{ page }} of {{ total_pages }}</span>
{% if page < total_pages %}
<a href="?page={{ page + 1 }}" class="button">Next</a>
{% endif %}
</nav>
{% endif %}
{% else %}
<div class="empty-state">
<p>No notes yet. Create your first note!</p>
+2 -26
View File
@@ -5,23 +5,10 @@
{% block content %}
<div class="login-container">
<h2>Admin Login</h2>
<p>Sign in with your personal website using IndieLogin</p>
<p>Sign in with {{ config.OIDC_PROVIDER_NAME }} to manage this site.</p>
<form action="{{ url_for('auth.login_initiate') }}" method="POST" class="login-form">
<div class="form-group">
<label for="me">Your Website URL</label>
<input
type="url"
id="me"
name="me"
placeholder="https://example.com"
required
autofocus
>
<small>Enter your website URL (must match admin configuration)</small>
</div>
<button type="submit" class="button button-primary">Sign in with IndieLogin</button>
<button type="submit" class="button button-primary">Sign in with {{ config.OIDC_PROVIDER_NAME }}</button>
</form>
{% if config.DEV_MODE %}
@@ -33,16 +20,5 @@
</a>
</div>
{% endif %}
<div class="login-help">
<h3>What is IndieLogin?</h3>
<p>
IndieLogin allows you to sign in using your own website.
No password required - just authenticate with your domain.
</p>
<a href="https://indielogin.com/api" target="_blank" rel="noopener">
Learn more about IndieLogin
</a>
</div>
</div>
{% endblock %}
+44
View File
@@ -0,0 +1,44 @@
{% extends "admin/base.html" %}
{% block title %}Connected Apps - StarPunk Admin{% endblock %}
{% block admin_content %}
<div class="tokens-admin">
<h2>Connected Apps</h2>
<p>Micropub apps you have approved. Revoke any you no longer use.</p>
{% if tokens %}
<table class="note-table">
<thead>
<tr>
<th>App</th>
<th>Scope</th>
<th>Approved</th>
<th>Last used</th>
<th>Expires</th>
<th></th>
</tr>
</thead>
<tbody>
{% for t in tokens %}
<tr>
<td>{{ t.client_id }}</td>
<td>{{ t.scope }}</td>
<td>{{ t.created_at }}</td>
<td>{{ t.last_used_at or "never" }}</td>
<td>{{ t.expires_at }}</td>
<td>
<form method="POST" action="{{ url_for('admin.revoke_token', token_id=t.id) }}">
<button type="submit" class="button button-danger"
onclick="return confirm('Revoke this app\'s access?')">Revoke</button>
</form>
</td>
</tr>
{% endfor %}
</tbody>
</table>
{% else %}
<p>No apps connected.</p>
{% endif %}
</div>
{% endblock %}
+108
View File
@@ -0,0 +1,108 @@
{% extends "admin/base.html" %}
{% block title %}Webmention Detail - StarPunk Admin{% endblock %}
{% block admin_content %}
<div class="webmention-detail">
<h2>Webmention Detail</h2>
<div class="dashboard-actions">
<a href="{{ url_for('admin.webmentions') }}" class="button">
Back to Webmentions
</a>
</div>
<div class="detail-card">
<div class="detail-row">
<strong>Source:</strong>
<a href="{{ webmention.source_url }}" target="_blank">{{ webmention.source_url }}</a>
</div>
<div class="detail-row">
<strong>Target:</strong>
{% if webmention.target_note_id %}
<a href="{{ url_for('public.note', slug=webmention.target_slug) }}">{{ webmention.target_url }}</a>
{% else %}
{{ webmention.target_url }} (Homepage)
{% endif %}
</div>
<div class="detail-row">
<strong>Type:</strong>
<span class="badge badge-{{ webmention.mention_type }}">{{ webmention.mention_type }}</span>
</div>
<div class="detail-row">
<strong>Author:</strong>
{{ webmention.author_name or 'Anonymous' }}
{% if webmention.author_url %}
(<a href="{{ webmention.author_url }}" target="_blank">{{ webmention.author_url }}</a>)
{% endif %}
</div>
{% if webmention.author_photo %}
<div class="detail-row">
<strong>Author Photo:</strong>
<img src="{{ webmention.author_photo }}" alt="{{ webmention.author_name or 'Author' }}" width="48" height="48" loading="lazy">
</div>
{% endif %}
{% if webmention.content_snippet %}
<div class="detail-row">
<strong>Content:</strong>
<div class="content-preview">{{ webmention.content_snippet|safe }}</div>
</div>
{% endif %}
<div class="detail-row">
<strong>Validation Status:</strong>
<span class="status-badge status-{{ webmention.validation_status }}">{{ webmention.validation_status }}</span>
{% if webmention.validation_error %}
<br><small class="error-text">{{ webmention.validation_error }}</small>
{% endif %}
</div>
<div class="detail-row">
<strong>Moderation Status:</strong>
<span class="status-badge status-{{ webmention.moderation_status }}">{{ webmention.moderation_status }}</span>
</div>
<div class="detail-row">
<strong>Received:</strong>
{{ webmention.received_at.strftime('%B %d, %Y at %I:%M %p') }}
</div>
{% if webmention.validated_at %}
<div class="detail-row">
<strong>Validated:</strong>
{{ webmention.validated_at.strftime('%B %d, %Y at %I:%M %p') }}
</div>
{% endif %}
</div>
{# Moderation Actions #}
<div class="moderation-actions">
<h3>Actions</h3>
<form method="POST" action="{{ url_for('admin.webmention_action', id=webmention.id) }}" style="display: inline;">
<input type="hidden" name="action" value="approve">
<button type="submit" class="button button-primary" {% if webmention.moderation_status == 'approved' %}disabled{% endif %}>
Approve
</button>
</form>
<form method="POST" action="{{ url_for('admin.webmention_action', id=webmention.id) }}" style="display: inline;">
<input type="hidden" name="action" value="hide">
<button type="submit" class="button" {% if webmention.moderation_status == 'hidden' %}disabled{% endif %}>
Hide
</button>
</form>
<form method="POST" action="{{ url_for('admin.webmention_action', id=webmention.id) }}" style="display: inline;">
<input type="hidden" name="action" value="delete">
<button type="submit" class="button button-danger" onclick="return confirm('Delete this webmention permanently?')">
Delete
</button>
</form>
</div>
</div>
{% endblock %}
+125
View File
@@ -0,0 +1,125 @@
{% extends "admin/base.html" %}
{% block title %}Webmentions - StarPunk Admin{% endblock %}
{% block admin_content %}
<div class="webmentions-admin">
<h2>Webmentions</h2>
<div class="dashboard-actions">
<a href="{{ url_for('admin.dashboard') }}" class="button">
Back to Dashboard
</a>
</div>
{# Filter tabs #}
<div class="filter-tabs">
<a href="{{ url_for('admin.webmentions') }}" class="{% if not status_filter %}active{% endif %}">
All
</a>
<a href="{{ url_for('admin.webmentions', status='pending') }}" class="{% if status_filter == 'pending' %}active{% endif %}">
Pending
</a>
<a href="{{ url_for('admin.webmentions', status='approved') }}" class="{% if status_filter == 'approved' %}active{% endif %}">
Approved
</a>
<a href="{{ url_for('admin.webmentions', status='hidden') }}" class="{% if status_filter == 'hidden' %}active{% endif %}">
Hidden
</a>
</div>
{% if webmentions %}
<form method="POST" action="{{ url_for('admin.webmention_bulk_action') }}">
<div class="bulk-actions">
<button type="submit" name="action" value="approve" class="button">
Approve Selected
</button>
<button type="submit" name="action" value="hide" class="button">
Hide Selected
</button>
<button type="submit" name="action" value="delete" class="button button-danger"
onclick="return confirm('Delete selected webmentions permanently?')">
Delete Selected
</button>
</div>
<table class="webmention-table">
<thead>
<tr>
<th><input type="checkbox" id="select-all"></th>
<th>Source</th>
<th>Target</th>
<th>Type</th>
<th>Author</th>
<th>Status</th>
<th>Received</th>
<th>Actions</th>
</tr>
</thead>
<tbody>
{% for wm in webmentions %}
<tr>
<td><input type="checkbox" name="ids" value="{{ wm.id }}"></td>
<td><a href="{{ wm.source_url }}" target="_blank">{{ wm.source_url|truncate(40) }}</a></td>
<td>
{% if wm.target_note_id %}
<a href="{{ url_for('public.note', slug=wm.target_slug) }}">{{ wm.target_slug }}</a>
{% else %}
Homepage
{% endif %}
</td>
<td><span class="badge badge-{{ wm.mention_type }}">{{ wm.mention_type }}</span></td>
<td>{{ wm.author_name or 'Anonymous' }}</td>
<td>
<span class="status-badge status-{{ wm.moderation_status }}">
{{ wm.moderation_status }}
</span>
</td>
<td>{{ wm.received_at.strftime('%b %d, %Y %H:%M') }}</td>
<td>
<a href="{{ url_for('admin.webmention_detail', id=wm.id) }}" class="button button-small">
View
</a>
</td>
</tr>
{% endfor %}
</tbody>
</table>
</form>
{# Pagination #}
{% if total_pages > 1 %}
<nav class="pagination">
{% if page > 1 %}
<a href="?page={{ page - 1 }}{% if status_filter %}&status={{ status_filter }}{% endif %}" class="button">Previous</a>
{% endif %}
<span>Page {{ page }} of {{ total_pages }}</span>
{% if page < total_pages %}
<a href="?page={{ page + 1 }}{% if status_filter %}&status={{ status_filter }}{% endif %}" class="button">Next</a>
{% endif %}
</nav>
{% endif %}
{% else %}
{# Empty states #}
{% if status_filter %}
<div class="empty-state">
<p>No webmentions match the current filters.</p>
<a href="{{ url_for('admin.webmentions') }}" class="button">Clear Filters</a>
</div>
{% else %}
<div class="empty-state">
<p>No webmentions received yet.</p>
<p class="text-muted">They will appear here when other sites mention your content.</p>
</div>
{% endif %}
{% endif %}
</div>
<script>
// Select All functionality
document.getElementById('select-all')?.addEventListener('change', function() {
document.querySelectorAll('input[name="ids"]').forEach(cb => cb.checked = this.checked);
});
</script>
{% endblock %}
+14 -3
View File
@@ -5,8 +5,17 @@
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{% block title %}StarPunk{% endblock %}</title>
<link rel="stylesheet" href="{{ url_for('static', filename='css/style.css') }}">
<link rel="alternate" type="application/rss+xml" title="{{ config.SITE_NAME }} RSS Feed" href="{{ url_for('public.feed', _external=True) }}">
<link rel="alternate" type="application/xml+opml" title="{{ config.SITE_NAME }} Feed Subscription List" href="{{ url_for('public.opml', _external=True) }}">
<link rel="alternate" type="application/rss+xml" title="{{ config.SITE_NAME }} RSS Feed" href="{{ absolute_url_for('public.feed') }}">
<link rel="alternate" type="application/xml+opml" title="{{ config.SITE_NAME }} Feed Subscription List" href="{{ absolute_url_for('public.opml') }}">
{# Webmention endpoint (v1.6.0) #}
{% if config.WEBMENTION_ENABLED %}
<link rel="webmention" href="/webmention">
<link rel="micropub" href="{{ absolute_url_for('micropub.micropub_endpoint') }}">
<link rel="indieauth-metadata" href="{{ absolute_url_for('indieauth.metadata') }}">
<link rel="authorization_endpoint" href="{{ absolute_url_for('indieauth.authorize') }}">
<link rel="token_endpoint" href="{{ absolute_url_for('indieauth.token') }}">
{% endif %}
{# rel-me links from discovered author profile (v1.2.0 Phase 2) #}
{% if author and author.rel_me_links %}
@@ -30,7 +39,9 @@
<a href="/">Home</a>
<a href="{{ url_for('public.feed') }}">RSS</a>
{% if g.me %}
<a href="{{ url_for('admin.dashboard') }}">Admin</a>
<a href="{{ url_for('admin.dashboard') }}">Dashboard</a>
{% else %}
<a href="{{ url_for('auth.login_form') }}">Login</a>
{% endif %}
<form action="/search" method="get" role="search" style="margin-left: auto; display: flex; gap: var(--spacing-sm);">
<input
+2 -2
View File
@@ -9,7 +9,7 @@
<h2 class="p-name">{{ config.SITE_NAME or 'Recent Notes' }}</h2>
{# u-url for feed (self-reference) #}
<a class="u-url" href="{{ url_for('public.index', _external=True) }}" style="display: none;">Feed URL</a>
<a class="u-url" href="{{ absolute_url_for('public.index') }}" style="display: none;">Feed URL</a>
{# Feed-level author h-card with all properties #}
{# Hidden because it's semantic-only markup for parsers, not visual content #}
@@ -53,7 +53,7 @@
<footer class="note-meta">
{# u-url for permalink #}
<a class="u-url" href="{{ url_for('public.note', slug=note.slug, _external=True) }}">
<a class="u-url" href="{{ absolute_url_for('public.note', slug=note.slug) }}">
<time class="dt-published" datetime="{{ note.created_at.isoformat() }}">
{{ note.created_at.strftime('%B %d, %Y') }}
</time>
+139 -1
View File
@@ -13,6 +13,31 @@
<h1 class="p-name">{{ note.title }}</h1>
{% endif %}
{# Reply context (v1.6.0 Phase 4) - displayed if this is a reply post #}
{% if note.in_reply_to %}
<div class="reply-context">
<span class="reply-label">In reply to:</span>
<blockquote class="h-cite">
{% if reply_context and reply_context.fetch_status == 'fetched' %}
{% if reply_context.content_snippet %}
<p class="p-content">{{ reply_context.content_snippet }}</p>
{% endif %}
<cite>
<a class="u-in-reply-to" href="{{ note.in_reply_to }}">
{% 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 %}
</a>
</cite>
{% else %}
<cite>
<a class="u-in-reply-to" href="{{ note.in_reply_to }}">{{ note.in_reply_to }}</a>
</cite>
{% endif %}
</blockquote>
</div>
{% 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) }}
@@ -24,7 +49,7 @@
<footer class="note-meta">
{# u-url and u-uid same for notes (per Q23) #}
<a class="u-url u-uid" href="{{ url_for('public.note', slug=note.slug, _external=True) }}">
<a class="u-url u-uid" href="{{ absolute_url_for('public.note', slug=note.slug) }}">
<time class="dt-published" datetime="{{ note.created_at.isoformat() }}">
{{ note.created_at.strftime('%B %d, %Y at %I:%M %p') }}
</time>
@@ -68,5 +93,118 @@
<nav class="note-nav">
<a href="/">Back to all notes</a>
</nav>
{# Webmentions section (v1.6.0 Phase 5) - only shown if approved webmentions exist #}
{% if webmentions %}
<section class="webmentions">
<h2>Responses</h2>
{% if replies %}
<div class="webmention-group webmention-replies">
<h3>{{ replies|length }} {{ 'Reply' if replies|length == 1 else 'Replies' }}</h3>
{% for reply in replies %}
<article class="webmention webmention-reply h-cite">
<div class="webmention-author">
{% if reply.author_photo %}
<img src="{{ reply.author_photo }}" alt="" width="48" height="48" loading="lazy">
{% endif %}
<a class="p-author" href="{{ reply.author_url or reply.source_url }}">
{{ reply.author_name or 'Anonymous' }}
</a>
</div>
{% if reply.content_snippet %}
<div class="p-content">{{ reply.content_snippet|safe }}</div>
{% endif %}
<a class="u-url webmention-date" href="{{ reply.source_url }}">
<time class="dt-published" datetime="{{ reply.received_at.isoformat() }}">
{{ reply.received_at.strftime('%B %d, %Y') }}
</time>
</a>
</article>
{% endfor %}
</div>
{% endif %}
{% if likes %}
<div class="webmention-group webmention-likes">
<h3>{{ likes|length }} {{ 'Like' if likes|length == 1 else 'Likes' }}</h3>
<div class="facepile">
{% for wm in likes[:8] %}
<a href="{{ wm.author_url or wm.source_url }}" class="face" title="{{ wm.author_name or 'Anonymous' }}">
{% if wm.author_photo %}
<img src="{{ wm.author_photo }}" alt="{{ wm.author_name or '' }}" width="32" height="32" loading="lazy">
{% else %}
<span class="face-initial" style="background-color: {{ wm.author_url|url_to_color }}">
{{ (wm.author_name or '?')[0]|upper }}
</span>
{% endif %}
</a>
{% endfor %}
{% if likes|length > 8 %}
<span class="face-overflow">+{{ likes|length - 8 }} others</span>
{% endif %}
</div>
</div>
{% endif %}
{% if reposts %}
<div class="webmention-group webmention-reposts">
<h3>{{ reposts|length }} {{ 'Repost' if reposts|length == 1 else 'Reposts' }}</h3>
<div class="facepile">
{% for wm in reposts[:8] %}
<a href="{{ wm.author_url or wm.source_url }}" class="face" title="{{ wm.author_name or 'Anonymous' }}">
{% if wm.author_photo %}
<img src="{{ wm.author_photo }}" alt="{{ wm.author_name or '' }}" width="32" height="32" loading="lazy">
{% else %}
<span class="face-initial" style="background-color: {{ wm.author_url|url_to_color }}">
{{ (wm.author_name or '?')[0]|upper }}
</span>
{% endif %}
</a>
{% endfor %}
{% if reposts|length > 8 %}
<span class="face-overflow">+{{ reposts|length - 8 }} others</span>
{% endif %}
</div>
</div>
{% endif %}
{% if bookmarks %}
<div class="webmention-group webmention-bookmarks">
<h3>{{ bookmarks|length }} {{ 'Bookmark' if bookmarks|length == 1 else 'Bookmarks' }}</h3>
<div class="facepile">
{% for wm in bookmarks[:8] %}
<a href="{{ wm.author_url or wm.source_url }}" class="face" title="{{ wm.author_name or 'Anonymous' }}">
{% if wm.author_photo %}
<img src="{{ wm.author_photo }}" alt="{{ wm.author_name or '' }}" width="32" height="32" loading="lazy">
{% else %}
<span class="face-initial" style="background-color: {{ wm.author_url|url_to_color }}">
{{ (wm.author_name or '?')[0]|upper }}
</span>
{% endif %}
</a>
{% endfor %}
{% if bookmarks|length > 8 %}
<span class="face-overflow">+{{ bookmarks|length - 8 }} others</span>
{% endif %}
</div>
</div>
{% endif %}
{% if mentions %}
<div class="webmention-group webmention-mentions">
<h3>{{ mentions|length }} {{ 'Mention' if mentions|length == 1 else 'Mentions' }}</h3>
{% for mention in mentions %}
<div class="webmention webmention-mention">
<a href="{{ mention.source_url }}">{{ mention.author_name or mention.source_url }}</a>
{% if mention.content_snippet %}
<p>{{ mention.content_snippet|truncate(200) }}</p>
{% endif %}
</div>
{% endfor %}
</div>
{% endif %}
</section>
{% endif %}
</article>
{% endblock %}
+1 -1
View File
@@ -28,7 +28,7 @@
<footer class="note-meta">
{# u-url for permalink #}
<a class="u-url" href="{{ url_for('public.note', slug=note.slug, _external=True) }}">
<a class="u-url" href="{{ absolute_url_for('public.note', slug=note.slug) }}">
<time class="dt-published" datetime="{{ note.created_at.isoformat() }}">
{{ note.created_at.strftime('%B %d, %Y') }}
</time>
+48
View File
@@ -0,0 +1,48 @@
"""
Absolute URLs come from SITE_URL, not the request (v2.0.1)
Behind a reverse proxy the app is reached over plain HTTP, so URLs built
from the request said http:// on an https site.
"""
import pytest
from starpunk import create_app
from starpunk.notes import create_note
@pytest.fixture
def app(tmp_path):
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",
}
)
def test_pages_use_site_url_behind_http_proxy(app):
with app.app_context():
note = create_note(content="Hello over the proxy", published=True, tags=["proxy"])
client = app.test_client()
pages = ["/", f"/note/{note.slug}", "/tag/proxy"]
for path in pages:
# The test client makes plain http://localhost requests, like Caddy does
response = client.get(path)
assert response.status_code == 200, path
html = response.data.decode()
assert "http://localhost" not in html, path
home = client.get("/").data.decode()
assert 'href="https://blog.example.com/feed"' in home
assert 'href="https://blog.example.com/opml.xml"' in home
note_html = client.get(f"/note/{note.slug}").data.decode()
assert f'href="https://blog.example.com/note/{note.slug}"' in note_html
-522
View File
@@ -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
-637
View File
@@ -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 """
<!DOCTYPE html>
<html>
<head>
<link rel="authorization_endpoint" href="https://auth.example.com/authorize">
<link rel="token_endpoint" href="https://auth.example.com/token">
<title>Test Profile</title>
</head>
<body>
<h1>Hello World</h1>
</body>
</html>
"""
@pytest.fixture
def mock_profile_html_relative():
"""HTML profile with relative URLs"""
return """
<!DOCTYPE html>
<html>
<head>
<link rel="authorization_endpoint" href="/auth/authorize">
<link rel="token_endpoint" href="/auth/token">
</head>
<body></body>
</html>
"""
@pytest.fixture
def mock_link_headers():
"""HTTP Link headers with IndieAuth endpoints"""
return (
'<https://auth.example.com/authorize>; rel="authorization_endpoint", '
'<https://auth.example.com/token>; 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 = '<https://auth.example.com/token>; 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 = '</auth/token>; 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 = '<html><head></head><body></body></html>'
endpoints = _parse_html_links(html, 'https://alice.example.com/')
assert endpoints == {}
def test_parse_html_links_malformed():
"""Parse malformed HTML gracefully"""
html = '<html><head><link rel="token_endpoint"' # Missing closing tags
endpoints = _parse_html_links(html, 'https://alice.example.com/')
# Should return empty dict, not crash
assert isinstance(endpoints, dict)
def test_parse_html_links_rel_as_list():
"""Parse HTML where rel attribute is a list"""
html = '''
<html><head>
<link rel="authorization_endpoint me" href="https://auth.example.com/authorize">
</head></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 = '<html></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'
@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': '<https://different.example.com/token>; 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 = '<html><head></head><body></body></html>'
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
+243
View File
@@ -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")
+329
View File
@@ -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 = '<html><head><link rel="redirect_uri" href="/cb"></head></html>'
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
+12 -12
View File
@@ -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',
+4 -3
View File
@@ -212,11 +212,12 @@ class TestAdminTemplates:
assert response.status_code == 200
assert b"<form" in response.data
def test_login_has_me_input(self, client):
"""Test login form has 'me' URL input"""
def test_login_has_sso_button(self, client):
"""Test login form offers OIDC sign-in, not a URL field (v2.0.0)"""
response = client.get("/auth/login")
assert response.status_code == 200
assert b'name="me"' in response.data or b'id="me"' in response.data
assert b"Sign in with" in response.data
assert b'name="me"' not in response.data
def test_login_has_submit_button(self, client):
"""Test login form has submit button"""