Files
StarPunk/starpunk/micropub.py
T
PhilandClaude Opus 5.5 ccb9f6dce2 fix: keep inline images in Micropub articles (v2.16.0)
- Content sent as both html and text is stored as the HTML; the text is
  usually a plain fallback, so images, links and headings were lost.
- Images embedded from other sites are copied into the media library
  (SSRF-checked fetcher, best effort, max 20) and the text points at the
  copies, on create and on content replace.
- HTML content is sanitized as is instead of going through Markdown, which
  added stray <br>s and empty paragraphs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 17:11:46 -07:00

988 lines
37 KiB
Python

"""
Micropub endpoint implementation for StarPunk
This module handles Micropub protocol requests, providing a standard IndieWeb
interface for creating posts via external clients.
Functions:
normalize_properties: Convert form/JSON data to Micropub properties format
extract_content: Get content from Micropub properties
extract_title: Get the title (name) from Micropub properties
extract_summary: Get the author's summary from Micropub properties
extract_tags: Get category tags from Micropub properties
handle_create: Process Micropub create action
handle_update: Process Micropub update action (v2.4.0)
handle_delete: Process Micropub delete / undelete actions (v2.4.0)
handle_query: Process Micropub query endpoints
extract_bearer_token: Get token from Authorization header or form
Exceptions:
MicropubError: Base exception for Micropub operations
MicropubAuthError: Authentication/authorization errors
MicropubValidationError: Invalid request data
References:
- W3C Micropub Specification: https://www.w3.org/TR/micropub/
- IndieAuth Specification: https://www.w3.org/TR/indieauth/
"""
from datetime import datetime, timezone
from typing import Optional
from flask import Request, current_app, jsonify
from starpunk.models import split_title
from starpunk.notes import (
create_note, delete_note, get_note, list_notes, undelete_note, update_note,
InvalidNoteDataError, NoteNotFoundError,
)
from starpunk.indieauth import check_scope
from starpunk.utils import absolute_url_for, iso_utc
# Custom Exceptions
class MicropubError(Exception):
"""Base exception for Micropub operations"""
def __init__(self, error: str, error_description: str, status_code: int = 400):
self.error = error
self.error_description = error_description
self.status_code = status_code
super().__init__(error_description)
class MicropubAuthError(MicropubError):
"""Authentication or authorization error"""
def __init__(self, error_description: str, status_code: int = 401):
super().__init__("unauthorized", error_description, status_code)
class MicropubValidationError(MicropubError):
"""Invalid request data"""
def __init__(self, error_description: str):
super().__init__("invalid_request", error_description, 400)
# Response Helpers
def error_response(error: str, error_description: str, status_code: int = 400):
"""
Generate OAuth 2.0 compliant error response
Args:
error: Error code (e.g., "invalid_request")
error_description: Human-readable error description
status_code: HTTP status code
Returns:
Tuple of (response, status_code)
"""
headers = {}
if status_code == 401:
# RFC 6750 3: tell the client how to authenticate (v2.9.0)
challenge = 'Bearer realm="micropub"'
if error == "unauthorized" and "Invalid" in error_description:
challenge += ', error="invalid_token"'
headers["WWW-Authenticate"] = challenge
return (
jsonify({"error": error, "error_description": error_description}),
status_code,
headers,
)
# Token Extraction
def extract_bearer_token(request: Request) -> Optional[str]:
"""
Extract bearer token from Authorization header or form parameter
Micropub spec allows token in either location:
- Authorization: Bearer <token>
- access_token form parameter
Args:
request: Flask request object
Returns:
Token string if found, None otherwise
"""
# The scheme is case-insensitive (RFC 7235)
scheme, _, credentials = request.headers.get("Authorization", "").partition(" ")
header_token = credentials.strip() if scheme.lower() == "bearer" else None
body_token = None
if request.method == "POST":
body_token = request.form.get("access_token")
elif request.method == "GET":
body_token = request.args.get("access_token")
# Only one method may be used (RFC 6750 2) (v2.9.0)
if header_token and body_token:
raise MicropubValidationError("Send the access token in the header or the body, not both")
return header_token or body_token
# Property Normalization
def normalize_properties(data: dict) -> dict:
"""
Normalize Micropub properties from both form and JSON formats
Handles two input formats:
- JSON: {"type": ["h-entry"], "properties": {"content": ["value"]}}
- Form: {content: ["value"], "category[]": ["tag1", "tag2"]}
Args:
data: Raw request data (form dict or JSON dict)
Returns:
Normalized properties dict with all values as lists
"""
# JSON format has properties nested. Values MUST be arrays (3.3.2); a
# bare value is wrapped rather than read character by character.
# mp-* commands and access_token are not properties (3.2).
if "properties" in data:
properties = data["properties"]
if not isinstance(properties, dict):
raise MicropubValidationError("properties must be an object")
return {
key: value if isinstance(value, list) else [value]
for key, value in properties.items()
if not key.startswith("mp-") and key != "access_token"
}
# Form format - convert to properties dict
properties = {}
for key, value in data.items():
if hasattr(value, "filename") or (isinstance(value, list) and value and hasattr(value[0], "filename")):
continue # uploaded files are handled separately
# Skip reserved Micropub parameters
if key.startswith("mp-") or key in ["action", "url", "access_token", "h"]:
continue
# Handle array notation: property[] -> property
clean_key = key.rstrip("[]")
# Ensure value is always a list
if not isinstance(value, list):
value = [value]
properties[clean_key] = value
return properties
# Property Extraction
def extract_content(properties: dict) -> str:
"""
Extract content from Micropub properties
Args:
properties: Normalized Micropub properties dict
Returns:
Content string
Raises:
MicropubValidationError: If content is missing or empty
"""
content_list = properties.get("content") or properties.get("summary") or []
# Handle both plain text and HTML/text objects
if not content_list:
raise MicropubValidationError("Content is required")
content = content_list[0]
# Handle structured content ({"html": "...", "text": "..."}). The HTML is
# what was written; clients send text as a plain fallback, which loses
# images, links and headings (v2.16.0; before, text was preferred)
if isinstance(content, dict):
content = content.get("html") or content.get("text", "")
if not isinstance(content, str) or not content.strip():
raise MicropubValidationError("Content cannot be empty")
return content.strip()
def content_format(properties: dict) -> Optional[str]:
"""'html' if the content was sent as HTML (returned as such by q=source)"""
content = _first(properties.get("content"))
if isinstance(content, dict) and content.get("html"):
return "html"
return None
def _has_text(content) -> bool:
"""Whether a content property has any text. Likes, reposts (v2.5.0) and
photo posts (v2.6.5) may come without."""
values = content if isinstance(content, list) else [content]
return any(
(c.strip() if isinstance(c, str) else (c.get("text") or c.get("html") or "").strip())
for c in values if c
)
def extract_title(properties: dict) -> Optional[str]:
"""
Extract the title (Micropub 'name' property), stored in notes.title (ADR-076)
Args:
properties: Normalized Micropub properties dict
Returns:
Title on a single line, or None if no name was sent
"""
name = (properties.get("name") or [""])[0]
if not isinstance(name, str):
return None
return " ".join(name.split()) or None
def extract_summary(properties: dict) -> Optional[str]:
"""The author's summary (Micropub 'summary' property, v2.16.0), as plain text"""
summary = _first(properties.get("summary"))
if isinstance(summary, dict):
summary = summary.get("text") or summary.get("value") or ""
if not isinstance(summary, str):
return None
return summary.strip() or None
def drop_title_heading(content: str, title: Optional[str]) -> str:
"""Content without a '# heading' first line that only repeats the title"""
heading, rest = split_title(content)
if title and heading == title:
return rest
return content
def extract_tags(properties: dict) -> list[str]:
"""
Extract tags from Micropub category property
Args:
properties: Normalized Micropub properties dict
Returns:
List of tag strings
"""
categories = properties.get("category", [])
# Strings only: person tags (h-card objects) aren't supported and are
# ignored, as Micropub says to ignore what isn't recognised (3.3.5)
return [tag.strip() for tag in categories if isinstance(tag, str) and tag.strip()]
def extract_published_date(properties: dict) -> Optional[datetime]:
"""
Extract published date from Micropub properties
Args:
properties: Normalized Micropub properties dict
Returns:
Datetime object if published date provided, None otherwise
"""
published = _first(properties.get("published"))
if not published:
return None
try:
value = datetime.fromisoformat(str(published).strip().replace("Z", "+00:00"))
except ValueError:
raise MicropubValidationError(f"published is not an ISO 8601 date: {published}")
# Stored times are naive UTC, like every other note (v2.9.0)
if value.tzinfo is not None:
value = value.astimezone(timezone.utc).replace(tzinfo=None)
return value
# Action Handlers
MAX_PHOTOS = 4 # ADR-057
MAX_REMOTE_PHOTO_BYTES = 20 * 1024 * 1024
# Properties we can store, and so can be updated (v2.4.0)
UPDATABLE = {"content", "name", "summary", "category", "in-reply-to", "post-status", "photo"}
def _first(value):
if isinstance(value, list):
return value[0] if value else None
return value
def _require_scope(token_info: dict, *scopes: str) -> None:
granted = token_info.get("scope", "")
if not any(check_scope(s, granted) for s in scopes):
raise MicropubError(
"insufficient_scope", f"Token lacks {' or '.join(scopes)} scope", status_code=403
)
def extract_post_status(properties: dict) -> bool:
"""post-status: 'draft' -> unpublished; 'published' or absent -> published"""
status = _first(properties.get("post-status"))
if status in (None, "", "published"):
return True
if status == "draft":
return False
raise MicropubValidationError(f"Unsupported post-status: {status}")
def extract_visibility_draft(properties: dict) -> bool:
"""
True if visibility asks for a non-public post (v2.9.0)
StarPunk only has public posts and drafts, so private and unlisted posts
are kept as drafts rather than published.
"""
visibility = _first(properties.get("visibility"))
if visibility in (None, "", "public"):
return False
if visibility in ("private", "unlisted"):
return True
raise MicropubValidationError(f"Unsupported visibility: {visibility}")
UNSUPPORTED_MEDIA = ("video", "audio")
def extract_url_property(properties: dict, name: str) -> Optional[str]:
"""A URL property (in-reply-to, like-of, repost-of): string or h-cite"""
value = _first(properties.get(name))
if isinstance(value, dict): # h-cite
value = _first((value.get("properties") or {}).get("url")) or value.get("value")
value = (value or "").strip() if isinstance(value, str) else ""
if value and not value.startswith(("http://", "https://")):
raise MicropubValidationError(f"{name} must be an http(s) URL")
return value or None
def extract_in_reply_to(properties: dict) -> Optional[str]:
return extract_url_property(properties, "in-reply-to")
def extract_photos(properties: dict) -> list[dict[str, str]]:
"""
Extract photo URLs and alt text from Micropub properties
Handles both simple URL strings and structured photo objects with alt text.
Examples:
>>> extract_photos({'photo': ['https://example.com/photo.jpg']})
[{'url': 'https://example.com/photo.jpg', 'alt': ''}]
>>> extract_photos({'photo': [{'value': 'https://example.com/photo.jpg', 'alt': 'Sunset'}]})
[{'url': 'https://example.com/photo.jpg', 'alt': 'Sunset'}]
"""
result = []
for photo in properties.get("photo", []):
if isinstance(photo, str):
result.append({'url': photo, 'alt': ''})
elif isinstance(photo, dict):
url = photo.get('value') or photo.get('url', '')
if url:
result.append({'url': url, 'alt': photo.get('alt', '')})
return result
def _public_address(host: str) -> bool:
"""True if every address the host resolves to is public (no SSRF into the LAN)"""
import ipaddress
import socket
try:
infos = socket.getaddrinfo(host, None)
except socket.gaierror:
return False
for info in infos:
ip = ipaddress.ip_address(info[4][0])
if not ip.is_global:
return False
return bool(infos)
def _fetch_remote_photo(url: str) -> Optional[dict]:
"""
Download a photo hosted elsewhere into the media library. Returns the
saved media ({'id', 'path', ...}), or None if it couldn't be fetched.
Uses the webmention fetcher (v2.9.0): every redirect is checked against
private addresses and the connection is pinned to the checked address.
"""
from urllib.parse import urlparse
from starpunk.media import save_media
from starpunk.webmention_ssrf import safe_get, user_agent
try:
result = safe_get(
url, headers={"User-Agent": user_agent(current_app.config.get("SITE_URL", ""))},
max_bytes=MAX_REMOTE_PHOTO_BYTES, timeout=20,
)
if result.status_code != 200:
raise ValueError(f"HTTP {result.status_code}")
name = urlparse(result.url).path.rsplit("/", 1)[-1] or "photo.jpg"
return save_media(result.content, name)
except Exception as e:
current_app.logger.warning(f"Could not fetch photo {url}: {e}")
return None
def _media_id_for_url(url: str) -> Optional[int]:
"""Media id for a photo URL: ours by path, or downloaded if hosted elsewhere"""
from starpunk.database import get_db
site_url = current_app.config.get("SITE_URL", "http://localhost:5000").rstrip('/')
if url.startswith(site_url) or url.startswith('/media/'):
path = url[len(site_url):] if url.startswith(site_url) else url
if path.startswith('/media/'):
path = path[len('/media/'):]
row = get_db(current_app).execute("SELECT id FROM media WHERE path = ?", (path,)).fetchone()
if row:
return row[0]
current_app.logger.warning(f"Photo URL not found in media: {url}")
return None
media = _fetch_remote_photo(url)
return media["id"] if media else None
MAX_INLINE_IMAGES = 20
def localize_inline_images(content: str) -> str:
"""
Copy images embedded in the text from other sites into the media library
and point the text at the copies (v2.16.0), so an article doesn't depend
on the client's or a CDN's host staying up. Best effort: an image that
can't be fetched keeps its URL.
"""
from html import escape
from starpunk.syndication import inline_images
if not content or "<img" not in content and "![" not in content:
return content
site_url = current_app.config.get("SITE_URL", "").rstrip("/")
remote = [url for url, _ in inline_images(content)
if url.startswith(("http://", "https://")) and not url.startswith(site_url + "/")]
for url in list(dict.fromkeys(remote))[:MAX_INLINE_IMAGES]:
media = _fetch_remote_photo(url)
if media:
local = f"{site_url}/media/{media['path']}"
# As written in Markdown, and as it may be escaped in HTML attributes
content = content.replace(url, local).replace(escape(url), local)
return content
def _save_uploads(files) -> list[dict]:
"""Photos uploaded in a multipart create request -> [{'media_id', 'alt'}]"""
from starpunk.media import save_media
result = []
for key in ("photo", "photo[]"):
for upload in (files.getlist(key) if files else []):
if upload and upload.filename:
try:
result.append({"media_id": save_media(upload.read(), upload.filename)["id"], "alt": ""})
except ValueError as e:
raise MicropubValidationError(f"Invalid photo {upload.filename}: {e}")
return result
def _resolve_photos(photos: list[dict]) -> tuple[list[int], list[str]]:
"""Photo dicts ({'url'|'media_id', 'alt'}) -> (media ids, captions), max 4"""
if len(photos) > MAX_PHOTOS:
current_app.logger.warning(
f"Micropub received {len(photos)} photos, truncating to {MAX_PHOTOS} per ADR-057"
)
media_ids, captions = [], []
for photo in photos:
if len(media_ids) == MAX_PHOTOS:
break
media_id = photo.get("media_id") or _media_id_for_url(photo["url"])
if not media_id:
# Don't create or change the post without it (v2.9.0)
raise MicropubValidationError(f"Could not get photo {photo.get('url')}")
# The same photo twice is shown once (v2.6.5)
if media_id not in media_ids:
media_ids.append(media_id)
captions.append(photo.get("alt", ""))
return media_ids, captions
def _attach_photos_to_note(note_id: int, photos: list[dict]) -> None:
"""Attach photos (by URL or uploaded media id) to a note, replacing any others"""
from starpunk.media import attach_media_to_note
media_ids, captions = _resolve_photos(photos)
attach_media_to_note(note_id, media_ids, captions)
def _note_photos(note) -> list[dict]:
"""A note's current photos as Micropub photo dicts"""
from starpunk.media import get_note_media
site_url = current_app.config.get("SITE_URL", "http://localhost:5000").rstrip('/')
return [
{"url": f"{site_url}/media/{m['path']}", "alt": m.get("caption") or "", "media_id": m["id"]}
for m in get_note_media(note.id)
]
def _check_type(data: dict) -> None:
"""Only h-entry is supported"""
h = _first(data.get("h"))
kind = _first(data.get("type"))
if (h and h != "entry") or (kind and kind != "h-entry"):
raise MicropubValidationError(f"Only h-entry posts are supported (got {h or kind})")
def _note_from_url(url: Optional[str], deleted: bool = False):
"""Find the note a URL points at (/note/<slug> on this site)"""
from urllib.parse import urlparse
from starpunk.database import get_db
if not url:
raise MicropubValidationError("No url provided")
site = urlparse(current_app.config.get("SITE_URL", ""))
parsed = urlparse(url)
if parsed.netloc and site.netloc and parsed.netloc != site.netloc:
raise MicropubValidationError("URL is not on this site")
parts = [p for p in parsed.path.split("/") if p]
if len(parts) != 2 or parts[0] not in ("note", "notes"):
raise MicropubValidationError("URL is not a post on this site")
slug = parts[1]
if deleted:
row = get_db(current_app).execute(
"SELECT id FROM notes WHERE slug = ? AND deleted_at IS NOT NULL", (slug,)
).fetchone()
if row is None:
raise MicropubError("not_found", "No deleted post at that URL", 404)
return slug
note = get_note(slug=slug)
if note is None:
raise MicropubError("not_found", "Post not found", 404)
return note
def handle_create(data: dict, token_info: dict, files=None):
"""
Handle Micropub create action
Creates a note using StarPunk's notes.py CRUD functions after
mapping Micropub properties to StarPunk's note format.
Args:
data: Raw request data (form or JSON)
token_info: Authenticated token information (me, client_id, scope)
files: Uploaded files for multipart requests (v2.4.0)
Returns:
Tuple of (response_body, status_code, headers)
"""
_require_scope(token_info, "create", "draft")
# A token with only the draft scope may create drafts (v2.9.0)
drafts_only = not check_scope("create", token_info.get("scope", ""))
_check_type(data)
# mp-slug and mp-syndicate-to are server commands, not properties. Form
# posts send them at the top level; JSON clients inside properties too.
commands = dict(data) if isinstance(data, dict) else {}
if isinstance(commands.get("properties"), dict):
commands.update({k: v for k, v in commands["properties"].items() if k.startswith("mp-")})
custom_slug = _first(commands.get("mp-slug"))
if custom_slug is not None and not isinstance(custom_slug, str):
raise MicropubValidationError("mp-slug must be a string")
# Crossposting only to the targets asked for: absent means none (v2.9.0)
requested_targets = []
for key in ("mp-syndicate-to", "mp-syndicate-to[]"):
if key in commands:
value = commands[key]
requested_targets += value if isinstance(value, list) else [value]
try:
properties = normalize_properties(data)
like_of = extract_url_property(properties, "like-of")
repost_of = extract_url_property(properties, "repost-of")
bookmark_of = extract_url_property(properties, "bookmark-of")
if sum(bool(u) for u in (like_of, repost_of, bookmark_of)) > 1:
raise MicropubValidationError("A post can only be one of a like, repost or bookmark")
for prop in UNSUPPORTED_MEDIA:
if properties.get(prop) or (files and (files.getlist(prop) or files.getlist(f"{prop}[]"))):
raise MicropubValidationError(f"{prop} posts are not supported")
has_content = _has_text(properties.get("content")) or _has_text(properties.get("summary"))
photos = extract_photos(properties) + _save_uploads(files)
title = extract_title(properties)
# Photo posts may have no text (v2.6.5), nor titled posts (v2.9.0)
content = (
extract_content(properties)
if has_content or not (like_of or repost_of or bookmark_of or photos or title)
else ""
)
content = localize_inline_images(drop_title_heading(content, title))
# A summary with content is the author's summary; alone it is the
# content (Post Type Discovery), as extract_content does (v2.16.0)
summary = extract_summary(properties) if _has_text(properties.get("content")) else None
tags = extract_tags(properties)
published_date = extract_published_date(properties)
published = extract_post_status(properties) and not extract_visibility_draft(properties)
if drafts_only:
published = False
in_reply_to = extract_in_reply_to(properties)
fmt = content_format(properties) if has_content else None
# Look up and download photos before the note exists, so a bad photo
# can't leave a half-made post behind (v2.6.5)
media_ids, captions = _resolve_photos(photos)
except MicropubError:
raise
except Exception as e:
current_app.logger.error(f"Property extraction failed: {e}")
raise MicropubValidationError("Could not read the post's properties")
note = None
try:
note = create_note(
content=content,
title=title,
summary=summary,
published=published,
created_at=published_date,
custom_slug=custom_slug,
tags=tags if tags else None,
in_reply_to=in_reply_to,
like_of=like_of,
repost_of=repost_of,
bookmark_of=bookmark_of,
has_media=bool(media_ids),
content_format=fmt,
)
if media_ids:
from starpunk.media import attach_media_to_note
attach_media_to_note(note.id, media_ids, captions)
# Crosspost after photos are attached (v2.1.0); drafts wait until published
from starpunk.syndication import resolve_targets, select_targets
select_targets(note.id, resolve_targets(requested_targets))
return "", 201, {"Location": absolute_url_for("public.note", slug=note.slug)}
except InvalidNoteDataError as e:
raise MicropubValidationError(str(e))
except MicropubError:
raise
except Exception as e:
current_app.logger.error(f"Failed to create note via Micropub: {e}")
# The client is told it failed, so don't leave the post up (v2.6.5)
if note is not None:
try:
from starpunk.notes import delete_note
delete_note(id=note.id, soft=False)
except Exception as cleanup:
current_app.logger.error(f"Could not remove failed note {note.slug}: {cleanup}")
raise MicropubError("server_error", "Failed to create post", status_code=500)
def handle_update(data: dict, token_info: dict):
"""
Handle Micropub update action (v2.4.0)
JSON body: {"action": "update", "url": ..., "replace": {...},
"add": {...}, "delete": [...] or {...}}. Edits follow to crossposts.
"""
from starpunk.syndication import note_changed
_require_scope(token_info, "update")
note = _note_from_url(_first(data.get("url")))
replace = data.get("replace") or {}
add = data.get("add") or {}
delete = data.get("delete") or {}
if not isinstance(replace, dict) or not isinstance(add, dict) or not isinstance(delete, (dict, list)):
raise MicropubValidationError("replace and add must be objects; delete an object or list")
for prop, values in list(replace.items()) + list(add.items()) + (
list(delete.items()) if isinstance(delete, dict) else []):
if not isinstance(values, list):
raise MicropubValidationError(f"Values for {prop} must be an array")
if not (replace or add or delete):
raise MicropubValidationError("An update needs replace, add or delete")
touched = set(replace) | set(add) | set(delete)
unsupported = sorted(touched - UPDATABLE)
if unsupported:
raise MicropubValidationError(f"Updating {', '.join(unsupported)} is not supported")
if set(add) - {"category", "photo"}:
raise MicropubValidationError("Only category and photo can be added to")
from starpunk.tags import get_note_tags
title, summary, body = note.title, note.summary, note.content
tags = [t["display_name"] for t in get_note_tags(note.id, entered_order=True)]
photos = _note_photos(note)
changes = {}
# Removals first, then replacements, then additions
if isinstance(delete, list):
for prop in delete:
if prop == "name":
title = None
elif prop == "summary":
summary = None
elif prop == "content":
body = ""
elif prop == "category":
tags = []
elif prop == "photo":
photos = []
elif prop == "in-reply-to":
changes["in_reply_to"] = ""
elif prop == "post-status":
changes["published"] = True
else:
for prop, values in delete.items():
if prop == "category":
drop = {v.lower() for v in values}
tags = [t for t in tags if t.lower() not in drop]
elif prop == "photo":
drop = {p["url"] for p in extract_photos({"photo": values})}
photos = [p for p in photos if p["url"] not in drop]
else:
raise MicropubValidationError(f"Can't delete individual values of {prop}")
if "content" in replace:
# Empty text is fine if the note keeps its photos; update_note checks (v2.6.5)
body = localize_inline_images(extract_content(replace)) if _has_text(replace["content"]) else ""
changes["content_format"] = content_format(replace) if body else None
if "name" in replace:
title = extract_title(replace)
if "summary" in replace:
summary = extract_summary(replace)
if "category" in replace:
tags = extract_tags(replace)
if "photo" in replace:
photos = extract_photos(replace)
if "in-reply-to" in replace:
changes["in_reply_to"] = extract_in_reply_to(replace) or ""
if "post-status" in replace:
changes["published"] = extract_post_status(replace)
if "category" in add:
known = {t.lower() for t in tags}
tags += [t for t in extract_tags(add) if t.lower() not in known]
if "photo" in add:
photos += extract_photos(add)
# Text may go only if photos stay, it has a title, or it's a like, repost
# or bookmark (v2.6.5)
if not (body or "").strip() and not (photos or title or note.reacts_to):
raise MicropubValidationError("A post needs text, a title or a photo")
# Photos must all resolve before anything changes (v2.9.0)
if "photo" in touched:
media_ids, captions = _resolve_photos(photos)
if title != note.title:
changes["title"] = title
if summary != note.summary:
changes["summary"] = summary
body = drop_title_heading(body, title)
if body != note.content:
changes["content"] = body
elif "content_format" in changes and changes["content_format"] == note.content_format:
del changes["content_format"]
if {"category"} & touched:
changes["tags"] = tags
try:
if changes:
update_note(id=note.id, has_media=bool(photos), **changes)
if "photo" in touched:
from starpunk.media import attach_media_to_note
attach_media_to_note(note.id, media_ids, captions)
note_changed(note.id) # attach_media_to_note tells WebSub
except InvalidNoteDataError as e:
raise MicropubValidationError(str(e))
except MicropubError:
raise
except Exception as e:
current_app.logger.error(f"Failed to update note via Micropub: {e}")
raise MicropubError("server_error", "Failed to update post", status_code=500)
return "", 204
def handle_delete(data: dict, token_info: dict, undelete: bool = False):
"""Handle Micropub delete / undelete (v2.4.0). Deletes are soft so they can be undone."""
_require_scope(token_info, "delete")
url = _first(data.get("url"))
try:
if undelete:
undelete_note(_note_from_url(url, deleted=True))
else:
delete_note(id=_note_from_url(url).id, soft=True)
except MicropubError:
raise
except Exception as e:
current_app.logger.error(f"Micropub {'undelete' if undelete else 'delete'} failed: {e}")
raise MicropubError("server_error", "Failed to change post", status_code=500)
return "", 204
def _syndicate_to() -> list:
"""Configured crosspost targets in Micropub syndicate-to form"""
from starpunk.syndication import get_targets
return [{"uid": t.uid, "name": t.name} for t in get_targets().values()]
def note_to_mf2(note, wanted: Optional[list] = None) -> dict:
"""
A note as Microformats2 JSON, the inverse of create
The title is returned as name and the author's summary as summary.
"""
from starpunk.syndication import get_note_syndications
content = note.content
props = {
# HTML-authored content comes back as HTML (3.7.2, v2.9.0)
"content": [{"html": content} if note.content_format == "html" else content],
"published": [iso_utc(note.created_at)],
"url": [absolute_url_for("public.note", slug=note.slug)],
"post-status": ["published" if note.published else "draft"],
}
if note.title:
props["name"] = [note.title]
if note.summary:
props["summary"] = [note.summary]
from starpunk.tags import get_note_tags
tags = get_note_tags(note.id, entered_order=True)
if tags:
props["category"] = [tag["display_name"] for tag in tags]
if getattr(note, "in_reply_to", None):
props["in-reply-to"] = [note.in_reply_to]
if getattr(note, "like_of", None):
props["like-of"] = [note.like_of]
if getattr(note, "repost_of", None):
props["repost-of"] = [note.repost_of]
if getattr(note, "bookmark_of", None):
props["bookmark-of"] = [note.bookmark_of]
if not content.strip():
del props["content"] # photo posts, likes, reposts and bookmarks without text
photos = _note_photos(note)
if photos:
props["photo"] = [{"value": p["url"], "alt": p["alt"]} for p in photos]
synced = [s["remote_url"] for s in get_note_syndications(note.id) if s.get("remote_url")]
if synced:
props["syndication"] = synced
if wanted:
return {"properties": {k: v for k, v in props.items() if k in wanted}}
return {"type": ["h-entry"], "properties": props}
def _all_categories(prefix: str = "") -> list:
"""Tags on posts that exist (drafts included), most used first (q=category)"""
from starpunk.database import get_db
# Inner joins: tags left behind by edits or soft-deleted posts don't count
rows = get_db(current_app).execute(
"""
SELECT t.display_name, COUNT(*) AS uses
FROM tags t
JOIN note_tags nt ON nt.tag_id = t.id
JOIN notes n ON n.id = nt.note_id AND n.deleted_at IS NULL
GROUP BY t.id ORDER BY uses DESC, t.display_name
"""
).fetchall()
prefix = prefix.lower()
return [r["display_name"] for r in rows if not prefix or prefix in r["display_name"].lower()]
QUERIES = ["config", "source", "syndicate-to", "category"]
def handle_query(args, token_info: dict):
"""
Handle Micropub query endpoints
Supports:
- q=config: Server configuration
- q=source&url=...[&properties[]=...]: One post in Microformats2 JSON
- q=source (no url) [&limit=N&offset=N]: Recent posts, drafts included
- q=syndicate-to: Crosspost targets
- q=category[&filter=...]: Tags in use
Args:
args: Query arguments (werkzeug MultiDict or plain dict)
"""
def get_list(key):
if hasattr(args, "getlist"):
return args.getlist(key) + args.getlist(f"{key}[]")
value = args.get(key) or args.get(f"{key}[]")
return value if isinstance(value, list) else ([value] if value else [])
q = args.get("q")
# Posts (drafts included) and tags are for apps that may post (v2.9.0);
# config and syndicate-to are fine for any token
if q in ("source", "category"):
_require_scope(token_info, "create", "update", "delete", "draft")
if q == "config":
site_url = current_app.config.get("SITE_URL", "http://localhost:5000").rstrip('/')
return jsonify({
"media-endpoint": f"{site_url}/micropub/media",
"syndicate-to": _syndicate_to(),
"q": QUERIES,
"post-types": [
{"type": "note", "name": "Note", "properties": ["content"]},
{"type": "article", "name": "Article", "properties": ["name", "content"]},
{"type": "photo", "name": "Photo", "properties": ["photo"]},
{"type": "reply", "name": "Reply", "properties": ["in-reply-to", "content"]},
{"type": "like", "name": "Like", "properties": ["like-of"]},
{"type": "repost", "name": "Repost", "properties": ["repost-of", "content"]},
{"type": "bookmark", "name": "Bookmark", "properties": ["bookmark-of", "content"]},
],
}), 200
if q == "source":
url = args.get("url")
wanted = get_list("properties")
if url:
try:
note = _note_from_url(url)
except MicropubError as e:
return error_response("invalid_request" if e.status_code == 400 else e.error,
e.error_description, e.status_code)
return jsonify(note_to_mf2(note, wanted)), 200
try:
limit = max(1, min(int(args.get("limit", 10)), 50))
offset = max(0, int(args.get("offset", 0)))
except ValueError:
return error_response("invalid_request", "limit and offset must be numbers")
notes = list_notes(published_only=False, limit=limit, offset=offset)
items = [note_to_mf2(n, wanted) for n in notes]
return jsonify({"items": items}), 200
if q == "syndicate-to":
return jsonify({"syndicate-to": _syndicate_to()}), 200
if q == "category":
return jsonify({"categories": _all_categories(args.get("filter") or "")}), 200
return error_response("invalid_request", f"Unknown query: {q}" if q else "Missing q parameter")