@rmdes/indiekit-endpoint-microsub 1.0.0-beta.1

package/lib/websub/handler.js

@@ -0,0 +1,163 @@
+/**
+ * WebSub callback handler
+ * @module websub/handler
+ */
+
+import { parseFeed } from "../feeds/parser.js";
+import { processFeed } from "../polling/processor.js";
+import { getFeedBySubscriptionId, updateFeedWebsub } from "../storage/feeds.js";
+
+import { verifySignature } from "./subscriber.js";
+
+/**
+ * Verify WebSub subscription
+ * GET /microsub/websub/:id
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function verify(request, response) {
+  const { id } = request.params;
+  const {
+    "hub.topic": topic,
+    "hub.challenge": challenge,
+    "hub.lease_seconds": leaseSeconds,
+  } = request.query;
+
+  if (!challenge) {
+    return response.status(400).send("Missing hub.challenge");
+  }
+
+  const { application } = request.app.locals;
+  const feed = await getFeedBySubscriptionId(application, id);
+
+  if (!feed) {
+    return response.status(404).send("Subscription not found");
+  }
+
+  // Verify topic matches (allow both feed URL and topic URL)
+  const expectedTopic = feed.websub?.topic || feed.url;
+  if (topic !== feed.url && topic !== expectedTopic) {
+    return response.status(400).send("Topic mismatch");
+  }
+
+  // Update lease seconds if provided
+  if (leaseSeconds) {
+    const seconds = Number.parseInt(leaseSeconds, 10);
+    if (seconds > 0) {
+      await updateFeedWebsub(application, id, {
+        hub: feed.websub?.hub,
+        topic: expectedTopic,
+        leaseSeconds: seconds,
+        secret: feed.websub?.secret,
+      });
+    }
+  }
+
+  // Mark subscription as active (not pending)
+  if (feed.websub?.pending) {
+    await updateFeedWebsub(application, id, {
+      hub: feed.websub?.hub,
+      topic: expectedTopic,
+      secret: feed.websub?.secret,
+      leaseSeconds: feed.websub?.leaseSeconds,
+      pending: false,
+    });
+  }
+
+  console.log(`[Microsub] WebSub subscription verified for ${feed.url}`);
+
+  // Return challenge to verify subscription
+  response.type("text/plain").send(challenge);
+}
+
+/**
+ * Receive WebSub notification
+ * POST /microsub/websub/:id
+ * @param {object} request - Express request
+ * @param {object} response - Express response
+ */
+export async function receive(request, response) {
+  const { id } = request.params;
+  const { application } = request.app.locals;
+
+  const feed = await getFeedBySubscriptionId(application, id);
+  if (!feed) {
+    return response.status(404).send("Subscription not found");
+  }
+
+  // Verify X-Hub-Signature if we have a secret
+  if (feed.websub?.secret) {
+    const signature =
+      request.headers["x-hub-signature-256"] ||
+      request.headers["x-hub-signature"];
+
+    if (!signature) {
+      return response.status(401).send("Missing signature");
+    }
+
+    // Get raw body for signature verification
+    const rawBody =
+      typeof request.body === "string"
+        ? request.body
+        : JSON.stringify(request.body);
+
+    if (!verifySignature(signature, rawBody, feed.websub.secret)) {
+      console.warn(`[Microsub] Invalid WebSub signature for ${feed.url}`);
+      return response.status(401).send("Invalid signature");
+    }
+  }
+
+  // Acknowledge receipt immediately
+  response.status(200).send("OK");
+
+  // Process pushed content in background
+  setImmediate(async () => {
+    try {
+      await processWebsubContent(
+        application,
+        feed,
+        request.headers["content-type"],
+        request.body,
+      );
+    } catch (error) {
+      console.error(
+        `[Microsub] Error processing WebSub content for ${feed.url}: ${error.message}`,
+      );
+    }
+  });
+}
+
+/**
+ * Process WebSub pushed content
+ * @param {object} application - Indiekit application
+ * @param {object} feed - Feed document
+ * @param {string} contentType - Content-Type header
+ * @param {string|object} body - Request body
+ * @returns {Promise<void>}
+ */
+async function processWebsubContent(application, feed, contentType, body) {
+  // Convert body to string if needed
+  const content = typeof body === "string" ? body : JSON.stringify(body);
+
+  try {
+    // Parse the pushed content
+    const parsed = await parseFeed(content, feed.url, { contentType });
+
+    console.log(
+      `[Microsub] Processing ${parsed.items.length} items from WebSub push for ${feed.url}`,
+    );
+
+    // Process like a normal feed fetch but with pre-parsed content
+    // This reuses the existing feed processing logic
+    await processFeed(application, {
+      ...feed,
+      _websubContent: parsed,
+    });
+  } catch (error) {
+    console.error(
+      `[Microsub] Failed to parse WebSub content for ${feed.url}: ${error.message}`,
+    );
+  }
+}
+
+export const websubHandler = { verify, receive };

package/lib/websub/subscriber.js

@@ -0,0 +1,181 @@
+/**
+ * WebSub subscriber
+ * @module websub/subscriber
+ */
+
+import crypto from "node:crypto";
+
+import { updateFeedWebsub } from "../storage/feeds.js";
+
+const DEFAULT_LEASE_SECONDS = 86_400 * 7; // 7 days
+
+/**
+ * Subscribe to a WebSub hub
+ * @param {object} application - Indiekit application
+ * @param {object} feed - Feed document with websub.hub
+ * @param {string} callbackUrl - Callback URL for this subscription
+ * @returns {Promise<boolean>} Whether subscription was initiated
+ */
+export async function subscribe(application, feed, callbackUrl) {
+  if (!feed.websub?.hub) {
+    return false;
+  }
+
+  const topic = feed.websub.topic || feed.url;
+  const secret = generateSecret();
+
+  try {
+    const response = await fetch(feed.websub.hub, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        "hub.mode": "subscribe",
+        "hub.topic": topic,
+        "hub.callback": callbackUrl,
+        "hub.secret": secret,
+        "hub.lease_seconds": String(DEFAULT_LEASE_SECONDS),
+      }),
+    });
+
+    // 202 Accepted means subscription is pending verification
+    // 204 No Content means subscription was immediately accepted
+    if (response.status === 202 || response.status === 204) {
+      // Store the secret for signature verification
+      await updateFeedWebsub(application, feed._id, {
+        hub: feed.websub.hub,
+        topic,
+        secret,
+        pending: true,
+      });
+      return true;
+    }
+
+    console.error(
+      `[Microsub] WebSub subscription failed: ${response.status} ${response.statusText}`,
+    );
+    return false;
+  } catch (error) {
+    console.error(`[Microsub] WebSub subscription error: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Unsubscribe from a WebSub hub
+ * @param {object} application - Indiekit application
+ * @param {object} feed - Feed document with websub.hub
+ * @param {string} callbackUrl - Callback URL for this subscription
+ * @returns {Promise<boolean>} Whether unsubscription was initiated
+ */
+export async function unsubscribe(application, feed, callbackUrl) {
+  if (!feed.websub?.hub) {
+    return false;
+  }
+
+  const topic = feed.websub.topic || feed.url;
+
+  try {
+    const response = await fetch(feed.websub.hub, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        "hub.mode": "unsubscribe",
+        "hub.topic": topic,
+        "hub.callback": callbackUrl,
+      }),
+    });
+
+    if (response.status === 202 || response.status === 204) {
+      // Clear WebSub data from feed
+      await updateFeedWebsub(application, feed._id, {
+        hub: feed.websub.hub,
+        topic,
+        secret: undefined,
+        leaseSeconds: undefined,
+        pending: false,
+      });
+      return true;
+    }
+
+    return false;
+  } catch (error) {
+    console.error(`[Microsub] WebSub unsubscribe error: ${error.message}`);
+    return false;
+  }
+}
+
+/**
+ * Generate a random secret for signature verification
+ * @returns {string} Random hex string
+ */
+function generateSecret() {
+  return crypto.randomBytes(32).toString("hex");
+}
+
+/**
+ * Verify WebSub signature
+ * @param {string} signature - X-Hub-Signature header value
+ * @param {Buffer|string} body - Request body
+ * @param {string} secret - Subscription secret
+ * @returns {boolean} Whether signature is valid
+ */
+export function verifySignature(signature, body, secret) {
+  if (!signature || !secret) {
+    return false;
+  }
+
+  // Signature format: sha1=<hex> or sha256=<hex>
+  const [algorithm, hash] = signature.split("=");
+  if (!algorithm || !hash) {
+    return false;
+  }
+
+  // Normalize algorithm name
+  const algo = algorithm.toLowerCase().replace("sha", "sha");
+
+  try {
+    const expectedHash = crypto
+      .createHmac(algo, secret)
+      .update(body)
+      .digest("hex");
+
+    // Use timing-safe comparison
+    return crypto.timingSafeEqual(
+      Buffer.from(hash, "hex"),
+      Buffer.from(expectedHash, "hex"),
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a WebSub subscription is about to expire
+ * @param {object} feed - Feed document
+ * @param {number} [thresholdSeconds] - Seconds before expiry to consider "expiring"
+ * @returns {boolean} Whether subscription is expiring soon
+ */
+export function isSubscriptionExpiring(feed, thresholdSeconds = 86_400) {
+  if (!feed.websub?.expiresAt) {
+    return false;
+  }
+
+  const expiresAt = new Date(feed.websub.expiresAt);
+  const threshold = new Date(Date.now() + thresholdSeconds * 1000);
+
+  return expiresAt <= threshold;
+}
+
+/**
+ * Get callback URL for a feed
+ * @param {string} baseUrl - Base URL of the Microsub endpoint
+ * @param {string} feedId - Feed ID
+ * @returns {string} Callback URL
+ */
+export function getCallbackUrl(baseUrl, feedId) {
+  return `${baseUrl}/microsub/websub/${feedId}`;
+}

package/locales/en.json

@@ -0,0 +1,80 @@
+{
+  "microsub": {
+    "reader": {
+      "title": "Reader",
+      "empty": "No items to display",
+      "markAllRead": "Mark all as read",
+      "newer": "Newer",
+      "older": "Older"
+    },
+    "channels": {
+      "title": "Channels",
+      "new": "New channel",
+      "create": "Create channel",
+      "delete": "Delete channel",
+      "settings": "Channel settings",
+      "empty": "No channels yet. Create one to get started.",
+      "notifications": "Notifications"
+    },
+    "timeline": {
+      "title": "Timeline",
+      "empty": "No items in this channel",
+      "markRead": "Mark as read",
+      "markUnread": "Mark as unread",
+      "remove": "Remove"
+    },
+    "feeds": {
+      "title": "Feeds",
+      "follow": "Follow",
+      "unfollow": "Unfollow",
+      "empty": "No feeds followed in this channel"
+    },
+    "item": {
+      "reply": "Reply",
+      "like": "Like",
+      "repost": "Repost",
+      "bookmark": "Bookmark",
+      "viewOriginal": "View original"
+    },
+    "compose": {
+      "title": "Compose",
+      "content": "What's on your mind?",
+      "submit": "Post",
+      "cancel": "Cancel",
+      "replyTo": "Replying to",
+      "likeOf": "Liking",
+      "repostOf": "Reposting"
+    },
+    "settings": {
+      "title": "%{channel} settings",
+      "excludeTypes": "Exclude interaction types",
+      "excludeTypesHelp": "Select types of posts to hide from this channel",
+      "excludeRegex": "Exclude pattern",
+      "excludeRegexHelp": "Regular expression to filter out matching content",
+      "save": "Save settings",
+      "types": {
+        "like": "Likes",
+        "repost": "Reposts",
+        "bookmark": "Bookmarks",
+        "reply": "Replies",
+        "checkin": "Check-ins"
+      }
+    },
+    "search": {
+      "title": "Search",
+      "placeholder": "Enter URL or search term",
+      "submit": "Search",
+      "noResults": "No results found"
+    },
+    "preview": {
+      "title": "Preview",
+      "subscribe": "Subscribe to this feed"
+    },
+    "error": {
+      "channelNotFound": "Channel not found",
+      "feedNotFound": "Feed not found",
+      "invalidUrl": "Invalid URL",
+      "invalidAction": "Invalid action"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@rmdes/indiekit-endpoint-microsub",
+  "version": "1.0.0-beta.1",
+  "description": "Microsub endpoint for Indiekit. Enables subscribing to feeds and reading content using the Microsub protocol.",
+  "keywords": [
+    "indiekit",
+    "indiekit-plugin",
+    "indieweb",
+    "microsub",
+    "reader",
+    "social-reader"
+  ],
+  "homepage": "https://github.com/rmdes/indiekit",
+  "author": {
+    "name": "Ricardo Mendes",
+    "url": "https://rmendes.net"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "lib",
+    "locales",
+    "views",
+    "index.js"
+  ],
+  "bugs": {
+    "url": "https://github.com/rmdes/indiekit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rmdes/indiekit.git",
+    "directory": "packages/endpoint-microsub"
+  },
+  "dependencies": {
+    "@indiekit/error": "^1.0.0-beta.25",
+    "@indiekit/frontend": "^1.0.0-beta.25",
+    "@indiekit/util": "^1.0.0-beta.25",
+    "debug": "^4.3.2",
+    "express": "^5.0.0",
+    "feedparser": "^2.2.10",
+    "htmlparser2": "^9.0.0",
+    "ioredis": "^5.3.0",
+    "luxon": "^3.4.0",
+    "microformats-parser": "^2.0.0",
+    "sanitize-html": "^2.11.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/views/channel-new.njk

@@ -0,0 +1,33 @@
+{% extends "document.njk" %}
+
+{% block content %}
+  <div class="channel-new">
+    <a href="{{ request.baseUrl }}/channels" class="back-link">
+      {{ icon("arrow-left") }} {{ __("microsub.channels.title") }}
+    </a>
+
+    <form method="post" action="{{ request.baseUrl }}/channels/new">
+      {{ field({
+        label: {
+          text: __("microsub.channels.new")
+        },
+        input: {
+          id: "name",
+          name: "name",
+          required: true,
+          autocomplete: "off",
+          autofocus: true
+        }
+      }) }}
+
+      <div class="button-group">
+        {{ button({
+          text: __("microsub.channels.create")
+        }) }}
+        <a href="{{ request.baseUrl }}/channels" class="button button--secondary">
+          {{ __("Cancel") }}
+        </a>
+      </div>
+    </form>
+  </div>
+{% endblock %}

package/views/channel.njk

@@ -0,0 +1,41 @@
+{% extends "document.njk" %}
+
+{% block content %}
+  <div class="channel">
+    <header class="channel__header">
+      <a href="{{ request.baseUrl }}/channels" class="back-link">
+        {{ icon("arrow-left") }} {{ __("microsub.channels.title") }}
+      </a>
+      <div class="channel__actions">
+        <a href="{{ request.baseUrl }}/channels/{{ channel.uid }}/settings" class="button button--secondary button--small">
+          {{ icon("settings") }} {{ __("microsub.channels.settings") }}
+        </a>
+      </div>
+    </header>
+
+    {% if items.length > 0 %}
+    <div class="timeline">
+      {% for item in items %}
+      {% include "partials/item-card.njk" %}
+      {% endfor %}
+    </div>
+
+    {% if paging %}
+    <nav class="timeline__paging" aria-label="Pagination">
+      {% if paging.before %}
+      <a href="?before={{ paging.before }}" class="button button--secondary">
+        {{ icon("arrow-left") }} {{ __("microsub.reader.newer") }}
+      </a>
+      {% endif %}
+      {% if paging.after %}
+      <a href="?after={{ paging.after }}" class="button button--secondary">
+        {{ __("microsub.reader.older") }} {{ icon("arrow-right") }}
+      </a>
+      {% endif %}
+    </nav>
+    {% endif %}
+    {% else %}
+    {{ prose({ text: __("microsub.timeline.empty") }) }}
+    {% endif %}
+  </div>
+{% endblock %}

package/views/compose.njk

@@ -0,0 +1,61 @@
+{% extends "document.njk" %}
+
+{% block content %}
+  <div class="compose">
+    <a href="{{ request.headers.referer or request.baseUrl + '/channels' }}" class="back-link">
+      {{ icon("arrow-left") }} {{ __("Back") }}
+    </a>
+
+    {% if replyTo %}
+    <div class="compose__context">
+      {{ icon("reply") }} {{ __("microsub.compose.replyTo") }}: <a href="{{ replyTo }}">{{ replyTo }}</a>
+    </div>
+    {% endif %}
+
+    {% if likeOf %}
+    <div class="compose__context">
+      {{ icon("heart") }} {{ __("microsub.compose.likeOf") }}: <a href="{{ likeOf }}">{{ likeOf }}</a>
+    </div>
+    {% endif %}
+
+    {% if repostOf %}
+    <div class="compose__context">
+      {{ icon("repost") }} {{ __("microsub.compose.repostOf") }}: <a href="{{ repostOf }}">{{ repostOf }}</a>
+    </div>
+    {% endif %}
+
+    <form method="post" action="{{ request.baseUrl }}/compose">
+      {% if replyTo %}
+      <input type="hidden" name="in-reply-to" value="{{ replyTo }}">
+      {% endif %}
+      {% if likeOf %}
+      <input type="hidden" name="like-of" value="{{ likeOf }}">
+      {% endif %}
+      {% if repostOf %}
+      <input type="hidden" name="repost-of" value="{{ repostOf }}">
+      {% endif %}
+
+      {% if not likeOf and not repostOf %}
+      {{ textarea({
+        label: {
+          text: __("microsub.compose.content"),
+          classes: "label--visuallyhidden"
+        },
+        id: "content",
+        name: "content",
+        rows: 5,
+        autofocus: true
+      }) }}
+      {% endif %}
+
+      <div class="button-group">
+        {{ button({
+          text: __("microsub.compose.submit")
+        }) }}
+        <a href="{{ request.headers.referer or request.baseUrl + '/channels' }}" class="button button--secondary">
+          {{ __("microsub.compose.cancel") }}
+        </a>
+      </div>
+    </form>
+  </div>
+{% endblock %}