@sockethub/platform-feeds 4.0.0-alpha.8 → 4.0.0-beta.0

package/README.md

@@ -8,7 +8,7 @@ This platform fetches RSS and Atom feeds from URLs and converts feed entries int
 ActivityStreams objects. It handles various feed formats and provides structured data for
 web applications to consume feed content.
 
-## Implemented Verbs (`@type`)
+## Implemented Verbs (`type`)
 
 * **fetch** - Retrieve and parse an RSS or Atom feed
 
@@ -18,33 +18,82 @@ web applications to consume feed content.
 
 ```json
 {
-  "@type": "fetch",
-  "context": "feeds",
+  "type": "fetch",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/feeds/v1.jsonld"
+  ],
   "actor": {
-    "@id": "https://example.com/feed.xml"
+    "id": "https://example.com/feed.xml",
+    "type": "feed"
   }
 }
 ```
 
+#### Optional Fetch Parameters
+
+A fetch request may carry an `object` with filtering parameters. The `object`
+is strictly validated: only the parameters below are accepted, anything else
+is rejected.
+
+```json
+{
+  "type": "fetch",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/feeds/v1.jsonld"
+  ],
+  "actor": {
+    "id": "https://example.com/feed.xml",
+    "type": "feed"
+  },
+  "object": {
+    "since": "2024-01-01T00:00:00.000Z",
+    "limit": 10
+  }
+}
+```
+
+* **since** (RFC3339 `date-time` string) — only return entries published at or
+  after this instant. Entries without a parseable publication date are
+  excluded when `since` is set, since they cannot be confirmed as recent
+  enough.
+* **limit** (integer, minimum `1`) — return at most this many entries. Applied
+  after `since`, preserving feed order.
+
 ### Response Format
 
 Returns an ActivityStreams Collection with feed entries:
 
 ```json
 {
-  "@type": "Collection",
-  "context": "feeds",
+  "type": "collection",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/feeds/v1.jsonld"
+  ],
+  "summary": "Example Blog",
   "totalItems": 10,
   "items": [
     {
-      "@type": "Create",
+      "type": "post",
+      "@context": [
+        "https://www.w3.org/ns/activitystreams",
+        "https://sockethub.org/ns/context/v1.jsonld",
+        "https://sockethub.org/ns/context/platform/feeds/v1.jsonld"
+      ],
       "actor": {
-        "@id": "https://example.com/feed.xml",
+        "id": "https://example.com/feed.xml",
+        "type": "feed",
         "name": "Example Blog"
       },
       "object": {
-        "@type": "Article",
-        "name": "Blog Post Title",
+        "id": "https://example.com/post/1",
+        "type": "note",
+        "title": "Blog Post Title",
         "content": "Post content...",
         "url": "https://example.com/post/1",
         "published": "2023-01-01T12:00:00Z"
@@ -54,6 +103,95 @@ Returns an ActivityStreams Collection with feed entries:
 }
 ```
 
+### Detailed Response Example
+
+```json
+{
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/feeds/v1.jsonld"
+  ],
+  "type": "collection",
+  "summary": "Best Feed Inc.",
+  "totalItems": 10,
+  "items": [
+    {
+      "@context": [
+        "https://www.w3.org/ns/activitystreams",
+        "https://sockethub.org/ns/context/v1.jsonld",
+        "https://sockethub.org/ns/context/platform/feeds/v1.jsonld"
+      ],
+      "type": "post",
+      "actor": {
+        "type": "feed",
+        "name": "Best Feed Inc.",
+        "id": "http://blog.example.com/rss",
+        "description": "Where the best feed comes to be the best",
+        "image": "http://blog.example.com/images/bestfeed.jpg",
+        "link": "http://blog.example.com",
+        "categories": ["best", "feed", "animals"],
+        "language": "en",
+        "author": "John Doe"
+      },
+      "object": {
+        "id": "http://blog.example.com/articles/about-stuff",
+        "type": "note",
+        "title": "About stuff...",
+        "url": "http://blog.example.com/articles/about-stuff",
+        "published": "2013-05-28T12:00:00.000Z",
+        "datenum": 1369742400000,
+        "brief": "Brief synopsis of stuff...",
+        "content": "Once upon a time...",
+        "contentType": "text"
+      }
+    }
+  ]
+}
+```
+
+## Request Hardening (SSRF Guard)
+
+Because the server fetches whatever URL a client supplies as `actor.id`, feed
+requests are hardened against server-side request forgery (SSRF) and resource
+exhaustion, using the shared guarded fetch dispatcher from `@sockethub/util`:
+
+* Only `http:` and `https:` URLs are accepted.
+* The connection is refused if the destination resolves to a loopback, private,
+  link-local, carrier-grade NAT, or otherwise non-public address — validated at
+  the connection layer, so it also covers every redirect hop (no
+  check-then-fetch rebinding gap). IPv4-mapped, IPv4-compatible, and NAT64 IPv6
+  spellings of those ranges are normalized and blocked as well.
+* Response bodies are capped (a missing or lying `Content-Length` does not
+  bypass the cap).
+* Non-2xx responses fail the job with a descriptive error.
+
+### `allowPrivateAddresses`
+
+Set in the Sockethub config file under this platform's `packageConfig` entry:
+
+```json
+{
+  "packageConfig": {
+    "@sockethub/platform-feeds": {
+      "allowPrivateAddresses": true
+    }
+  }
+}
+```
+
+This disables **only** the private/loopback destination checks. Scheme
+validation, the redirect limit, and the response size cap always remain in
+effect.
+
+This is an escape hatch for development and test harnesses that serve feed
+fixtures from `localhost`, or for self-hosted deployments that intentionally
+fetch intranet feeds. **Do not enable it on a server that accepts requests
+from untrusted clients** — it allows any client to make the server issue HTTP
+requests to internal services, including cloud metadata endpoints such as
+`169.254.169.254`. It defaults to off; the full guard is active unless
+`allowPrivateAddresses` is explicitly `true`.
+
 ## Supported Feed Formats
 
 * **RSS 2.0**: Standard RSS feeds

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * This is a platform for Sockethub implementing Atom/RSS fetching functionality.
+ *
+ * Developed by Nick Jennings (https://github.com/silverbucket)
+ *
+ * Sockethub is licensed under the LGPLv3.
+ * See the LICENSE file for details.
+ *
+ * The latest version of this module can be found here:
+ *   git://github.com/sockethub/sockethub.git
+ *
+ * For more information about Sockethub visit http://sockethub.org/.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ */
+import type { ActivityStream, PlatformCallback, PlatformConfig, PlatformInterface, PlatformSchemaStruct, PlatformSession } from "@sockethub/schemas";
+import { type Episode } from "podparse";
+import { type PlatformFeedsActivityObject, type PlatformFeedsActivityStream } from "./types.js";
+/**
+ * Class: Feeds
+ *
+ * Handles all actions related to fetching feeds.
+ *
+ * Current supported feed types:
+ *
+ * - RSS (1 & 2)
+ *
+ * - Atom
+ *
+ * Uses the `podparse` module as a base tool fetching feeds.
+ *
+ * https://github.com/Tombarr/podcast-feed-parser
+ *
+ */
+export default class Feeds implements PlatformInterface {
+    id: string;
+    private readonly log;
+    private dispatcher?;
+    config: PlatformConfig;
+    /**
+     * @constructor
+     * @param session - a unique session object for this platform instance
+     */
+    constructor(session: PlatformSession);
+    get schema(): PlatformSchemaStruct;
+    /**
+     * Stateless platforms are always ready to handle jobs.
+     */
+    isInitialized(): boolean;
+    /**
+     * Fetch feeds from specified source. Upon completion, it will send back a
+     * response to the original request with a complete ActivityStreams Collection
+     * containing all feed items and metadata.
+     *
+     * The request may carry an optional `object` with filtering parameters:
+     * `since` (RFC3339 date-time; only entries published at or after this
+     * instant, undated entries excluded) and `limit` (integer >= 1; cap on
+     * returned entries, applied after `since`, feed order preserved).
+     *
+     * @param job - Activity streams object containing job data with actor.id as feed URL
+     * @param done - Callback function that receives (error, ASCollection)
+     * See the package README for canonical request and response payload
+     * examples.
+     */
+    fetch(job: ActivityStream, done: PlatformCallback): void;
+    /**
+     * Cleanup method called when platform instance is being shut down.
+     *
+     * @param done - Callback function to signal completion
+     */
+    cleanup(done: PlatformCallback): void;
+    /**
+     * The SSRF-guarded undici dispatcher, created once per instance (its
+     * `allowPrivateAddresses` setting comes from packageConfig, fixed before the
+     * first job) and reused so connections/timers are pooled.
+     */
+    private getDispatcher;
+    private makeRequest;
+    private fetchFeed;
+}
+/**
+ * Optional parameters a client may attach to a `fetch` request `object`.
+ * Mirrors the strict `messages.object` schema; both must stay in sync.
+ */
+export interface FeedFetchParams {
+    since?: string;
+    limit?: number;
+}
+/**
+ * Extract the supported fetch parameters from a request `object`. Inbound
+ * messages are already validated against the strict `messages` schema on the
+ * server, so this only needs to read the recognized fields defensively (the
+ * platform may also be called directly, e.g. in tests).
+ */
+export declare function extractFetchParams(object: unknown): FeedFetchParams;
+/**
+ * Apply the `since` and `limit` fetch parameters to built feed entries.
+ *
+ * - `since`: drop entries published before the given instant. Entries without a
+ *   parseable date (`datenum === 0`) are excluded when `since` is set, since we
+ *   cannot confirm they are recent enough. An unparseable `since` is ignored.
+ * - `limit`: return at most `limit` entries, preserving feed order.
+ */
+export declare function applyFetchFilters(articles: Array<PlatformFeedsActivityStream>, params: FeedFetchParams): Array<PlatformFeedsActivityStream>;
+export declare function buildFeedItem(item: Episode, channelUrl: string): PlatformFeedsActivityObject;