@rmdes/indiekit-endpoint-comments

Comment endpoint for Indiekit. Allows visitors to authenticate via IndieAuth and post comments on blog posts. Site owners can reply to comments from the admin session.

Features

• IndieAuth authentication — visitors sign in with their personal URL via IndieAuth/PKCE
• Comment submission — authenticated visitors can post comments on any page
• Owner replies — site owner can reply to native comments from the admin session
• Rate limiting — per-user rate limits (configurable per hour/per day)
• Content sanitization — HTML sanitization with configurable max length
• Admin moderation — hide (soft delete), restore, and purge comments
• JF2 API — comments served in JF2 feed format for frontend consumption

Installation

npm install @rmdes/indiekit-endpoint-comments

// indiekit.config.js
import CommentsEndpoint from "@rmdes/indiekit-endpoint-comments";

export default {
  plugins: [
    new CommentsEndpoint({
      mountPath: "/comments",
      maxLength: 2000,
      rateLimit: { perHour: 5, perDay: 20 },
    }),
  ],
};

API

Public Routes (no authentication required)

Method	Path	Description
GET	/comments/api/comments?target={url}	Get comments for a target URL (JF2 feed)
GET	/comments/api/session	Check current IndieAuth session
GET	/comments/api/is-owner	Check if visitor is the site owner (admin session)
POST	/comments/api/submit	Submit a comment (requires IndieAuth session)
POST	/comments/api/reply	Submit an owner reply to a comment (requires admin session)
POST	/comments/api/auth	Start IndieAuth flow
GET	/comments/auth/callback	IndieAuth callback handler

Admin Routes (require Indiekit authentication)

Method	Path	Description
GET	/comments	Admin dashboard with stats and moderation
POST	/comments/hide	Soft-delete a comment
POST	/comments/purge	Permanently delete a comment

Owner Reply (POST /comments/api/reply)

Allows the site owner to reply to native comments. Requires an active Indiekit admin session (not an IndieAuth comment session).

Request:

{
  "parent_id": "comment-id-123",
  "content": "Thanks for the comment!",
  "target": "https://example.com/posts/hello/"
}

Response:

{
  "success": true,
  "comment": {
    "type": "entry",
    "author": {
      "name": "Site Owner",
      "url": "https://example.com",
      "photo": "https://..."
    },
    "content": {
      "text": "Thanks for the comment!",
      "html": "<p>Thanks for the comment!</p>"
    },
    "published": "2026-03-15T12:00:00.000Z"
  }
}

Owner Detection (GET /comments/api/is-owner)

Returns owner status and available syndication targets for the reply-to-interactions feature. Used by the frontend to show reply buttons on interactions.

Response (when owner):

{
  "isOwner": true,
  "name": "Ricardo Mendes",
  "url": "https://rmendes.net",
  "photo": "https://...",
  "syndicationTargets": {
    "bluesky": "https://bsky.social",
    "mastodon": "https://indieweb.social"
  }
}

The syndicationTargets map is auto-detected from Indiekit's registered syndicators. The frontend uses these to route replies to the correct platform via Micropub.

Architecture

Comment Types

This plugin handles two distinct reply flows:

Flow	Trigger	Route	Session
Visitor comment	Visitor submits via comment form	POST /api/submit	IndieAuth comment session
Owner reply to comment	Owner replies to a native comment	POST /api/reply	Indiekit admin session

Reply-to-Interactions (Micropub flow)

When the site owner replies to platform interactions (Mastodon replies, Bluesky mentions, IndieWeb webmentions), the reply goes through Micropub — not through this plugin. The frontend posts to /micropub with in-reply-to set to the interaction's URL and optional mp-syndicate-to for platform-specific threading.

This separation exists because:

• Native comments are stored in the comments collection and managed by this plugin
• Platform interactions are stored in the conversation_items collection by @rmdes/indiekit-endpoint-conversations
• Owner replies to interactions are Micropub posts stored in the posts collection

Collections

Collection	Purpose
comments	Native visitor comments
comment_sessions	IndieAuth session state (PKCE, tokens)

Dependencies

• indiekit-eleventy-theme — The theme's comments.js provides the Alpine.js comment form, IndieAuth flow, and inline reply UI. webmentions.js provides reply buttons on platform interactions.
• @rmdes/indiekit-endpoint-conversations — Handles platform interactions (Mastodon/Bluesky/AP). Owner replies to platform interactions go through Micropub, and conversations enriches its API with those replies for frontend threading.

License

MIT