Files
StarPunk/starpunk/auth.py
T
PhilandClaude Opus 5.5 75946be7b2 maint: Dependency upgrades and High backlog items (v2.11.0)
- All dependencies to current releases (97 known vulnerabilities -> 0),
  Python 3.14, uv pinned, requirements-test.txt, lxml/dateutil pinned
- CSRF tokens on admin forms, logout and IndieAuth consent
- IndieAuth client and crosspost link-card fetches via safe_get
- FLASK_DEBUG/FLASK_ENV default off/production; image sets them
- Foreign keys enforced on pooled connections; migration 018 removes orphans
- Rate limits shared across processes (rate_limits, migration 019)
- datetime.utcnow() and sqlite3 default adapters replaced
- compose.yaml fixed; duplicate dev_auth.py and test.ini removed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:09:52 -07:00

503 lines
14 KiB
Python

"""
Authentication module for StarPunk
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 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
Functions:
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
require_auth: Decorator for protected routes
Exceptions:
AuthError: Base authentication exception
InvalidStateError: CSRF state validation failed
UnauthorizedError: User not authorized as admin
OIDCError: Identity provider error
"""
import base64
import hashlib
import secrets
import time
from datetime import datetime, timedelta, timezone
from functools import wraps
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.database import get_db
# 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"""
class InvalidStateError(AuthError):
"""CSRF state validation failed"""
class UnauthorizedError(AuthError):
"""User not authorized as admin"""
class OIDCError(AuthError):
"""Identity provider error"""
def _hash_token(token: str) -> str:
"""
Hash token using SHA-256
Args:
token: Token to hash
Returns:
Hexadecimal hash string
"""
return hashlib.sha256(token.encode()).hexdigest()
def _generate_state_token() -> str:
"""Generate a URL-safe random token"""
return secrets.token_urlsafe(32)
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:
"""
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:
next_url: Where to send the admin after login (same site only)
Returns:
Redirect URL to the provider's authorization endpoint
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(
"""
INSERT INTO oidc_login_state (state, nonce, code_verifier, next_url, expires_at)
VALUES (?, ?, ?, ?, ?)
""",
(
state,
nonce,
code_verifier,
_safe_next_url(next_url),
datetime.now(timezone.utc).replace(tzinfo=None) + 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()
db.execute("DELETE FROM oidc_login_state WHERE state = ?", (state,))
db.commit()
return dict(row) if row else None
def handle_callback(
code: str, state: str, iss: Optional[str] = None
) -> Tuple[str, Optional[str]]:
"""
Finish the OIDC flow: exchange the code, verify the ID token, check
the subject is the configured admin, and create a session.
Args:
code: Authorization code from the provider
state: CSRF state token
iss: Issuer from the redirect (RFC 9207), checked when present
Returns:
(session_token, next_url)
Raises:
InvalidStateError: State token validation failed
UnauthorizedError: Subject is not the configured admin
OIDCError: Provider or token error
"""
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")
metadata = get_oidc_metadata()
if iss and iss.rstrip("/") != metadata["issuer"].rstrip("/"):
raise OIDCError(f"Unexpected issuer in callback: {iss}")
try:
response = httpx.post(
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,
)
except httpx.RequestError as e:
raise OIDCError(f"Token request failed: {e}")
if response.status_code != 200:
current_app.logger.error(
f"Auth: OIDC token endpoint returned {response.status_code}: {response.text[:200]}"
)
raise OIDCError(f"Token endpoint returned {response.status_code}")
try:
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")
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:
raise OIDCError("ADMIN_ME not configured")
session_token = create_session(me)
# Refresh the author h-card; never block login on it
try:
from starpunk.author_discovery import get_author_profile
get_author_profile(me, refresh=True)
except Exception as e:
current_app.logger.warning(f"Author discovery failed: {e}")
return session_token, pending["next_url"]
def create_session(me: str) -> str:
"""
Create authenticated session
Args:
me: Verified user identity URL
Returns:
Session token (plaintext, to be sent as cookie)
"""
# Generate secure token
session_token = secrets.token_urlsafe(32)
token_hash = _hash_token(session_token)
current_app.logger.debug("Auth: Session token generated (hash will be stored)")
# Calculate expiry (use configured session lifetime or default to 30 days)
session_lifetime = current_app.config.get("SESSION_LIFETIME", 30)
expires_at = datetime.now(timezone.utc).replace(tzinfo=None) + timedelta(days=session_lifetime)
current_app.logger.debug(f"Auth: Session expiry: {expires_at} ({session_lifetime} days)")
# Get request metadata
user_agent = request.headers.get("User-Agent", "")[:200]
ip_address = request.remote_addr
current_app.logger.debug(f"Auth: Request metadata - IP: {ip_address}, User-Agent: {user_agent[:50]}...")
# Store in database
db = get_db(current_app)
db.execute(
"""
INSERT INTO sessions
(session_token_hash, me, expires_at, user_agent, ip_address)
VALUES (?, ?, ?, ?, ?)
""",
(token_hash, me, expires_at, user_agent, ip_address),
)
db.commit()
# Cleanup expired sessions
_cleanup_expired_sessions()
# Log session creation
current_app.logger.info(f"Auth: Session created for {me}")
return session_token
def verify_session(token: str) -> Optional[Dict[str, Any]]:
"""
Verify session token
Args:
token: Session token from cookie
Returns:
Session info dict if valid, None otherwise
"""
if not token:
current_app.logger.debug("Auth: No session token provided")
return None
token_hash = _hash_token(token)
db = get_db(current_app)
session_data = db.execute(
"""
SELECT id, me, created_at, expires_at, last_used_at
FROM sessions
WHERE session_token_hash = ?
AND expires_at > datetime('now')
""",
(token_hash,),
).fetchone()
if not session_data:
current_app.logger.debug("Auth: Session token invalid or expired")
return None
current_app.logger.debug(f"Auth: Session verified for {session_data['me']}")
# Update last_used_at for activity tracking
db.execute(
"""
UPDATE sessions
SET last_used_at = datetime('now')
WHERE id = ?
""",
(session_data["id"],),
)
db.commit()
return {
"me": session_data["me"],
"created_at": session_data["created_at"],
"expires_at": session_data["expires_at"],
}
def destroy_session(token: str) -> None:
"""
Destroy session (logout)
Args:
token: Session token to destroy
"""
if not token:
return
token_hash = _hash_token(token)
db = get_db(current_app)
db.execute(
"""
DELETE FROM sessions
WHERE session_token_hash = ?
""",
(token_hash,),
)
db.commit()
current_app.logger.info("Session destroyed")
def require_auth(f):
"""
Decorator to require authentication for a route
Usage:
@app.route('/admin')
@require_auth
def admin_dashboard():
return render_template('admin/dashboard.html')
"""
@wraps(f)
def decorated_function(*args, **kwargs):
# Get session token from cookie
session_token = request.cookies.get("starpunk_session")
# Verify session
session_info = verify_session(session_token)
if not session_info:
# Store intended destination
session["next"] = request.url
return redirect(url_for("auth.login_form"))
# Store user info in g for use in views
g.user = session_info
g.me = session_info["me"]
return f(*args, **kwargs)
return decorated_function