@sockethub/platform-metadata 1.0.1-alpha.7 → 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 +34 -2
  2. package/dist/index.d.ts +134 -0
  3. package/dist/index.js +55688 -55472
  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 -34
package/README.md CHANGED
@@ -86,10 +86,42 @@ The platform extracts the following metadata when available:
86
86
  * **open-graph-scraper**: Core library for extracting Open Graph and metadata from web
87
87
  pages
88
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
+
89
120
  ## Error Handling
90
121
 
91
- If metadata extraction fails (invalid URL, network issues, parsing errors), the platform
92
- 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.
93
125
 
94
126
  ## Use Cases
95
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
+ }