@sockethub/platform-irc 4.0.0-alpha.12 → 4.0.0-alpha.14

package/README.md

@@ -18,6 +18,10 @@ 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
@@ -33,8 +37,9 @@ messages.
     "type": "person"
   },
   "target": {
-    "id": "#general@irc.libera.chat",
-    "type": "room"
+    "id": "general@irc.libera.chat",
+    "type": "room",
+    "name": "#general"
   },
   "object": {
     "type": "message",
@@ -58,8 +63,9 @@ messages.
     "type": "person"
   },
   "target": {
-    "id": "#general@irc.libera.chat",
-    "type": "room"
+    "id": "general@irc.libera.chat",
+    "type": "room",
+    "name": "#general"
   }
 }
 ```
@@ -89,6 +95,227 @@ messages.
 }
 ```
 
+### 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": {},
+  "object": {
+    "type": "attendance",
+    "members": ["alice", "bob", "carol"]
+  }
+}
+```
+
+### 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
@@ -106,4 +333,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,136 @@
+/**
+ * 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 sendToClient;
+    private irc2as;
+    private forceDisconnect;
+    private clientConnecting;
+    private initialized;
+    private client?;
+    private jobQueue;
+    private channels;
+    private handledActors;
+    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): void;
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+    /**
+     * 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): void;
+    /**
+     * Disconnect IRC client
+     * @param {object} job activity streams object
+     * @param done
+     */
+    disconnect(job: ActivityStream, done: PlatformCallback): void;
+    cleanup(done: PlatformCallback): any;
+    /**
+     * Resolve an IRC channel name from a job target. Prefers `target.name`,
+     * falling back to the channel segment of `target.id` (`<server>/<channel>`).
+     * Returns undefined when no valid `#channel` can be determined, so callers
+     * never emit a bare `NAMES` command (which floods the client with the
+     * server's entire channel list).
+     */
+    private resolveChannelName;
+    private isJoined;
+    private hasJoined;
+    private hasLeft;
+    private getClient;
+    private ircConnect;
+    private completeJob;
+    private registerListeners;
+}
+export default IRC;