Files
StarPunk/docs/projectplan/BACKLOG.md
T
PhilandClaude Opus 5.5 0716984958 docs: Bring all documentation up to date for v2.10.1
- architecture/: overview, technology stack, auth (OIDC + built-in
  IndieAuth), syndication (POSSE) rewritten; new database.md,
  deployment.md and indieweb-protocols.md; legacy stack marked historical
- decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections
  (superseded auth ADRs, proposed -> accepted); INDEX rebuilt
- design/: reconstructed the v1.6.0 documents the webmention code cites;
  reports for 18 v2 releases without a design folder; INDEX rebuilt
- projectplan/: BACKLOG rewritten (shipped items removed, open issues from
  the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX
- standards/: development setup (uv, tests, DEV_MODE), testing (CI test
  stage), git and release flow, versioning, coding standards, cookies
- README, CLAUDE.md, .env.example (every setting the code reads, with
  defaults) brought up to date
- 137 broken links repaired (old absolute paths, moved files); stale ADR
  references in code comments corrected (comments only)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 12:40:19 -07:00

15 KiB
Raw Blame History

StarPunk Backlog

Last Updated: 2026-11-03 (current release: v2.10.1)

These are the open features and bugs, sorted by priority. Each item was checked against the code at v2.10.1. Work that has shipped is listed per release in vX.Y.Z/RELEASE.md and in CHANGELOG.md.

Priority Levels

  • Critical - Items that break existing functionality
  • High - Security, data-integrity or correctness bugs; important features
  • Medium - Planned features and spec gaps with visible effect
  • Low - Nice-to-have, minor spec deviations, deferred ideas

Critical

No critical items


High

SQLite foreign keys are not enforced (ON DELETE CASCADE is inert)

  • Description: No connection runs PRAGMA foreign_keys = ON, so the ON DELETE CASCADE clauses in the schema do nothing. When a note is deleted from the admin (a hard delete), its note_tags, note_media, syndications and webmention rows stay behind. delete_media() relies on the cascade to remove media_variants and note_media rows, so those are left orphaned too. Before turning the pragma on, check for existing orphan rows and add a migration that cleans them up. Each cascade also needs tests.
  • Where: starpunk/database/ (connection setup/pool), starpunk/notes.py (delete_note, hard delete), starpunk/media.py (delete_media), migrations/007–010, 016
  • Source: v2.10.x review; confirmed in code (there is no foreign_keys pragma anywhere in starpunk/)
  • Description: Admin forms (create/edit/delete notes, webmention moderation, token revocation) and the IndieAuth consent form rely only on the SameSite=Lax session cookie. Lax blocks cross-site POSTs in current browsers, but a per-session CSRF token is the standard defence and covers older clients and same-site subdomains.
  • Where: starpunk/routes/admin.py, starpunk/routes/indieauth.py, templates/admin/*
  • Source: Documentation refresh 2026-11-03 (architecture review)

Two outbound fetches don't use the hardened fetcher

  • Description: IndieAuth client-metadata discovery (indieauth.fetch_client_redirect_uris) checks only the first URL, then uses httpx.get(follow_redirects=True): redirect hops aren't checked and DNS isn't pinned. Crosspost link cards and Threads image fetches (syndication._fetch_public) check each hop but don't pin DNS, and their 10 s timeout is per read. Move both to webmention_ssrf.safe_get, as Webmention, WebSub and Micropub photo downloads already do.
  • Where: starpunk/indieauth.py, starpunk/syndication.py
  • Source: Documentation refresh 2026-11-03

FLASK_DEBUG defaults to on

  • Description: config.py reads FLASK_DEBUG with default "1" (and FLASK_ENV defaults to development); the runtime image sets neither. Production is safe only because the deployment sets FLASK_DEBUG=0. Default to off, or set it in the Containerfile runtime stage.
  • Where: starpunk/config.py, Containerfile
  • Source: Documentation refresh 2026-11-03 (production verified: DEBUG is False there)

Rate limiters are per process

  • Description: RateLimiter keeps its counters in memory, and gunicorn runs 4 workers. The WebSub hub limit of 30/min is therefore really 4×30/min, and the webmention endpoint limit is multiplied the same way. Consider a counter stored in SQLite that all workers share.
  • Where: starpunk/rate_limiter.py, starpunk/routes/websub.py, starpunk/routes/webmention.py, Containerfile (--workers 4)
  • Source: ADR-071 (Consequences: rate limiting bounds subscriber-chosen requests); v2.10.1 review

Medium

Admin editor cannot clear all tags

  • Description: When a note is saved with an empty tag field, the route passes tags=None. update_note treats that as "unchanged", so the last tags can't be removed from the editor.
  • Where: starpunk/routes/admin.py (edit POST: tags=tags if tags else None), starpunk/notes.py (update_note)
  • Source: Old backlog (v1.3.0 follow-up); still present

Media captions not escaped in RSS HTML

  • Description: The RSS description embeds <img alt="{caption}"> without escaping the caption. A caption containing " or < breaks the item's HTML.
  • Where: starpunk/feeds/rss.py (two places, ~lines 136 and 277)
  • Source: Old backlog (Architect Review 2.2.10); still present

No rate limiting on upload endpoints

  • Description: Media uploads (/admin/new and the Micropub media endpoint) have no rate limit. Both require authentication, so the risk comes from a leaked token or session.
  • Where: starpunk/routes/admin.py, starpunk/routes/micropub.py
  • Source: Old backlog (Architect Review security assessment); still present

Micropub: more updatable properties

  • Description: add works only for category and photo. published, syndication and location can't be updated.
  • Where: starpunk/micropub.py
  • Source: docs/design/v2.9.0/2026-11-03-micropub-review.md (Kept as is)

Micropub: insufficient_scope returns 403

  • Description: StarPunk follows RFC 6750 and returns 403, but the Micropub spec's error table says 401. Choose one: keep 403 and document why, or switch to 401.
  • Where: starpunk/micropub.py, starpunk/routes/micropub.py
  • Source: docs/design/v2.9.0/2026-11-03-micropub-review.md (Kept as is)

Webmentions with status error are never retried

  • Description: When a received webmention fails unexpectedly or temporarily, it is stored as error. It is never processed again unless the sender sends it again. Add a limited number of retries with backoff.
  • Where: starpunk/webmention_worker.py
  • Source: docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md (Known limits)

IndieAuth scope handling

  • Description: The metadata's scopes_supported omits draft, though Micropub honours it and the consent screen grants it. Requested scopes aren't filtered, so unknown scopes are granted (and have no effect).
  • Where: starpunk/indieauth.py, starpunk/routes/indieauth.py
  • Source: Documentation refresh 2026-11-03

Webmention source DNS failures are permanent

  • Description: A DNS failure while fetching a webmention source becomes ValueError and marks the mention invalid/error without retry; the WebSub worker now retries ResolutionError. Treat it as transient here too.
  • Where: starpunk/webmention_processor.py, starpunk/webmention_worker.py
  • Source: v1.6.0 design reconstruction (docs/design/v1.6.0/background-worker.md)

Webmention rate limiter never cleaned up

  • Description: cleanup_rate_limiters() is never called, so per-IP and per-domain keys accumulate for the life of each process.
  • Where: starpunk/rate_limiter.py, starpunk/routes/webmention.py
  • Source: v1.6.0 design reconstruction

Atom and JSON Feed not linked from pages

  • Description: base.html advertises only /feed (as RSS) and OPML with rel=alternate; add <link rel="alternate"> for /feed.atom and /feed.json so readers can pick a format.
  • Where: templates/base.html
  • Source: Documentation refresh 2026-11-03

Housekeeping in the repository

  • Description: compose.yaml is stale (image: starpunk:0.6.0, VERSION=0.6.0 would override the real version, unused ENVIRONMENT); the root dev_auth.py duplicates starpunk/dev_auth.py and is unused; LICENSE says "Copyright (c) 2024 [Your Name]"; test.ini contains a private host name; lxml and python-dateutil are used directly but only installed as dependencies of other packages, while pytest is pinned in the production requirements.txt.
  • Where: compose.yaml, dev_auth.py, LICENSE, test.ini, requirements*.txt
  • Source: Documentation refresh 2026-11-03

Backfeed responses to crossposts

  • Description: Idea: bring likes, boosts and replies to StarPunk's own crossposts back to the note as responses. Two options: poll GoToSocial (the token would need a read scope), or rely on Bridgy, which sends webmentions. Since v2.8.0, StarPunk ignores webmentions from a note's own crossposts, so that rule would need to change to work with Bridgy.
  • Where: starpunk/syndication.py, starpunk/webmention_worker.py
  • Source: v2.8.0 microformats2 review discussion

Tag-filtered feeds

  • Description: Tag pages are h-feeds and WebSub topics, but there are no RSS, Atom or JSON feeds per tag (for example /tag/python/feed.atom). Tag pages also have no pagination, and the editor has no tag autocomplete.
  • Where: starpunk/routes/public.py, starpunk/feeds/, templates/admin/
  • Source: Old backlog (Tag enhancements)

Low

Micropub: location / checkin ignored

  • Description: These properties are accepted but dropped, which spec 3.3.5 allows.
  • Where: starpunk/micropub.py
  • Source: docs/design/v2.9.0/2026-11-03-micropub-review.md

Micropub: video and audio unsupported

  • Description: video and audio are refused with 400 (UNSUPPORTED_MEDIA). Supporting them would need upload handling, HTML5 embedding, Media RSS and possibly podcast feeds (see ADR-059).
  • Where: starpunk/micropub.py, starpunk/media.py
  • Source: docs/design/v2.9.0/2026-11-03-micropub-review.md; old backlog (Audio/Podcast, Video)

Micropub: GET access_token query parameter accepted

  • Description: Tokens sent in the URL end up in logs and proxies. Consider refusing them.
  • Where: starpunk/micropub.py (extract_bearer_token)
  • Source: docs/design/v2.9.0/2026-11-03-micropub-review.md

Person tags (p-category h-card) unsupported

  • Description: h-card objects in category are silently ignored.
  • Where: starpunk/micropub.py, templates
  • Source: docs/design/v2.8.0/2026-11-03-microformats2-review.md (Not done)

Reply-context h-cite lacks author h-card, name and published

  • Description: The u-in-reply-to h-cite shows the cached author name as plain text. It has no p-author h-card, p-name or dt-published.
  • Where: templates/note.html, starpunk/reply_context.py
  • Source: docs/design/v2.8.0/2026-11-03-microformats2-review.md (Not done)

Photo alt falls back to "Image"

  • Description: A photo-only post with no caption still gets alt="Image".
  • Where: templates/partials/media.html
  • Source: docs/design/v2.8.0/2026-11-03-microformats2-review.md (Not done)

Old webmentions lack source details

  • Description: Webmentions received before migration 014 keep NULL source details (the original post's URL and published time) until they are re-validated. A one-off re-validation would fill them in.
  • Where: starpunk/webmention_worker.py, migration 014
  • Source: docs/design/v2.8.0/2026-11-03-microformats2-review.md (Not done)

Homepage webmentions refused

  • Description: Mentions of the home page are refused with 400. They are not stored or shown anywhere.
  • Where: starpunk/routes/webmention.py
  • Source: docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md (Known limits)

Webmention discovery ignores HTTP cache headers

  • Description: Endpoint discovery doesn't apply HTTP caching (spec 5.3). Targets are only fetched when a note is created, edited or deleted, so the extra cost is small.
  • Where: starpunk/webmention_sender.py
  • Source: docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md (Known limits)

410 tombstone page has no microformats

  • Description: The "This post has been deleted" page is a generic error page. It could include an h-entry with the post's URL and deletion state.
  • Where: templates/410.html
  • Source: docs/design/v2.7.0/2026-11-03-webmention-spec-compliance.md (Known limits)

Slow and previously flaky tests

  • Description: tests/test_migration_race_condition.py takes about 5 minutes. 8 tests were flaky or failing until v2.7.1. Speed them up (mock the waits) or mark them slow so the default test run stays fast.
  • Where: tests/test_migration_race_condition.py
  • Source: v2.7.1 release; ADR-012

Animated WebP not detected

  • Description: Animated GIFs are detected and handled; animated WebP is not.
  • Where: starpunk/media.py
  • Source: Old backlog (Architect Review 2.2.2); still present

MAX_DIMENSION not configurable

  • Description: MAX_DIMENSION = 12000 is a constant.
  • Where: starpunk/media.py
  • Source: Old backlog (Developer Review M4)

N+1 queries on secondary pages

  • Description: Tag pages and a few single-note views load media one note at a time. Load it in batches if this becomes a problem.
  • Where: starpunk/routes/public.py (tag page), starpunk/routes/admin.py, starpunk/models.py, starpunk/tags.py
  • Source: Old backlog (v1.5.0 scoping)

Unused settings and legacy tables

  • Description: NOTES_PATH is read and its folder created, but notes are always written under DATA_PATH/notes. SITE_AUTHOR is required but shown nowhere. INITIAL_SCHEMA_SQL recreates the unused tokens and authorization_codes tables (dropped by migration 004) on every start, and auth_state is unused. Version fallbacks are stale (author_discovery.py "1.2.0", base.html "0.5.0").
  • Where: starpunk/config.py, starpunk/utils.py, starpunk/database/schema.py, starpunk/author_discovery.py, templates/base.html
  • Source: Documentation refresh 2026-11-03 (docs/architecture/database.md, deployment.md)

Media library and crosspost settings UI

  • Description: There is no admin page to browse or delete media, and crosspost targets can only be configured through environment variables.
  • Where: starpunk/routes/admin.py
  • Source: Old backlog (Media enhancements, POSSE configuration UI)

Deferred indefinitely

  • Static site generation (conflicts with Micropub)
  • Multi-language UI, advanced analytics, WYSIWYG editor, mobile app
  • Comments system (webmentions cover it)
  • CDN integration, gallery views

Done since the last update (2025-12-17)

These items were removed from the backlog because they have shipped:

  • POSSE: GoToSocial (v2.1.0), Bluesky (v2.2.0), Threads (v2.6.0)
  • Webmentions: receive, send, display and moderation (v1.6.0); fixed and made spec-compliant in v2.6.8–v2.7.2
  • Reply contexts, replies, likes, reposts and bookmarks (v2.4.0, v2.5.0, v2.9.0)
  • Photo posts without text (v2.6.5); thumbnails and image variants (v1.4.0)
  • PKCE for IndieAuth login: replaced by OIDC admin login with PKCE (v2.0.0, ADR-064)
  • HEIC conversion quality: no longer hardcoded; HEIC images now go through the normal optimisation tiers
  • media.py module docstring now says 12000px
  • Fresh feeds and push updates: WebSub (v2.10.0, v2.10.1)