@sockethub/platform-irc 4.0.0-alpha.8 → 4.0.0-beta.0

package/README.md

@@ -8,7 +8,7 @@ This platform provides IRC client functionality, allowing web applications to co
 IRC servers, join channels, send messages, and handle IRC events through ActivityStreams
 messages.
 
-## Implemented Verbs (`@type`)
+## Implemented Verbs (`type`)
 
 * **send** - Send messages to channels or users
 * **join** - Join IRC channels
@@ -18,20 +18,31 @@ messages.
 
 ## Usage
 
+IRC room targets use `#channel@server` in `target.id` (for example
+`#general@irc.libera.chat`). When you include `target.name`, use the channel
+name as it appears on IRC (for example `#general`).
+
 ### Send Message Example
 
 ```json
 {
-  "@type": "send",
-  "context": "irc",
+  "type": "send",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
   "actor": {
-    "@id": "mynick@irc.libera.chat"
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
   },
   "target": {
-    "@id": "#general@irc.libera.chat"
+    "id": "#general@irc.libera.chat",
+    "type": "room",
+    "name": "#general"
   },
   "object": {
-    "@type": "Note",
+    "type": "message",
     "content": "Hello IRC channel!"
   }
 }
@@ -41,13 +52,20 @@ messages.
 
 ```json
 {
-  "@type": "join",
-  "context": "irc",
+  "type": "join",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
   "actor": {
-    "@id": "mynick@irc.libera.chat"
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
   },
   "target": {
-    "@id": "#general@irc.libera.chat"
+    "id": "#general@irc.libera.chat",
+    "type": "room",
+    "name": "#general"
   }
 }
 ```
@@ -56,21 +74,318 @@ messages.
 
 ```json
 {
-  "@type": "send",
-  "context": "irc",
+  "type": "send",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
   "actor": {
-    "@id": "mynick@irc.libera.chat"
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
   },
   "target": {
-    "@id": "friend@irc.libera.chat"
+    "id": "friend@irc.libera.chat",
+    "type": "person"
   },
   "object": {
-    "@type": "Note",
+    "type": "message",
     "content": "Hello friend!"
   }
 }
 ```
 
+### Update Topic Example
+
+```json
+{
+  "type": "update",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
+  },
+  "target": {
+    "id": "#general@irc.libera.chat",
+    "type": "room",
+    "name": "#general"
+  },
+  "object": {
+    "type": "topic",
+    "content": "New channel topic"
+  }
+}
+```
+
+### Update Nickname Example
+
+```json
+{
+  "type": "update",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
+  },
+  "target": {
+    "id": "newnick@irc.libera.chat",
+    "type": "person"
+  },
+  "object": {
+    "type": "address"
+  }
+}
+```
+
+### Query Attendance Example
+
+```json
+{
+  "type": "query",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
+  },
+  "target": {
+    "id": "#general@irc.libera.chat",
+    "type": "room",
+    "name": "#general"
+  },
+  "object": {
+    "type": "attendance"
+  }
+}
+```
+
+### Query Attendance Response Example
+
+```json
+{
+  "type": "query",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "#general@irc.libera.chat",
+    "type": "room",
+    "name": "#general"
+  },
+  "target": {
+    "id": "mynick@irc.libera.chat",
+    "type": "person",
+    "name": "mynick"
+  },
+  "object": {
+    "type": "attendance",
+    "members": ["alice", "bob", "carol"],
+    "roles": { "alice": "owner", "bob": "participant" }
+  }
+}
+```
+
+`roles` maps a nick to `owner` (channel op, admin or founder), `admin` (half-op)
+or `participant` (voiced). Nicks absent from it are plain members.
+
+### Query Channels Example
+
+Lists channels on the server. `object.name` is an optional `LIST` mask (one
+parameter, no spaces). Rows use the server's `CHANTYPES` (`#` and `&` by
+default). The server still sends every row; the response is capped at 5000
+items and includes `"truncated": true` when rows were dropped.
+
+```json
+{
+  "type": "query",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
+  },
+  "target": {
+    "id": "irc.libera.chat",
+    "type": "service"
+  },
+  "object": {
+    "type": "channels",
+    "name": "#sockethub*"
+  }
+}
+```
+
+### Query Channels Response Example
+
+One message is sent once the server finishes the list.
+
+```json
+{
+  "type": "query",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "irc.libera.chat",
+    "type": "service",
+    "name": "irc.libera.chat"
+  },
+  "object": {
+    "type": "channels",
+    "items": [
+      {
+        "id": "#sockethub@irc.libera.chat",
+        "type": "room",
+        "name": "#sockethub",
+        "members": 12,
+        "summary": "Sockethub development"
+      }
+    ]
+  }
+}
+```
+
+### Disconnect Example
+
+```json
+{
+  "type": "disconnect",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
+  }
+}
+```
+
+## Authentication
+
+Authenticated connections use SASL. Two mechanisms are supported:
+
+* **`PLAIN`** — sends a username and secret via SASL PLAIN. This is the
+  default mechanism, and is supported by most IRC networks (Libera.Chat,
+  OFTC, etc.). Both `password` and `token` use PLAIN by default. Use
+  `token` for personal access tokens (e.g. Libera.Chat NickServ tokens)
+  to avoid storing primary account passwords.
+* **`OAUTHBEARER`** — sends an OAuth 2.0 access token instead of a password
+  ([RFC 7628](https://datatracker.ietf.org/doc/html/rfc7628)). Requires
+  `saslMechanism: "OAUTHBEARER"` to be set explicitly. Adoption on
+  public IRC networks is still limited; the main deployment is SourceHut's
+  `chat.sr.ht` (via the [soju](https://soju.im/) bouncer). Major networks
+  such as Libera.Chat, OFTC, and Hackint do not currently advertise
+  OAUTHBEARER. See emersion's [IRC × OAuth 2.0](https://emersion.fr/blog/2022/irc-and-oauth2/)
+  writeup for background. How to obtain the token is provider-specific and
+  outside the scope of this module.
+
+`password` and `token` are mutually exclusive. Both default to SASL PLAIN;
+set `saslMechanism: "OAUTHBEARER"` explicitly for OAuth 2.0 bearer tokens.
+Secure connections validate the IRC server's TLS certificate by default. The
+optional `allowInvalidCert` field defaults to `false`; when set to `true`, it
+disables TLS certificate validation for secure connections. Use this
+security-relevant opt-out only for trusted self-signed IRC networks.
+
+### Credentials with password (SASL PLAIN)
+
+```json
+{
+  "type": "credentials",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
+  },
+  "object": {
+    "type": "credentials",
+    "nick": "mynick",
+    "server": "irc.libera.chat",
+    "password": "secret",
+    "port": 6697,
+    "secure": true
+  }
+}
+```
+
+### Credentials with personal access token (SASL PLAIN)
+
+Networks like Libera.Chat accept NickServ personal access tokens via
+SASL PLAIN. Use the `token` field instead of `password` to make the
+distinction clear:
+
+```json
+{
+  "type": "credentials",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "mynick@irc.libera.chat",
+    "type": "person"
+  },
+  "object": {
+    "type": "credentials",
+    "nick": "mynick",
+    "server": "irc.libera.chat",
+    "token": "my-personal-access-token",
+    "port": 6697,
+    "secure": true
+  }
+}
+```
+
+### Credentials with OAuth token (SASL OAUTHBEARER)
+
+```json
+{
+  "type": "credentials",
+  "@context": [
+    "https://www.w3.org/ns/activitystreams",
+    "https://sockethub.org/ns/context/v1.jsonld",
+    "https://sockethub.org/ns/context/platform/irc/v1.jsonld"
+  ],
+  "actor": {
+    "id": "mynick@chat.sr.ht",
+    "type": "person"
+  },
+  "object": {
+    "type": "credentials",
+    "nick": "mynick",
+    "server": "chat.sr.ht",
+    "token": "oauth-access-token",
+    "saslMechanism": "OAUTHBEARER",
+    "port": 6697,
+    "secure": true
+  }
+}
+```
+
 ## Features
 
 * **Channel communication**: Join and participate in IRC channels
@@ -88,4 +403,5 @@ 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/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * This is a platform for Sockethub implementing IRC 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, PersistentPlatformConfig, PersistentPlatformInterface, PlatformCallback, PlatformSchemaStruct, PlatformSession } from "@sockethub/schemas";
+import { type IrcSocketInstance } from "irc-socket-sasl";
+import type { PlatformIrcCredentialsObject } from "./types.js";
+export type { IrcSocketInstance } from "irc-socket-sasl";
+export type { PlatformIrcCredentialsObject } from "./types.js";
+export declare function flattenConnectOptions(options: Record<string, unknown>): Record<string, unknown>;
+export type GetClientCallback = (err: string | null, client?: IrcSocketInstance) => void;
+/**
+ * Handles all actions related to communication via the IRC protocol.
+ */
+export declare class IRC implements PersistentPlatformInterface {
+    private readonly log;
+    credentialsHash: string | undefined;
+    config: PersistentPlatformConfig;
+    private readonly updateActor;
+    private readonly prepareActorUpdate?;
+    private readonly sendToClient;
+    private irc2as;
+    private forceDisconnect;
+    private clientConnecting;
+    private initialized;
+    private client?;
+    private jobQueue;
+    private pongAcksToSkip;
+    private channels;
+    private handledActors;
+    private credentials?;
+    constructor(session: PlatformSession);
+    /**
+     * JSON schema defining the types this platform accepts.
+     *
+     * `password` and `token` are mutually exclusive. Both default to SASL
+     * PLAIN; set `saslMechanism: 'OAUTHBEARER'` explicitly for OAuth 2.0
+     * bearer tokens (RFC 7628). See the package README for canonical
+     * credentials payload examples.
+     */
+    get schema(): PlatformSchemaStruct;
+    /**
+     * Returns whether the platform is ready to handle jobs.
+     * For IRC, this means we have successfully connected to the server.
+     */
+    isInitialized(): boolean;
+    /**
+     * Function: connect
+     *
+     * Connect to an IRC server.
+     *
+     * @param {object} job activity streams object
+     * @param {object} credentials credentials object
+     * @param {object} done callback when job is done
+     */
+    connect(job: ActivityStream, credentials: PlatformIrcCredentialsObject, done: PlatformCallback): void;
+    /**
+     * Function: join
+     *
+     * Join a room or private conversation.
+     *
+     * @param {object} job activity streams object
+     * @param {object} done callback when job is done
+     */
+    join(job: ActivityStream, done: PlatformCallback): any;
+    /**
+     * Function leave
+     *
+     * Leave a room or private conversation.
+     *
+     * @param {object} job activity streams object
+     * @param {object} done callback when job is done
+     */
+    leave(job: ActivityStream, done: PlatformCallback): any;
+    /**
+     * Function: send
+     *
+     * Send a message to a room or private conversation.
+     *
+     * @param {object} job activity streams object
+     * @param {object} done callback when job is done
+     */
+    send(job: ActivityStream, done: PlatformCallback): any;
+    /**
+     * Function: update
+     *
+     * Indicate a change (i.e. room topic update, or nickname change).
+     *
+     * @param {object} job activity streams object
+     * @param {object} credentials credentials to verify this user is the right one
+     * @param {object} done callback when job is done
+     */
+    update(job: ActivityStream, credentials: PlatformIrcCredentialsObject, done: PlatformCallback): any;
+    /**
+     * Function: query
+     *
+     * Indicate an intent to query something (e.g. get a list of users in a room).
+     *
+     * @param {object} job activity streams object
+     * @param {object} done callback when job is done
+     */
+    query(job: ActivityStream, done: PlatformCallback): any;
+    /**
+     * Disconnect IRC client
+     * @param {object} job activity streams object
+     * @param done
+     */
+    disconnect(job: ActivityStream, done: PlatformCallback): void;
+    cleanup(done: PlatformCallback): any;
+    /**
+     * Resolve an activity target to its IRC recipient (channel or nick).
+     *
+     * Targets are server-qualified for consistency with what the platform emits
+     * (see irc2as): rooms are addressed as `#channel@server` and users
+     * (private messages) as
+     * `nick@server` — the same `@server` suffix for both. Returns `null` for a
+     * `room` target that isn't server-qualified (a bare channel), which callers
+     * reject — bare channel names are no longer accepted.
+     *
+     * @param target activity stream target (`job.target`)
+     * @returns the IRC channel (`#channel`) or nick, or `null` for a bare room
+     */
+    private resolveIrcTarget;
+    private isJoined;
+    private hasJoined;
+    private hasLeft;
+    /**
+     * A socket holds exactly one nick. Replace whatever handledActors held
+     * rather than deleting the actor a job was addressed as: after a rename
+     * the store rejected, the client still addresses jobs as the old actor,
+     * so deleting by job actor leaves the nick the socket released behind
+     * and whoever takes it next is treated as this connection.
+     */
+    private setSocketNick;
+    private getClient;
+    private ircConnect;
+    private completeJob;
+    private isNickAck;
+    private adoptForcedNickChange;
+    private registerListeners;
+}
+export default IRC;