@sockethub/platform-xmpp 5.0.0-alpha.9 → 5.0.0-beta.1

package/README.md

@@ -8,63 +8,311 @@ This platform provides XMPP client functionality, allowing web applications to c
 XMPP servers, send messages, manage contacts, join chat rooms, and handle presence
 updates through ActivityStreams messages.
 
-## Implemented Verbs (`@type`)
+## Implemented Verbs (`type`)
 
+* **connect** - Establish a connection to the XMPP server
+* **disconnect** - Close the XMPP connection
+* **join** - Join an XMPP chat room (MUC)
+* **leave** - Leave an XMPP chat room
 * **send** - Send messages to contacts or chat rooms
-* **join** - Join XMPP chat rooms (MUCs)
-* **observe** - Subscribe to presence updates
-* **request-friend** - Send contact/buddy requests
-* **remove-friend** - Remove contacts from roster
-* **make-friend** - Accept contact requests
 * **update** - Update presence status and information
+* **request-friend** - Send a contact/buddy request
+* **remove-friend** - Remove a contact from the roster
+* **make-friend** - Accept a contact request
+* **query** - Query room attendance and room information via service discovery
+
+## Authentication
+
+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 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
+
+Use a standard XMPP account password. The server negotiates the strongest
+available SASL mechanism (typically SCRAM-SHA-1, falling back to PLAIN).
+The examples below assume you already have an initialized Sockethub client
+instance named `sc`.
+
+```javascript
+{
+  type: "credentials",
+  "@context": sc.contextFor("xmpp"),
+  actor: { id: "user@jabber.net", type: "person" },
+  object: {
+    type: "credentials",
+    userAddress: "user@jabber.net",
+    password: "s3cret",
+    resource: "phone"
+  }
+}
+```
+
+If your deployment expects a bearer-style token in the SASL PLAIN password
+slot, pass that token string as `password`. This is only a narrow
+compatibility mode. Dedicated token SASL mechanisms such as ejabberd
+`X-OAUTH2`, Prosody `OAUTHBEARER`, Prosody community `X-TOKEN`, and SASL2 FAST
+are not implemented by the bundled `@xmpp/client`, which only supports
+`SCRAM-SHA-1`, `PLAIN`, and `ANONYMOUS` and prefers `SCRAM-SHA-1` when both
+SCRAM and PLAIN are offered.
+
+A failed authentication with either a traditional password or a token string
+surfaces the same `SASLError: not-authorized` and is treated as a
+non-recoverable connection error.
 
 ## Usage
 
+### Connect Example
+
+```javascript
+{
+  type: "connect",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "user@example.org/web",
+    type: "person"
+  }
+}
+```
+
 ### Send Message Example
 
-```json
+```javascript
+{
+  type: "send",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "user@example.org",
+    type: "person"
+  },
+  target: {
+    id: "friend@jabber.net",
+    type: "person"
+  },
+  object: {
+    type: "message",
+    content: "Hello from Sockethub!"
+  }
+}
+```
+
+### Send Room Message Example
+
+```javascript
 {
-  "@type": "send",
-  "context": "xmpp",
-  "actor": {
-    "@id": "user@example.org"
+  type: "send",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "user@example.org/web",
+    type: "person"
   },
-  "target": {
-    "@id": "friend@jabber.net"
+  target: {
+    id: "room@conference.example.org",
+    type: "room"
   },
-  "object": {
-    "@type": "Note",
-    "content": "Hello from Sockethub!"
+  object: {
+    type: "message",
+    content: "Hello room"
+  }
+}
+```
+
+### Update Presence Example
+
+```javascript
+{
+  type: "update",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "user@example.org/web",
+    type: "person"
+  },
+  object: {
+    type: "presence",
+    presence: "away",
+    content: "Out for lunch"
+  }
+}
+```
+
+### Query Room Attendance Response Example
+
+```javascript
+{
+  type: "query",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "room@conference.example.org",
+    type: "room"
+  },
+  target: {
+    id: "user@example.org/web",
+    type: "person"
+  },
+  object: {
+    type: "attendance",
+    members: ["alice", "bob", "carol"]
+  }
+}
+```
+
+### Query Room Attendance Example
+
+```javascript
+{
+  type: "query",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "user@example.org/web",
+    type: "person"
+  },
+  target: {
+    id: "room@conference.example.org",
+    type: "room"
+  },
+  object: {
+    type: "attendance"
+  }
+}
+```
+
+### Query Room Information Example
+
+```javascript
+{
+  type: "query",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "user@example.org/web",
+    type: "person"
+  },
+  target: {
+    id: "room@conference.example.org",
+    type: "room"
+  },
+  object: {
+    type: "room-info"
+  }
+}
+```
+
+### Query Room Information Response Example
+
+```javascript
+{
+  type: "query",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "room@conference.example.org",
+    type: "room",
+    name: "Room Display Name"
+  },
+  target: {
+    id: "user@example.org/web",
+    type: "person"
+  },
+  object: {
+    type: "room-info",
+    features: ["http://jabber.org/protocol/muc", "muc_passwordprotected"],
+    identities: [{
+      category: "conference",
+      type: "text",
+      name: "Room Display Name"
+    }]
+  }
+}
+```
+
+### Disconnect Example
+
+```javascript
+{
+  type: "disconnect",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "user@example.org/web",
+    type: "person"
   }
 }
 ```
 
 ### Join Chat Room Example
 
-```json
+```javascript
 {
-  "@type": "join",
-  "context": "xmpp",
-  "actor": {
-    "@id": "user@example.org"
+  type: "join",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "user@example.org",
+    type: "person"
   },
-  "target": {
-    "@id": "room@conference.example.org"
+  target: {
+    id: "room@conference.example.org",
+    type: "room"
   }
 }
 ```
 
 ### Request Friend Example
 
-```json
+```javascript
 {
-  "@type": "request-friend",
-  "context": "xmpp",
-  "actor": {
-    "@id": "user@example.org"
+  type: "request-friend",
+  "@context": sc.contextFor("xmpp"),
+  actor: {
+    id: "user@example.org",
+    type: "person"
   },
-  "target": {
-    "@id": "friend@jabber.net"
+  target: {
+    id: "friend@jabber.net",
+    type: "person"
   }
 }
 ```
@@ -86,4 +334,5 @@ updates through ActivityStreams messages.
 
 ## API
 
-Detailed API documentation can be found [here](API.md)
+API reference docs are generated from the source JSDoc and are not committed to this repository.
+Run `bun run doc` in this package to generate them locally.

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/incoming-handlers.d.ts

@@ -0,0 +1,25 @@
+import type { XmppElement } from "@xmpp/client";
+import type { XmppHandlerSession } from "./types.js";
+export declare class IncomingHandlers {
+    /** @internal Exposed to allow test access for null-handling validation. */
+    session: XmppHandlerSession | undefined;
+    constructor(session?: XmppHandlerSession);
+    close(): void;
+    error(err: {
+        text?: string;
+        condition?: string;
+        toString(): string;
+    }): void;
+    presence(stanza: XmppElement): void;
+    subscribe(to: {
+        id: string;
+        type: string;
+    }, from: string, name?: string): void;
+    notifyChatMessage(stanza: XmppElement): void;
+    notifyError(stanza: XmppElement): void;
+    notifyRoomAttendance(stanza: XmppElement): void;
+    notifyRoomInfo(stanza: XmppElement): void;
+    notifyRoomInfoError(stanza: XmppElement): void;
+    online(): void;
+    stanza(stanza: XmppElement): void;
+}

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+/**
+ * This is a platform for Sockethub implementing XMPP 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, Logger, PersistentPlatformConfig, PersistentPlatformInterface, PlatformCallback, PlatformSchemaStruct, PlatformSendToClient } from "@sockethub/schemas";
+import { type XmppClientInstance, type XmppClientOptions, type XmppElement } from "@xmpp/client";
+import type { XmppCredentialsObject, XmppPlatformSession } from "./types.js";
+export type { XmppCredentialsObject, XmppPlatformSession } from "./types.js";
+/**
+ * xmpp.js never sets TLS SNI, and `@xmpp/resolve` connects to raw IPs from
+ * SRV/A lookups, so direct TLS (`xmpps://`) is validated against the IP and
+ * fails (ERR_TLS_CERT_ALTNAME_INVALID). Both connect paths call
+ * `Transport.prototype.socketParameters(uri)`, so wrapping the prototypes
+ * covers them.
+ *
+ * The transport classes are shared module-level prototypes, so the wrapper is
+ * installed once per prototype and keeps the active domain in prototype state.
+ * That state is refreshed on every call: a later client for a different JID
+ * domain must not reuse the first wrapper's servername, and an IP-literal
+ * domain must send no SNI at all. Remove once xmpp.js sets `servername`
+ * upstream (xmppjs/xmpp.js#1128) and `@xmpp/*` is bumped.
+ */
+export declare function setTlsServername(client: XmppClientInstance, domain: string): void;
+/**
+ * Handles all actions related to communication via. the XMPP protocol.
+ *
+ * Uses `xmpp.js` as a base tool for interacting with XMPP.
+ *
+ * {@link https://github.com/xmppjs/xmpp.js}
+ */
+export default class XMPP implements PersistentPlatformInterface {
+    credentialsHash: string | undefined;
+    readonly config: PersistentPlatformConfig;
+    readonly log: Logger;
+    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;
+    private __initialized;
+    /** @internal Exposed for test access and IncomingHandlers. */
+    __client: XmppClientInstance | undefined;
+    /**
+     * Constructor called from the Sockethub `Platform` instance, passing in a
+     * session object.
+     * @param session - {@link XmppPlatformSession}
+     */
+    constructor(session: XmppPlatformSession);
+    protected createClient(): void;
+    protected createXml(): void;
+    /**
+     * Mark the platform as disconnected and uninitialized
+     * @param stopReconnection - If true, stop automatic reconnection
+     */
+    private __markDisconnected;
+    /**
+     * Classify error to determine if reconnection should be attempted
+     * @param err - The error from XMPP client
+     * @returns 'RECOVERABLE' or 'NON_RECOVERABLE'
+     */
+    private __classifyError;
+    /**
+     * Check if the XMPP client is properly connected and can send messages
+     * @returns true if client is connected and operational
+     */
+    private __isClientConnected;
+    /**
+     * @description
+     * JSON schema defining the types this platform accepts.
+     *
+     * Deployments that accept a bearer-style token in the SASL PLAIN password
+     * slot should still pass that token string as `password`. Dedicated token
+     * SASL mechanisms such as ejabberd `X-OAUTH2`, Prosody `OAUTHBEARER`,
+     * Prosody community `X-TOKEN`, and SASL2 FAST are not implemented by this
+     * client. See the package README for canonical credentials and usage
+     * payload examples.
+     **/
+    get schema(): PlatformSchemaStruct;
+    /**
+     * Returns whether the platform is ready to handle jobs.
+     * For XMPP, this means we have successfully connected to the server.
+     * During temporary network interruptions with automatic reconnection,
+     * remains true to allow queued jobs to retry rather than fail.
+     * @returns true if ready to handle jobs
+     */
+    isInitialized(): boolean;
+    /**
+     * Connect to the XMPP server.
+     *
+     * @param job - activity streams object
+     * @param credentials - credentials object
+     * @param done - callback when job is done
+     */
+    connect(job: ActivityStream, credentials: XmppCredentialsObject, done: PlatformCallback): void;
+    /**
+     * Join a room, optionally defining a display name for that room.
+     *
+     * @param job - activity streams object
+     * @param done - callback when job is done
+     */
+    join(job: ActivityStream, done: PlatformCallback): Promise<void>;
+    /**
+     * Leave a room
+     *
+     * @param job - activity streams object
+     * @param done - callback when job is done
+     */
+    leave(job: ActivityStream, done: PlatformCallback): void;
+    /**
+     * Send a message to a room or private conversation.
+     *
+     * @param job - activity streams object
+     * @param done - callback when job is done
+     */
+    send(job: ActivityStream, done: PlatformCallback): void;
+    /**
+     * @description
+     * Indicate presence and status message.
+     * Valid presence values are "away", "chat", "dnd", "xa", "offline", "online".
+     *
+     * @param job - activity streams object
+     * @param done - callback when job is done
+     */
+    update(job: ActivityStream, done: PlatformCallback): void;
+    /**
+     * @description
+     * Send friend request
+     *
+     * @param job - activity streams object
+     * @param done - callback when job is done
+     */
+    "request-friend"(job: ActivityStream, done: PlatformCallback): void;
+    /**
+     * @description
+     * Send a remove friend request
+     *
+     * @param job - activity streams object
+     * @param done - callback when job is done
+     */
+    "remove-friend"(job: ActivityStream, done: PlatformCallback): void;
+    /**
+     * @description
+     * Confirm a friend request
+     *
+     * @param job - activity streams object
+     * @param done - callback when job is done
+     */
+    "make-friend"(job: ActivityStream, done: PlatformCallback): void;
+    /**
+     * Indicate an intent to query something (e.g. get room attendance or room information).
+     *
+     * @param job - activity streams object
+     * @param done - callback when job is done
+     */
+    query(job: ActivityStream, done: PlatformCallback): void;
+    /**
+     * Disconnect XMPP client
+     * @param _job - activity streams object
+     * @param done - callback when done
+     */
+    disconnect(_job: ActivityStream, done: PlatformCallback): void;
+    /**
+     * Called when it's time to close any connections or clean data before being wiped
+     * forcefully.
+     * @param done - callback when complete
+     */
+    cleanup(done: PlatformCallback): void;
+    private __registerHandlers;
+}