@sockethub/platform-xmpp 5.0.0-beta.0 → 5.0.0-beta.1

package/README.md

@@ -26,6 +26,11 @@ updates through ActivityStreams messages.
 Credentials are sent to Sockethub via a `credentials` message before the
 `connect` verb. The XMPP platform accepts a single `password` field.
 
+Authentication requires an encrypted connection: direct TLS (`xmpps://`) or
+a successful STARTTLS upgrade. If the server does not offer encryption, the
+connection fails before credentials are sent.
+This requirement also applies to automatic reconnections.
+
 ### Credentials object
 
 | Field | Type | Required | Description |
@@ -34,8 +39,40 @@ Credentials are sent to Sockethub via a `credentials` message before the
 | `userAddress` | string | yes | Bare JID, e.g. `user@jabber.net`. |
 | `resource` | string | yes | XMPP resource identifier (e.g. `"phone"`). |
 | `password` | string | yes | SASL password. Use this field for PLAIN-slot tokens too. |
-| `server` | string | no | Overrides the hostname from `userAddress`. |
-| `port` | number | no | Overrides the default port. |
+| `server` | string | no | Overrides the host from `userAddress`. Host name or `xmpp(s)://` URI. |
+| `port` | integer | no | Overrides the default port (1-65535). |
+
+Without a `port`, a bare host is looked up through its `_xmpps-client` and
+`_xmpp-client` SRV records, and its own addresses on ports 5223 (direct TLS)
+and 5222. A bare host with a `port` skips SRV lookup and connects with
+`xmpp://` (STARTTLS) on that port. For direct TLS, set `server` to an
+`xmpps://` URI. The platform does not use HTTP host-meta discovery or the
+WebSocket transport.
+
+An internationalized host name (such as `bücher.example`) works only as a bare
+host without a `port`. With a `port`, or inside an `xmpp(s)://` URI, it is
+refused; use its ASCII form (`xn--bcher-kva.example`) instead.
+
+### Private addresses
+
+The platform refuses to connect to loopback, private, link-local, and cloud
+metadata addresses, using the same address rules as the
+[outbound URL guard](../../docs/configuration.md#outbound-url-guard). To reach
+an XMPP server on a private network, set `allowPrivateAddresses` in this
+platform's `packageConfig` entry:
+
+```json
+{
+  "packageConfig": {
+    "@sockethub/platform-xmpp": {
+      "allowPrivateAddresses": true
+    }
+  }
+}
+```
+
+Do not enable it on a server that accepts untrusted clients. Any client could
+then make Sockethub connect to internal services.
 
 ### Password authentication
 

package/dist/guard.d.ts

@@ -0,0 +1,16 @@
+import type { XmppClientInstance } from "@xmpp/client";
+/**
+ * Refuse XMPP connections to loopback, private, link-local, and cloud
+ * metadata addresses, matching the outbound guard used by the HTTP platforms.
+ *
+ * Every socket gets the shared guarded DNS lookup, which checks the address
+ * actually connected to. IP-literal hosts skip DNS, so they are checked
+ * directly; `@xmpp/resolve` turns SRV and A records into IP literals, so
+ * discovered candidates are checked here too. Transports that do not use a
+ * host/port socket (WebSocket) are refused outright. xmpp.js treats a
+ * refusal as "no transport" and skips that candidate.
+ *
+ * The wrapper lives on the shared module-level prototypes, like
+ * {@link setTlsServername}, and its setting is refreshed on every call.
+ */
+export declare function guardXmppConnections(client: XmppClientInstance, allowPrivateAddresses: boolean): void;

package/dist/index.d.ts

@@ -48,6 +48,8 @@ export default class XMPP implements PersistentPlatformInterface {
     readonly sendToClient: PlatformSendToClient;
     /** @internal Set of bare JIDs for rooms this client has joined. */
     __knownRooms: Set<string>;
+    /** @internal Bare JID of the authenticated account, used by IncomingHandlers. */
+    __bareJid: string | undefined;
     protected __clientConstructor: (options: XmppClientOptions) => XmppClientInstance;
     protected __xml: (name: string, attrs?: Record<string, string | undefined>, ...children: (XmppElement | undefined)[]) => XmppElement;
     private readonly id;