Asterism Reader

A self-hosted, single-owner reader for a WordPress-powered social feed. Asterism connects to your WordPress site through Enable Mastodon Apps, with Friends providing incoming posts and ActivityPub providing federation. Each person deploys their own instance; this is not a shared, multi-user service.

Read a responsive Mosaic feed, open conversations, reply, like, bookmark, boost public posts, follow people, search available history, and organize follows into lists. Passkeys protect access, with mandatory backup-code confirmation and recovery. Reading preferences sync through the account database. The installable PWA caches the public shell only; feeds and credentials are never available offline.

Created using an AI agent

This app was created using an AI coding agent. If you have concerns about code quality, review the code carefully before using or deploying it.

Requirements

• Node.js 24 or later and npm, or a Docker host.
• A WordPress site with the official Enable Mastodon Apps, Friends, and ActivityPub plugins configured for your account.
• For production: a permanent HTTPS origin, one application process/replica, and persistent writable storage for SQLite. Any host meeting these requirements can run Asterism.

Read WordPress setup and compatibility before connecting. Feed availability, search coverage, and federation behavior depend on your plugins and their configuration.

Run locally

From a clone of this repository, replace the example URL with your WordPress site's public URL:

npm ci
npm run setup:local -- https://wordpress.example.com
npm run dev

The setup command creates .env and a private 24-hour invitation in work/local-setup-url.txt, refuses existing files, and never prints secrets. Open that invitation yourself, create a passkey, save the backup codes, and explicitly confirm that you saved them. The app runs at http://localhost:4320. HTTP WordPress URLs are accepted only for loopback addresses in development.

Connecting a local reader to a real WordPress site can perform real actions after you authorize it. For isolated development, use the mocked browser fixture described in testing.

Deploy your own instance

npm ci
npm run setup:production -- https://reader.example.com https://wordpress.example.com

This creates work/production.env and work/production-setup-url.txt, independently of the local .env. Provision your host using those private values, attach persistent storage, and enroll on your permanent HTTPS hostname. Edit OWNER_NAME before enrollment if you want a different passkey-manager label.

See deployment and backups for Docker and Node instructions, the full configuration reference, and upgrade guidance. Passkeys are bound to the reader hostname: do not reuse an enrolled development database at a production origin.

Development and validation

npm ci
npm run validate

validate runs formatting checks, TypeScript checking, a production build, and the automated tests locally. Build runs before tests because the PWA suite checks generated assets. There is no separate lint tool configured. Tests use disposable databases and injected WordPress responses; one optional real-WordPress test is skipped unless explicitly enabled for a disposable local site.

Testing maps test files to behavior and explains browser acceptance. Architecture documents request flow, authentication states, persistence, and extension points. Contributing covers the development workflow.

Features and limits

• Lists and Mastodon lists.csv imports are local to the owner database. Imports merge memberships without sending follow requests; unmatched accounts remain available for review. Re-import preserves deliberate edits and removals.
• Feed/list filtering scans bounded pages and returns a continuation even for sparse results. People search covers loaded follows; post and hashtag search depend on WordPress history. There is no independent full-text index or background sync worker.
• Author history falls back to filtering the home timeline if WordPress returns an empty account-status page. It cannot retrieve a remote author's complete archive.
• Link previews use bounded, authenticated requests, public-address validation, and sanitized metadata. Sensitive posts wait for disclosure. Failed previews leave the original link usable.
• Passkey names are generated by the app; renaming saved credentials is not implemented. OWNER_NAME controls the account label during new passkey registration.
• Real-device passkey support and your plugin combination require deployment acceptance; mocked tests do not establish live compatibility.

License

Asterism Reader is free software under the GNU General Public License, version 3 or (at your option) any later version (GPL-3.0-or-later). See LICENSE. Third-party dependencies retain their own licenses; see third-party notices.