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

package/README.md

@@ -26,16 +26,53 @@ 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 |
-|---|---|---|---|
+| --- | --- | --- | --- |
 | `type` | string | yes | Must be `"credentials"`. |
 | `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
 
@@ -280,6 +317,31 @@ non-recoverable connection error.
 }
 ```
 
+## Incoming presence and roster
+
+Live presence arrives as an `update` with `object.type` `presence`. `actor.id`
+is the sender's full JID, with `actor.type` `room` for a joined room and
+`person` otherwise; when the stanza has no `to`, `actor.name` is the resource
+part. `object.presence` is the `<show>` value, `offline` for an `unavailable`
+stanza, and `online` otherwise. A `<status>` element is copied to
+`object.content`. The responses schema accepts only `away`, `chat`, `dnd`,
+`xa`, `offline`, `online`, and `notauthorized`; a stanza with any other
+`<show>` value is dropped and the server logs
+`dropping malformed outbound message`.
+
+Roster data (`jabber:iq:roster`) is trusted only from the server (a stanza
+with no `from`) or from this account's own bare JID, per
+[RFC 6121 section 2.1.6](https://www.rfc-editor.org/rfc/rfc6121#section-2.1.6).
+Any other sender, including this account's full JID, is ignored and produces
+no client event. Roster items with subscription `none`, `to`, or `from`
+without a pending request are delivered as `request-friend`, with the contact
+JID and roster name in `actor`. Items with a mutual (`both`) subscription are
+delivered as a presence `update` with `object.presence` `online`; items where
+this account's own subscription request is still pending (`from` with
+`ask="subscribe"`) are delivered as a presence `update` with
+`object.presence` `notauthorized`. Every roster
+activity carries this account's bare JID in `target.id`.
+
 ## Features
 
 * **Instant messaging**: Send and receive one-on-one messages

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;