@riebeckite/plugin-webmention 0.0.6

package/dist/src/diagnostics.d.ts

@@ -0,0 +1,6 @@
+import type { Diagnostic } from "@riebeckite/core";
+import { type WebmentionProvider } from "./provider.js";
+import type { ResolvedWebmentionOptions } from "./types.js";
+export declare const WEBMENTION_PLUGIN_NAME = "webmention";
+/** Structured health checks for the configured provider and rendering mode. */
+export declare function buildWebmentionDiagnostics(provider: WebmentionProvider, options: ResolvedWebmentionOptions): Diagnostic[];

package/dist/src/endpoints.d.ts

@@ -0,0 +1,9 @@
+import type { PluginEndpoint } from "@riebeckite/core";
+import type { ResolvedWebmentionOptions } from "./types.js";
+/**
+ * Receive (`POST`) and feed (`GET`) endpoints for the configured path.
+ *
+ * The plugin only declares the HTTP contract; the HonoX integration mounts it
+ * on the host router. Route-framework specifics never enter this package.
+ */
+export declare function createWebmentionEndpoints(options: ResolvedWebmentionOptions): PluginEndpoint[];

package/dist/src/feed.d.ts

@@ -0,0 +1,28 @@
+import type { ContentManifest, PluginEndpointContext, PluginEndpointResponse, ResolvedRiebeckiteConfig } from "@riebeckite/core";
+import type { WebmentionMention } from "./mention.js";
+import { type WebmentionProvider } from "./provider.js";
+import type { ResolvedWebmentionOptions } from "./types.js";
+/** Public article summary attached to a fed mention. */
+export type WebmentionFeedEntry = Readonly<{
+    slug: string;
+    permalink: string;
+    title: string;
+}>;
+export type WebmentionFeedMention = WebmentionMention & Readonly<{
+    entry: WebmentionFeedEntry | null;
+}>;
+export type WebmentionFeed = Readonly<{
+    version: "1";
+    generatedAt: string;
+    count: number;
+    mentions: readonly WebmentionFeedMention[];
+}>;
+/**
+ * Builds the `GET` feed handler. It returns verified mentions as JSON so an
+ * application route, island, or external consumer can read them. The feed is
+ * optional when the provider cannot query.
+ */
+export declare function createWebmentionFeedHandler(options: ResolvedWebmentionOptions, provider: WebmentionProvider): (context: PluginEndpointContext) => Promise<PluginEndpointResponse>;
+/** Builds the feed payload shared by the endpoint and application consumers. */
+export declare function buildFeed(manifest: ContentManifest, config: ResolvedRiebeckiteConfig | undefined, mentions: readonly WebmentionMention[]): WebmentionFeed;
+export declare function summarizeEntry(manifest: ContentManifest, config: ResolvedRiebeckiteConfig | undefined, target: string): WebmentionFeedEntry | null;

package/dist/src/http.d.ts

@@ -0,0 +1,5 @@
+import type { PluginEndpointResponse } from "@riebeckite/core";
+/** JSON endpoint response with an explicit content type. */
+export declare function jsonResponse(status: number, value: unknown): PluginEndpointResponse;
+/** A structured, non-throwing error body shared by receive and feed. */
+export declare function errorResponse(status: number, error: string): PluginEndpointResponse;

package/dist/src/memory_provider.d.ts

@@ -0,0 +1,14 @@
+import { type WebmentionMention } from "./mention.js";
+import { type WebmentionProvider } from "./provider.js";
+import type { WebmentionQuery, WebmentionQueryResult } from "./query.js";
+/**
+ * In-memory provider for tests, local previews, and provider contract
+ * examples. State lives for the lifetime of the process/isolate only.
+ */
+export declare class MemoryWebmentionProvider implements WebmentionProvider {
+    #private;
+    readonly capabilities: Set<"store" | "query">;
+    constructor(initialMentions?: readonly WebmentionMention[]);
+    store(mention: WebmentionMention): Promise<void>;
+    query(query: WebmentionQuery): Promise<WebmentionQueryResult>;
+}

package/dist/src/mention.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Storage- and runtime-independent Webmention records.
+ *
+ * A mention is only created after the source document has been fetched and
+ * verified to link to the target, so every stored record is a verified
+ * mention by construction.
+ */
+export declare const WEBMENTION_TYPES: readonly ["mention", "reply", "like", "repost", "bookmark"];
+export type WebmentionType = (typeof WEBMENTION_TYPES)[number];
+export type WebmentionAuthor = Readonly<{
+    name?: string;
+    url?: string;
+    photo?: string;
+}>;
+export type WebmentionMention = Readonly<{
+    /** Absolute URL of the verified source document. */
+    source: string;
+    /** Absolute target URL on this site. */
+    target: string;
+    type: WebmentionType;
+    /** ISO-8601 timestamp of the verification that created this record. */
+    verifiedAt: string;
+    /** ISO-8601 publication date discovered on the source, when available. */
+    publishedAt?: string;
+    /** Source title, when discoverable. */
+    title?: string;
+    /** Short plain-text excerpt of the source, when discoverable. */
+    excerpt?: string;
+    author?: WebmentionAuthor;
+}>;
+/** Stable identity of a mention: a source/target pair. */
+export declare function webmentionKey(mention: Pick<WebmentionMention, "source" | "target">): string;

package/dist/src/options.d.ts

@@ -0,0 +1,12 @@
+import type { ConfigValidationIssue } from "@riebeckite/core";
+import type { ResolvedWebmentionOptions, WebmentionOptions } from "./types.js";
+export declare const DEFAULT_WEBMENTION_ENDPOINT = "/webmentions";
+export declare const DEFAULT_WEBMENTION_HEADING_TEXT = "Mentions";
+export declare const DEFAULT_WEBMENTION_LIMIT = 20;
+export declare const DEFAULT_WEBMENTION_CLASS_NAME = "rr-webmention";
+/**
+ * Applies defaults and creates the default source fetcher. Pure with respect
+ * to the filesystem; the only side effect is constructing a fetcher closure.
+ */
+export declare function resolveWebmentionOptions(options?: WebmentionOptions): ResolvedWebmentionOptions;
+export declare function validateWebmentionOptions(options: WebmentionOptions | undefined): readonly ConfigValidationIssue[];

package/dist/src/parse.d.ts

@@ -0,0 +1,25 @@
+import type { WebmentionAuthor, WebmentionType } from "./mention.js";
+export type ParsedWebmentionLink = Readonly<{
+    href: string;
+    normalized: string | null;
+    rels: readonly string[];
+    text: string;
+}>;
+export type ParsedWebmentionSource = Readonly<{
+    title?: string;
+    excerpt?: string;
+    author?: WebmentionAuthor;
+    publishedAt?: string;
+    links: readonly ParsedWebmentionLink[];
+}>;
+/**
+ * Parses the parts of a source document that a Webmention display needs:
+ * outbound links (for verification) and lightweight citation metadata. It
+ * deliberately does not implement the full microformats2 parser; recognized
+ * `rel` values and common meta tags cover the common cases.
+ */
+export declare function parseWebmentionSource(html: string, sourceUrl: string): ParsedWebmentionSource;
+/** Finds the parsed link that points at the target, if any. */
+export declare function findTargetLink(source: ParsedWebmentionSource, target: string): ParsedWebmentionLink | null;
+/** Maps recognized `rel` values to a Webmention type. */
+export declare function webmentionTypeForRels(rels: readonly string[]): WebmentionType;

package/dist/src/provider.d.ts

@@ -0,0 +1,30 @@
+import type { WebmentionMention } from "./mention.js";
+import type { WebmentionQuery, WebmentionQueryResult } from "./query.js";
+export declare const WEBMENTION_CAPABILITIES: readonly ["store", "query"];
+export type WebmentionCapability = (typeof WEBMENTION_CAPABILITIES)[number];
+/**
+ * Storage- and runtime-independent Webmention boundary.
+ *
+ * The plugin only ever sees this interface. A provider may keep credentials,
+ * database handles, or runtime bindings internally; those never enter the
+ * plugin options that reach generated output.
+ */
+export interface WebmentionProvider {
+    readonly capabilities: ReadonlySet<WebmentionCapability>;
+    /**
+     * Persists a verified mention. Implementations upsert by `(source, target)`
+     * so repeated deliveries converge on one record.
+     */
+    store(mention: WebmentionMention): Promise<void>;
+    /** Reads stored mentions. */
+    query(query: WebmentionQuery): Promise<WebmentionQueryResult>;
+}
+export declare function supportsWebmentionCapability(provider: WebmentionProvider, capability: WebmentionCapability): boolean;
+export declare class UnsupportedWebmentionQueryError extends Error {
+    readonly query: WebmentionQuery;
+    readonly requiredCapability: WebmentionCapability;
+    readonly name = "UnsupportedWebmentionQueryError";
+    constructor(query: WebmentionQuery, requiredCapability: WebmentionCapability);
+}
+export declare function requiredCapabilityForQuery(_query: WebmentionQuery): WebmentionCapability;
+export declare function assertWebmentionQuerySupported(provider: WebmentionProvider, query: WebmentionQuery): void;

package/dist/src/query.d.ts

@@ -0,0 +1,24 @@
+import type { WebmentionMention } from "./mention.js";
+export type MentionsForTargetQuery = Readonly<{
+    type: "mentions_for_target";
+    /** Absolute target URL. */
+    target: string;
+    limit?: number;
+}>;
+export type AllMentionsQuery = Readonly<{
+    type: "all_mentions";
+    limit?: number;
+    /** Only mentions verified at or after this ISO-8601 timestamp. */
+    since?: string;
+}>;
+export type WebmentionQuery = MentionsForTargetQuery | AllMentionsQuery;
+export type MentionsForTargetResult = Readonly<{
+    type: "mentions_for_target";
+    target: string;
+    mentions: readonly WebmentionMention[];
+}>;
+export type AllMentionsResult = Readonly<{
+    type: "all_mentions";
+    mentions: readonly WebmentionMention[];
+}>;
+export type WebmentionQueryResult = MentionsForTargetResult | AllMentionsResult;

package/dist/src/receive.d.ts

@@ -0,0 +1,20 @@
+import type { PluginEndpointContext, PluginEndpointResponse } from "@riebeckite/core";
+import { type WebmentionProvider } from "./provider.js";
+import type { ResolvedWebmentionOptions } from "./types.js";
+type WebmentionRequestBody = Readonly<{
+    source?: string;
+    target?: string;
+}>;
+/**
+ * Builds the `POST` receive handler. It validates the request, checks the
+ * target belongs to the site, verifies the source actually links to it, and
+ * stores the verified mention through the provider.
+ */
+export declare function createWebmentionReceiveHandler(options: ResolvedWebmentionOptions, provider: WebmentionProvider): (context: PluginEndpointContext) => Promise<PluginEndpointResponse>;
+/**
+ * Parses `source`/`target` from an `application/x-www-form-urlencoded` or
+ * `application/json` body. Returns `null` for malformed JSON; missing fields
+ * are reported separately by the caller.
+ */
+export declare function parseWebmentionRequestBody(body: string, headers: Readonly<Record<string, string>>): WebmentionRequestBody | null;
+export {};

package/dist/src/render.d.ts

@@ -0,0 +1,12 @@
+import type { WebmentionMention } from "./mention.js";
+import type { ResolvedWebmentionOptions } from "./types.js";
+/** Boolean attribute that marks the generated mention section. */
+export declare const WEBMENTION_ATTRIBUTE = "data-webmention";
+/**
+ * Renders the mentions section with stable `rr-webmention` hooks. Returns an
+ * empty string when there is nothing to show so callers can leave an entry's
+ * HTML untouched.
+ */
+export declare function renderWebmentionSection(mentions: readonly WebmentionMention[], options: ResolvedWebmentionOptions): string;
+/** Renders one mention list item. */
+export declare function renderWebmentionItem(mention: WebmentionMention, options: ResolvedWebmentionOptions): string;

package/dist/src/server.d.ts

@@ -0,0 +1,24 @@
+import type { ContentManifest, ResolvedRiebeckiteConfig } from "@riebeckite/core";
+import type { WebmentionMention } from "./mention.js";
+import type { WebmentionProvider } from "./provider.js";
+/**
+ * Reads verified mentions for one entry. Application routes call this at
+ * request/SSR time when they render mentions themselves instead of relying on
+ * build-time injection.
+ */
+export declare function getWebmentionsForEntry(input: {
+    manifest: ContentManifest;
+    config: ResolvedRiebeckiteConfig | undefined;
+    provider: WebmentionProvider;
+    slug: string;
+    limit?: number;
+}): Promise<WebmentionMention[]>;
+/**
+ * Groups mentions by the manifest entry they target. Mentions whose target is
+ * not a published entry are omitted; callers that need them can query the
+ * provider directly.
+ */
+export declare function groupMentionsBySlug(manifest: ContentManifest, config: ResolvedRiebeckiteConfig | undefined, mentions: readonly WebmentionMention[]): Map<string, WebmentionMention[]>;
+/** Counts mentions whose target does not match a published entry. */
+export declare function countUnmatchedMentions(manifest: ContentManifest, config: ResolvedRiebeckiteConfig | undefined, mentions: readonly WebmentionMention[]): number;
+export declare function compareMentions(left: WebmentionMention, right: WebmentionMention): number;

package/dist/src/targets.d.ts

@@ -0,0 +1,10 @@
+import type { ContentManifest, ContentManifestEntry, ResolvedRiebeckiteConfig } from "@riebeckite/core";
+/**
+ * Resolves an entry's public URL. Relative permalinks need the configured
+ * base URL; without one, only an already-absolute permalink can be matched.
+ */
+export declare function entryPublicUrl(entry: ContentManifestEntry, config: ResolvedRiebeckiteConfig | undefined): string | null;
+/** Finds the content entry whose public URL matches `target`, if any. */
+export declare function findTargetEntry(manifest: ContentManifest, config: ResolvedRiebeckiteConfig | undefined, target: string): ContentManifestEntry | undefined;
+/** Whether `target` is explicitly allowed by `allowedTargets`. */
+export declare function isAllowedTarget(target: string, allowedTargets: readonly string[], config: ResolvedRiebeckiteConfig | undefined): boolean;

package/dist/src/types.d.ts

@@ -0,0 +1,50 @@
+import type { WebmentionProvider } from "./provider.js";
+import type { WebmentionSourceFetcher } from "./verify.js";
+/**
+ * Options accepted by `webmention()`.
+ *
+ * `provider` is optional so a site can register the plugin before choosing a
+ * runtime store. Without one the plugin falls back to an in-memory provider,
+ * which is appropriate for local previews and tests but does not persist
+ * across processes or isolates.
+ */
+export type WebmentionOptions = Readonly<{
+    /** Verified-mention storage. Defaults to a per-plugin memory provider. */
+    provider?: WebmentionProvider;
+    /** Receive (POST) and feed (GET) path. Defaults to `/webmentions`. */
+    endpoint?: string;
+    /** Render stored mentions near articles. Defaults to `true`. */
+    render?: boolean;
+    /** Heading text for the rendered section. Defaults to `"Mentions"`. */
+    headingText?: string;
+    /** Maximum mentions rendered per article. Defaults to `20`. */
+    limit?: number;
+    /** Root CSS class of the rendered section. Defaults to `"rr-webmention"`. */
+    className?: string;
+    /** Extra absolute target URLs to accept beyond published entries. */
+    allowedTargets?: readonly string[];
+    /** Source fetcher override, mainly for tests and custom runtimes. */
+    fetchSource?: WebmentionSourceFetcher;
+    /** Fetch timeout in milliseconds. Defaults to `10000`. */
+    timeoutMs?: number;
+    /** Maximum accepted source document size in bytes. Defaults to `1000000`. */
+    maxBytes?: number;
+    /** Override the verification `User-Agent` header. */
+    userAgent?: string;
+    /** Allow fetching private-network sources. Defaults to `false`. */
+    allowPrivateHosts?: boolean;
+    /** Add `rel="nofollow ugc"` to rendered source links. Defaults to `true`. */
+    nofollow?: boolean;
+}>;
+/** `WebmentionOptions` with every default applied. */
+export type ResolvedWebmentionOptions = Readonly<{
+    provider: WebmentionProvider;
+    endpoint: string;
+    render: boolean;
+    headingText: string;
+    limit: number;
+    className: string;
+    allowedTargets: readonly string[];
+    fetchSource: WebmentionSourceFetcher;
+    nofollow: boolean;
+}>;

package/dist/src/url.d.ts

@@ -0,0 +1,14 @@
+/**
+ * URL helpers shared by verification, target matching, and storage. They keep
+ * comparison stable without changing the URLs that are persisted or rendered.
+ */
+/** Parses an absolute http(s) URL and returns a canonical comparison form. */
+export declare function normalizeWebmentionUrl(value: string): string | null;
+/**
+ * Canonical form used for equality checks. Fragments and a single trailing
+ * slash are ignored so `https://example.com/a`, `https://example.com/a/`, and
+ * `https://example.com/a#section` are treated as the same target.
+ */
+export declare function urlComparisonKey(value: string): string;
+/** Resolves a site-relative permalink against the configured base URL. */
+export declare function resolvePublicUrl(permalink: string, baseUrl: string | undefined): string | null;

package/dist/src/verify.d.ts

@@ -0,0 +1,74 @@
+import type { WebmentionMention } from "./mention.js";
+export type WebmentionSourceDocument = Readonly<{
+    /** Final absolute URL of the fetched document. */
+    url: string;
+    html: string;
+}>;
+/**
+ * Fetches a source document. It returns `null` for an unreachable, non-HTML,
+ * oversized, or otherwise unusable source. Implementations keep their own
+ * network/runtime details; the plugin core only calls this function.
+ */
+export type WebmentionSourceFetcher = (url: string) => Promise<WebmentionSourceDocument | null>;
+/**
+ * Resolves a hostname to every IP address it currently points at. It is
+ * injectable so a runtime (or a test) can supply its own resolver. The default
+ * uses `node:dns` and falls back to no resolution when the builtin is
+ * unavailable, such as in a Worker without a DNS module.
+ */
+export type WebmentionHostResolver = (hostname: string) => Promise<readonly string[]>;
+export type WebmentionSourceFetcherOptions = Readonly<{
+    /** Request timeout in milliseconds. Defaults to `10000`. */
+    timeoutMs?: number;
+    /** Maximum accepted body size in bytes. Defaults to `1_000_000`. */
+    maxBytes?: number;
+    userAgent?: string;
+    /**
+     * Allow fetching loopback and private-network hosts. Defaults to `false`.
+     * Enable only for a trusted, self-hosted verification service.
+     */
+    allowPrivateHosts?: boolean;
+    /**
+     * Hostname resolver used for DNS-rebinding checks. Defaults to the runtime's
+     * `node:dns` resolver. When resolution is unavailable, the hostname string
+     * and literal-IP checks still apply.
+     */
+    resolveHostname?: WebmentionHostResolver;
+}>;
+export declare const DEFAULT_WEBMENTION_TIMEOUT_MS = 10000;
+export declare const DEFAULT_WEBMENTION_MAX_BYTES = 1000000;
+export declare const DEFAULT_WEBMENTION_USER_AGENT = "Riebeckite-Webmention/1.0 (+https://github.com/Rerurate514/riebeckite)";
+/**
+ * Default fetcher backed by the global `fetch`. It follows redirects manually,
+ * validating every hop's host and resolved addresses, and caps the response
+ * body while it streams.
+ */
+export declare function createWebmentionSourceFetcher(options?: WebmentionSourceFetcherOptions): WebmentionSourceFetcher;
+export type WebmentionRejectionReason = "invalid_source" | "invalid_target" | "source_unreachable" | "no_link_found";
+export type WebmentionVerification = Readonly<{
+    ok: true;
+    mention: WebmentionMention;
+}> | Readonly<{
+    ok: false;
+    reason: WebmentionRejectionReason;
+}>;
+/**
+ * Verifies that `source` actually links to `target` and, when it does, builds
+ * the verified mention record. Network access happens only through `fetchSource`.
+ */
+export declare function verifyWebmention(input: {
+    source: string;
+    target: string;
+    fetchSource: WebmentionSourceFetcher;
+    verifiedAt?: string;
+}): Promise<WebmentionVerification>;
+/**
+ * Literal hostname check: rejects explicit local names and any literal IP in a
+ * loopback, private, link-local, unique-local, or reserved range.
+ */
+export declare function isDisallowedHostname(hostname: string): boolean;
+/**
+ * Rejects loopback, private, link-local, unique-local, and reserved addresses.
+ * Malformed input is treated as disallowed so a parsing gap cannot fail open.
+ */
+export declare function isDisallowedIpAddress(address: string): boolean;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@riebeckite/plugin-webmention",
+  "version": "0.0.6",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "source": "./index.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": "./style.css"
+  },
+  "dependencies": {
+    "@riebeckite/core": "0.0.6"
+  },
+  "devDependencies": {
+    "tsx": "^4.22.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "LICENSE",
+    "README.md",
+    "README_ja.md",
+    "dist",
+    "style.css"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Rerurate514/riebeckite.git",
+    "directory": "packages/plugins/webmention"
+  },
+  "homepage": "https://github.com/Rerurate514/riebeckite#readme",
+  "bugs": {
+    "url": "https://github.com/Rerurate514/riebeckite/issues"
+  },
+  "description": "Receive verified Webmentions and render them as mentions for Riebeckite sites.",
+  "keywords": [
+    "riebeckite",
+    "plugin",
+    "webmention",
+    "indieweb",
+    "mentions"
+  ],
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "sideEffects": [
+    "./style.css"
+  ],
+  "scripts": {
+    "build": "node ../../../scripts/build_package.mjs",
+    "test": "node --import tsx --test \"test/*.test.ts\""
+  }
+}

package/style.css

@@ -0,0 +1,66 @@
+.rr-webmention {
+  --rr-webmention-ink: var(--rb-color-ink, #181613);
+  --rr-webmention-muted: var(--rb-color-muted, #6b655c);
+  --rr-webmention-rule: color-mix(
+    in srgb,
+    var(--rr-webmention-ink) 16%,
+    transparent
+  );
+
+  margin-top: 3rem;
+  padding-top: 1.5rem;
+  border-top: 1px solid var(--rr-webmention-rule);
+  color: var(--rr-webmention-ink);
+}
+
+.rr-webmention__heading {
+  margin: 0 0 1rem;
+  font-size: 1.125rem;
+  font-weight: 700;
+  letter-spacing: 0.02em;
+}
+
+.rr-webmention__list {
+  display: grid;
+  gap: 1rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.rr-webmention__item {
+  margin: 0;
+  padding: 0;
+}
+
+.rr-webmention__source {
+  color: inherit;
+  font-weight: 600;
+  text-decoration: underline;
+  text-decoration-color: var(--rr-webmention-rule);
+  text-underline-offset: 0.2em;
+}
+
+.rr-webmention__source:hover,
+.rr-webmention__source:focus-visible {
+  text-decoration-color: var(--rr-webmention-muted);
+}
+
+.rr-webmention__author,
+.rr-webmention__date {
+  margin-inline-start: 0.4em;
+  color: var(--rr-webmention-muted);
+  font-size: 0.8125rem;
+}
+
+.rr-webmention__excerpt {
+  margin: 0.35rem 0 0;
+  color: var(--rr-webmention-muted);
+  font-size: 0.9375rem;
+  line-height: 1.5;
+}
+
+html[data-theme="dark"] .rr-webmention,
+html.dark .rr-webmention {
+  --rr-webmention-ink: var(--rb-color-paper, #f5f2ec);
+}