@sockethub/platform-metadata 1.0.1-alpha.6 → 1.0.1-alpha.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +51 -9
  2. package/dist/index.d.ts +134 -0
  3. package/dist/index.js +55994 -55750
  4. package/dist/index.js.map +116 -114
  5. package/dist/schema.d.ts +115 -0
  6. package/package.json +8 -7
  7. package/src/index.ts +0 -63
  8. package/src/schema.ts +0 -22
package/README.md CHANGED
@@ -8,7 +8,7 @@ This platform fetches and extracts metadata from web pages, including Open Graph
8
8
  site information, images, and other structured metadata. It uses the `open-graph-scraper`
9
9
  library to analyze web pages and return structured data in ActivityStreams format.
10
10
 
11
- ## Implemented Verbs (`@type`)
11
+ ## Implemented Verbs (`type`)
12
12
 
13
13
  * **fetch** - Extract metadata from a web page URL
14
14
 
@@ -21,10 +21,15 @@ to clients through the Sockethub service.
21
21
 
22
22
  ```json
23
23
  {
24
- "@type": "fetch",
25
- "context": "metadata",
24
+ "type": "fetch",
25
+ "@context": [
26
+ "https://www.w3.org/ns/activitystreams",
27
+ "https://sockethub.org/ns/context/v1.jsonld",
28
+ "https://sockethub.org/ns/context/platform/metadata/v1.jsonld"
29
+ ],
26
30
  "actor": {
27
- "@id": "https://example.com/page-to-analyze"
31
+ "id": "https://example.com/page-to-analyze",
32
+ "type": "website"
28
33
  }
29
34
  }
30
35
  ```
@@ -35,10 +40,15 @@ The platform returns an ActivityStream object with extracted metadata:
35
40
 
36
41
  ```json
37
42
  {
38
- "@type": "fetch",
39
- "context": "metadata",
43
+ "type": "fetch",
44
+ "@context": [
45
+ "https://www.w3.org/ns/activitystreams",
46
+ "https://sockethub.org/ns/context/v1.jsonld",
47
+ "https://sockethub.org/ns/context/platform/metadata/v1.jsonld"
48
+ ],
40
49
  "actor": {
41
- "@id": "https://example.com/page-to-analyze",
50
+ "id": "https://example.com/page-to-analyze",
51
+ "type": "website",
42
52
  "name": "Example Site"
43
53
  },
44
54
  "object": {
@@ -76,10 +86,42 @@ The platform extracts the following metadata when available:
76
86
  * **open-graph-scraper**: Core library for extracting Open Graph and metadata from web
77
87
  pages
78
88
 
89
+ ## Request Hardening (SSRF Guard)
90
+
91
+ Because the server fetches whatever URL a client supplies as `actor.id`, metadata
92
+ requests are hardened against server-side request forgery (SSRF) and resource
93
+ exhaustion. The fetch runs through a guarded connection layer that:
94
+
95
+ * refuses to connect to loopback, private, link-local, carrier-grade NAT, or
96
+ cloud-metadata addresses (e.g. `169.254.169.254`), in every IPv4/IPv6 spelling,
97
+ validated at connection time so it also covers redirect hops;
98
+ * caps the response body size.
99
+
100
+ ### `allowPrivateAddresses`
101
+
102
+ Set in the Sockethub config file under this platform's `packageConfig` entry:
103
+
104
+ ```json
105
+ {
106
+ "packageConfig": {
107
+ "@sockethub/platform-metadata": {
108
+ "allowPrivateAddresses": true
109
+ }
110
+ }
111
+ }
112
+ ```
113
+
114
+ This disables **only** the private/loopback destination checks. **Do not enable
115
+ it on a server that accepts requests from untrusted clients** — it lets any
116
+ client make the server issue requests to internal services. It defaults to off;
117
+ it is an escape hatch for dev/test harnesses serving fixtures from `localhost`,
118
+ or self-hosted deployments that intentionally fetch intranet pages.
119
+
79
120
  ## Error Handling
80
121
 
81
- If metadata extraction fails (invalid URL, network issues, parsing errors), the platform
82
- will return an error through the standard Sockethub error handling mechanism.
122
+ If metadata extraction fails (invalid URL, network issues, parsing errors, or a
123
+ blocked destination), the platform returns an error through the standard
124
+ Sockethub error handling mechanism.
83
125
 
84
126
  ## Use Cases
85
127
 
package/dist/index.d.ts ADDED
@@ -0,0 +1,134 @@
1
+ import type { ActivityStream, PlatformCallback, PlatformConfig, PlatformInterface, PlatformSession } from "@sockethub/schemas";
2
+ export default class Metadata implements PlatformInterface {
3
+ private readonly log;
4
+ private dispatcher?;
5
+ config: PlatformConfig;
6
+ constructor(session: PlatformSession);
7
+ /**
8
+ * The SSRF-guarded undici dispatcher, created once per instance (its
9
+ * `allowPrivateAddresses` setting comes from packageConfig, fixed before the
10
+ * first job) and reused across fetches so connections/timers are pooled.
11
+ */
12
+ private getDispatcher;
13
+ get schema(): {
14
+ name: string;
15
+ version: string;
16
+ contextUrl: string;
17
+ contextVersion: string;
18
+ schemaVersion: string;
19
+ messages: {
20
+ required: string[];
21
+ properties: {
22
+ type: {
23
+ type: string;
24
+ enum: string[];
25
+ };
26
+ object: boolean;
27
+ };
28
+ };
29
+ responses: {
30
+ type: string;
31
+ required: string[];
32
+ additionalProperties: boolean;
33
+ properties: {
34
+ "@context": {
35
+ type: string;
36
+ items: {
37
+ type: string;
38
+ };
39
+ };
40
+ id: {
41
+ type: string;
42
+ };
43
+ type: {
44
+ enum: string[];
45
+ };
46
+ actor: {
47
+ type: string;
48
+ required: string[];
49
+ additionalProperties: boolean;
50
+ properties: {
51
+ id: {
52
+ type: string;
53
+ };
54
+ type: {
55
+ enum: string[];
56
+ };
57
+ name: {
58
+ type: string;
59
+ };
60
+ };
61
+ };
62
+ object: {
63
+ $ref: string;
64
+ };
65
+ };
66
+ definitions: {
67
+ responses: {
68
+ page: {
69
+ type: string;
70
+ required: string[];
71
+ additionalProperties: boolean;
72
+ properties: {
73
+ type: {
74
+ enum: string[];
75
+ };
76
+ language: {
77
+ type: string;
78
+ };
79
+ title: {
80
+ type: string;
81
+ };
82
+ name: {
83
+ type: string;
84
+ };
85
+ description: {
86
+ type: string;
87
+ };
88
+ image: {
89
+ $ref: string;
90
+ };
91
+ url: {
92
+ type: string;
93
+ };
94
+ favicon: {
95
+ type: string;
96
+ };
97
+ charset: {
98
+ type: string;
99
+ };
100
+ };
101
+ };
102
+ ogImage: {
103
+ type: string;
104
+ items: {
105
+ type: string;
106
+ required: string[];
107
+ additionalProperties: boolean;
108
+ properties: {
109
+ url: {
110
+ type: string;
111
+ };
112
+ type: {
113
+ type: string;
114
+ };
115
+ width: {
116
+ type: string[];
117
+ };
118
+ height: {
119
+ type: string[];
120
+ };
121
+ };
122
+ };
123
+ };
124
+ };
125
+ };
126
+ };
127
+ };
128
+ /**
129
+ * Stateless platforms are always ready to handle jobs.
130
+ */
131
+ isInitialized(): boolean;
132
+ fetch(job: ActivityStream, cb: PlatformCallback): void;
133
+ cleanup(cb: PlatformCallback): void;
134
+ }