feat(endpoint-microsub): add Microsub endpoint for feed reading

packages/endpoint-auth/lib/controllers/authorization.js

@@ -2,6 +2,7 @@ import { IndiekitError } from "@indiekit/error";
 import { getCanonicalUrl } from "@indiekit/util";
 
 import { getClientInformation } from "../client.js";
+import { getProfileInformation } from "../profile.js";
 import { createRequestUri } from "../pushed-authorization-request.js";
 import { validateRedirect } from "../redirect.js";
 
@@ -102,13 +103,31 @@ export const authorizationController = {
    * @see {@link https://indieauth.spec.indieweb.org/#profile-url-response}
    */
   async post(request, response) {
-    const profileToken = { me: request.verifiedToken.me };
+    const { me, scope } = request.verifiedToken;
+    const profileToken = { me };
+
+    // Include profile information if profile scope was requested
+    if (scope && scope.includes("profile")) {
+      const profile = await getProfileInformation(me);
+      if (profile) {
+        profileToken.profile = profile;
+      }
+    }
 
     if (request.accepts("application/json")) {
       response.json(profileToken);
     } else {
       response.set("content-type", "application/x-www-form-urlencoded");
-      response.send(new URLSearchParams(profileToken).toString());
+      // Flatten profile for form-urlencoded response
+      const parameters = new URLSearchParams();
+      for (const [key, value] of Object.entries(profileToken)) {
+        if (key === "profile" && typeof value === "object") {
+          parameters.set("profile", JSON.stringify(value));
+        } else {
+          parameters.set(key, String(value));
+        }
+      }
+      response.send(parameters.toString());
     }
   },
 };

packages/endpoint-auth/lib/controllers/token.js

@@ -1,3 +1,4 @@
+import { getProfileInformation } from "../profile.js";
 import { signToken } from "../token.js";
 
 export const tokenController = {
@@ -9,7 +10,7 @@ export const tokenController = {
    * @see {@link https://indieauth.spec.indieweb.org/#redeeming-the-authorization-code}
    * @see {@link https://indieauth.spec.indieweb.org/#access-token-response}
    */
-  post(request, response) {
+  async post(request, response) {
     const { me, scope } = request.verifiedToken;
 
     const tokenData = { me, ...(scope && { scope }) };
@@ -19,11 +20,29 @@ export const tokenController = {
       ...tokenData,
     };
 
+    // Include profile information if profile scope was requested
+    if (scope && scope.includes("profile")) {
+      const profile = await getProfileInformation(me);
+      if (profile) {
+        accessToken.profile = profile;
+      }
+    }
+
     if (request.accepts("application/json")) {
       response.json(accessToken);
     } else {
       response.set("content-type", "application/x-www-form-urlencoded");
-      response.send(new URLSearchParams(accessToken).toString());
+      // Flatten profile for form-urlencoded response
+      const parameters = new URLSearchParams();
+      for (const [key, value] of Object.entries(accessToken)) {
+        if (key === "profile" && typeof value === "object") {
+          // Encode profile as JSON string for form-urlencoded
+          parameters.set("profile", JSON.stringify(value));
+        } else {
+          parameters.set(key, String(value));
+        }
+      }
+      response.send(parameters.toString());
     }
   },
 };

packages/endpoint-auth/lib/profile.js

@@ -0,0 +1,100 @@
+import { mf2 } from "microformats-parser";
+
+/**
+ * Get profile information from h-card on user's site
+ * @param {string} me - User's profile URL
+ * @returns {Promise<object|undefined>} Profile information (name, url, photo)
+ * @see {@link https://indieauth.spec.indieweb.org/#profile-information}
+ */
+export const getProfileInformation = async (me) => {
+  try {
+    const response = await fetch(me);
+    if (!response.ok) {
+      return;
+    }
+
+    const body = await response.text();
+    const { items } = mf2(body, { baseUrl: me });
+
+    // Find the representative h-card
+    // Per spec: h-card with u-url matching the profile URL
+    for (const item of items) {
+      if (item.type?.includes("h-card")) {
+        const { properties } = item;
+
+        // Check if this h-card represents the user (url matches me)
+        const urls = properties.url || [];
+        const hasMatchingUrl = urls.some((url) => {
+          const urlString = typeof url === "object" ? url.value : url;
+          return urlString === me || urlString === me.replace(/\/$/, "");
+        });
+
+        if (hasMatchingUrl || urls.length === 0) {
+          const profile = {};
+
+          // Extract name
+          if (properties.name?.[0]) {
+            const name = properties.name[0];
+            profile.name = typeof name === "object" ? name.value : name;
+          }
+
+          // Extract url
+          if (properties.url?.[0]) {
+            const url = properties.url[0];
+            profile.url = typeof url === "object" ? url.value : url;
+          } else {
+            profile.url = me;
+          }
+
+          // Extract photo
+          if (properties.photo?.[0]) {
+            const photo = properties.photo[0];
+            profile.photo = typeof photo === "object" ? photo.value : photo;
+          }
+
+          // Only return if we have at least some profile data
+          if (profile.name || profile.photo) {
+            return profile;
+          }
+        }
+      }
+    }
+
+    // If no h-card found, try looking in nested items
+    for (const item of items) {
+      if (item.children) {
+        for (const child of item.children) {
+          if (child.type?.includes("h-card")) {
+            const { properties } = child;
+            const profile = {};
+
+            if (properties.name?.[0]) {
+              const name = properties.name[0];
+              profile.name = typeof name === "object" ? name.value : name;
+            }
+
+            if (properties.url?.[0]) {
+              const url = properties.url[0];
+              profile.url = typeof url === "object" ? url.value : url;
+            } else {
+              profile.url = me;
+            }
+
+            if (properties.photo?.[0]) {
+              const photo = properties.photo[0];
+              profile.photo = typeof photo === "object" ? photo.value : photo;
+            }
+
+            if (profile.name || profile.photo) {
+              return profile;
+            }
+          }
+        }
+      }
+    }
+
+    return;
+  } catch {
+    return;
+  }
+};

packages/endpoint-auth/lib/scope.js

@@ -1,7 +1,7 @@
 export const scopes = {
   // IndieAuth scopes
   email: { supported: false },
-  profile: { supported: false },
+  profile: { supported: true },
   // Micropub scopes
   create: { supported: true },
   draft: { supported: true },

packages/endpoint-auth/test/unit/profile.js

@@ -0,0 +1,12 @@
+import { strict as assert } from "node:assert";
+import { describe, it } from "node:test";
+
+import { getProfileInformation } from "../../lib/profile.js";
+
+describe("endpoint-auth/lib/profile", () => {
+  it("Returns undefined for non-existent URL", async () => {
+    const result = await getProfileInformation("https://nonexistent.example");
+
+    assert.equal(result, undefined);
+  });
+});

packages/endpoint-microsub/README.md

@@ -0,0 +1,111 @@
+# @indiekit/endpoint-microsub
+
+Microsub endpoint for Indiekit. Enables subscribing to feeds and reading content using the [Microsub protocol](https://indieweb.org/Microsub).
+
+## Features
+
+- **Full Microsub API** - Channels, timeline, follow/unfollow, search, preview, mute, block
+- **Multiple feed formats** - RSS 1.0/2.0, Atom, JSON Feed, h-feed (Microformats)
+- **External client support** - Works with Monocle, Together, IndiePass
+- **Built-in reader UI** - Social reading experience in Indiekit admin
+- **Real-time updates** - Server-Sent Events (SSE) and WebSub integration
+- **Adaptive polling** - Tier-based feed fetching inspired by Ekster
+- **Direct webmention receiving** - Notifications channel for mentions
+
+## Installation
+
+`npm install @indiekit/endpoint-microsub`
+
+## Usage
+
+Add `@indiekit/endpoint-microsub` to the list of plugins in your configuration:
+
+```js
+export default {
+  plugins: ["@indiekit/endpoint-microsub"],
+};
+```
+
+## Options
+
+| Option       | Type     | Description                                                      |
+| :----------- | :------- | :--------------------------------------------------------------- |
+| `mountPath`  | `string` | Path to mount Microsub API. _Optional_, defaults to `/microsub`. |
+| `readerPath` | `string` | Path to mount reader UI. _Optional_, defaults to `/reader`.      |
+
+## Endpoints
+
+### Microsub API
+
+The main Microsub endpoint is mounted at `/microsub` (configurable).
+
+**Discovery**: Add this to your site's `<head>`:
+
+```html
+<link rel="microsub" href="https://yoursite.com/microsub" />
+```
+
+### Supported actions
+
+| Action     | GET | POST | Description                                    |
+| :--------- | :-- | :--- | :--------------------------------------------- |
+| `channels` | ✓   | ✓    | List, create, update, delete, reorder channels |
+| `timeline` | ✓   | ✓    | Get timeline, mark read/unread, remove items   |
+| `follow`   | ✓   | ✓    | List followed feeds, subscribe to new feeds    |
+| `unfollow` | -   | ✓    | Unsubscribe from feeds                         |
+| `search`   | ✓   | ✓    | Feed discovery and full-text search            |
+| `preview`  | ✓   | ✓    | Preview feed before subscribing                |
+| `mute`     | ✓   | ✓    | List muted URLs, mute/unmute                   |
+| `block`    | ✓   | ✓    | List blocked URLs, block/unblock               |
+| `events`   | ✓   | -    | Server-Sent Events stream                      |
+
+### Reader UI
+
+The built-in reader is mounted at `/reader` (configurable) and provides:
+
+- Channel list with unread counts
+- Timeline view with items
+- Mark as read on scroll/click
+- Like/reply/repost via Micropub
+- Channel settings (filters)
+- Compose modal
+
+### WebSub callbacks
+
+WebSub hub callbacks are handled at `/microsub/websub/:id`.
+
+### Webmention receiving
+
+Direct webmentions can be sent to `/microsub/webmention`.
+
+## MongoDB Collections
+
+This plugin creates the following collections:
+
+- `microsub_channels` - User's feed channels
+- `microsub_feeds` - Subscribed feeds
+- `microsub_items` - Timeline entries
+- `microsub_notifications` - Webmention notifications
+- `microsub_muted` - Muted URLs
+- `microsub_blocked` - Blocked URLs
+
+## Dependencies
+
+- **feedparser** - RSS/Atom parsing
+- **microformats-parser** - h-feed parsing
+- **ioredis** - Redis client (optional, for caching/pub-sub)
+- **sanitize-html** - XSS prevention
+
+## External Clients
+
+This endpoint is compatible with:
+
+- [Monocle](https://monocle.p3k.io/) - Web-based reader
+- [Together](https://together.tpxl.io/) - Web-based reader
+- [IndiePass](https://indiepass.app/) - Mobile/desktop app (archived)
+
+## References
+
+- [Microsub Specification](https://indieweb.org/Microsub-spec)
+- [Ekster](https://github.com/pstuifzand/ekster) - Reference implementation in Go
+- [Aperture](https://github.com/aaronpk/Aperture) - Popular Microsub server in PHP