@sockethub/server 5.0.0-alpha.10

package/src/platform.ts

@@ -0,0 +1,358 @@
+/**
+ * This runs as a stand-alone separate process that handles:
+ * 1. Starting up an instance of a given platform
+ * 2. Connecting to the redis job queue
+ * 3. Sending the platform jobs
+ * 4. Handling the result by putting it in the outgoing queue for
+ * sockethub core to send back to the client.
+ *
+ * If an exception is thrown by the platform, this process will die along with
+ * it and sockethub will start up another process. This ensures memory safety.
+ */
+import { crypto, getPlatformId } from "@sockethub/crypto";
+import {
+    CredentialsStore,
+    type JobDataDecrypted,
+    JobWorker,
+} from "@sockethub/data-layer";
+import type { JobHandler } from "@sockethub/data-layer";
+import type {
+    ActivityStream,
+    CredentialsObject,
+    PersistentPlatformInterface,
+    PlatformCallback,
+    PlatformInterface,
+    PlatformSession,
+} from "@sockethub/schemas";
+import debug from "debug";
+import config from "./config";
+
+// command-line params
+const parentId = process.argv[2];
+const platformName = process.argv[3];
+let identifier = process.argv[4];
+const redisUrl = process.env.REDIS_URL;
+
+const loggerPrefix = `sockethub:platform:${platformName}:${identifier}`;
+let logger = debug(loggerPrefix);
+
+// conditionally initialize sentry
+let sentry: { readonly reportError: (err: Error) => void } = {
+    reportError: (err: Error) => {},
+};
+(async () => {
+    if (config.get("sentry:dsn")) {
+        logger("initializing sentry");
+        sentry = await import("./sentry");
+    }
+})();
+
+let jobWorker: JobWorker;
+let jobWorkerStarted = false;
+let parentSecret1: string;
+let parentSecret2: string;
+
+logger(`platform handler initializing for ${platformName} ${identifier}`);
+
+interface SecretInterface {
+    parentSecret1: string;
+    parentSecret2: string;
+}
+
+interface SecretFromParent extends Array<string | SecretInterface> {
+    0: string;
+    1: SecretInterface;
+}
+
+/**
+ * Initialize platform module
+ */
+const platformSession: PlatformSession = {
+    debug: debug(`sockethub:platform:${platformName}:${identifier}`),
+    sendToClient: getSendFunction("message"),
+    updateActor: updateActor,
+};
+
+const platform: PlatformInterface = await (async () => {
+    const PlatformModule = await import(`@sockethub/platform-${platformName}`);
+    const p = new PlatformModule.default(platformSession) as PlatformInterface;
+    logger(`platform handler loaded for ${platformName} ${identifier}`);
+    return p as PlatformInterface;
+})();
+
+/**
+ * Safely send error message to parent process, handling IPC channel closure
+ */
+function safeProcessSend(message: [string, string]) {
+    if (process.send && process.connected) {
+        try {
+            process.send(message);
+        } catch (ipcErr) {
+            console.error(`Failed to report error via IPC: ${ipcErr.message}`);
+        }
+    } else {
+        console.error("Cannot report error: IPC channel not available");
+    }
+}
+
+/**
+ * Type guard to check if a platform is persistent and has credentialsHash.
+ */
+function isPersistentPlatform(
+    platform: PlatformInterface,
+): platform is PersistentPlatformInterface {
+    return platform.config.persist === true;
+}
+
+/**
+ * Handle any uncaught errors from the platform by alerting the worker and shutting down.
+ */
+process.once("uncaughtException", (err: Error) => {
+    console.log("EXCEPTION IN PLATFORM");
+    sentry.reportError(err);
+    console.log("error:\n", err.stack);
+    safeProcessSend(["error", err.toString()]);
+    process.exit(1);
+});
+
+process.once("unhandledRejection", (err: Error) => {
+    console.log("EXCEPTION IN PLATFORM");
+    sentry.reportError(err);
+    console.log("error:\n", err.stack);
+    safeProcessSend(["error", err.toString()]);
+    process.exit(1);
+});
+
+/**
+ * In the case of a parent disconnect, terminate child process.
+ */
+// Detect parent death via IPC disconnect
+process.on("disconnect", () => {
+    console.log(`Parent disconnected. Child ${process.pid} exiting.`);
+    process.exit(1);
+});
+
+/**
+ * Incoming messages from the worker to this platform. Data is an array, the first property is the
+ * method to call, the rest are params.
+ */
+process.on("message", async (data: SecretFromParent) => {
+    if (data[0] === "secrets") {
+        const { parentSecret2: parentSecret3, parentSecret1: parentSecret } =
+            data[1];
+        parentSecret1 = parentSecret;
+        parentSecret2 = parentSecret3;
+        await startQueueListener();
+    } else {
+        throw new Error("received unknown command from parent thread");
+    }
+});
+
+/**
+ * Returns a function used to handle completed jobs from the platform code (the `done` callback).
+ */
+function getJobHandler(): JobHandler {
+    return async (
+        job: JobDataDecrypted,
+    ): Promise<string | undefined | ActivityStream> => {
+        return new Promise((resolve, reject) => {
+            const jobLog = debug(`${loggerPrefix}:${job.sessionId}`);
+            jobLog(`received ${job.title} ${job.msg.type}`);
+            const credentialStore = new CredentialsStore(
+                parentId,
+                job.sessionId,
+                parentSecret1 + job.msg.sessionSecret,
+                {
+                    url: redisUrl,
+                },
+            );
+            // biome-ignore lint/performance/noDelete: <explanation>
+            delete job.msg.sessionSecret;
+
+            let jobCallbackCalled = false;
+            const doneCallback: PlatformCallback = (
+                err: Error | null,
+                result: null | ActivityStream,
+            ): void => {
+                if (jobCallbackCalled) {
+                    resolve(null);
+                    return;
+                }
+                jobCallbackCalled = true;
+                if (err) {
+                    jobLog(`failed ${job.title} ${job.msg.type}`);
+                    let errMsg: string | Error;
+                    // some error objects (e.g. TimeoutError) don't interpolate correctly
+                    // to being human-readable, so we have to do this little dance
+                    try {
+                        errMsg = err.toString();
+                    } catch (err) {
+                        errMsg = err;
+                    }
+                    sentry.reportError(new Error(errMsg as string));
+                    reject(new Error(errMsg as string));
+                } else {
+                    jobLog(`completed ${job.title} ${job.msg.type}`);
+                    resolve(result);
+                }
+            };
+
+            if (platform.config.requireCredentials?.includes(job.msg.type)) {
+                // This method requires credentials and should be called even if the platform is not
+                // yet initialized, because they need to authenticate before they are initialized.
+
+                // Get credentialsHash for validation.
+                // For persistent platforms: undefined (or empty string) initially, then we set to hash after first
+                // successful call.
+                // For stateless platforms: always undefined (no validation, credentials used once per request)
+                // CredentialsStore skips validation when credentialsHash is falsy (undefined or empty string)
+                const credentialsHash = isPersistentPlatform(platform)
+                    ? platform.credentialsHash
+                    : undefined;
+
+                credentialStore
+                    .get(job.msg.actor.id, credentialsHash)
+                    .then((credentials) => {
+                        // Create wrapper callback that updates credentialsHash after successful call
+                        const wrappedCallback: PlatformCallback = (
+                            err: Error | null,
+                            result: null | ActivityStream,
+                        ): void => {
+                            if (!err && isPersistentPlatform(platform)) {
+                                // Update credentialsHash after successful platform call.
+                                // Only persistent platforms track credential state across requests.
+                                platform.credentialsHash = crypto.objectHash(
+                                    credentials.object,
+                                );
+                            }
+                            doneCallback(err, result);
+                        };
+
+                        // Proceed with platform method call
+                        platform[job.msg.type](
+                            job.msg,
+                            credentials,
+                            wrappedCallback,
+                        );
+                    })
+                    .catch((err) => {
+                        // Credential store error (invalid/missing credentials)
+                        jobLog(`credential error ${err.toString()}`);
+
+                        /**
+                         * Critical distinction: handle credential errors differently based on platform state.
+                         *
+                         * For INITIALIZED platforms (already running):
+                         * - Reject ONLY this job via doneCallback(err, null)
+                         * - Keep the platform process running
+                         * - Why: Platform instances can be shared by multiple clients (sessions).
+                         *   Terminating on credential error would crash the platform for ALL users,
+                         *   including those with valid credentials. This would create a DoS vector
+                         *   where one user's mistake (browser refresh with wrong creds, mistyped
+                         *   password, expired token) would break the service for everyone sharing
+                         *   that platform instance.
+                         * - The failing client receives an error message, while other clients
+                         *   continue operating normally.
+                         *
+                         * For UNINITIALIZED platforms (not yet started):
+                         * - Terminate the platform process via reject(err)
+                         * - Why: If the initial connection fails due to invalid credentials, there's
+                         *   no valid session to preserve. The platform instance was created specifically
+                         *   for this connection attempt and has no other users. Terminating allows
+                         *   proper cleanup and a fresh start on the next attempt.
+                         * - Error is reported to Sentry for monitoring authentication issues.
+                         */
+                        if (platform.config.initialized) {
+                            // Platform already running - reject job only, preserve platform instance
+                            doneCallback(err, null);
+                        } else {
+                            // Platform not initialized - terminate platform process
+                            sentry.reportError(err);
+                            reject(err);
+                        }
+                    });
+            } else if (
+                platform.config.persist &&
+                !platform.config.initialized
+            ) {
+                reject(
+                    new Error(
+                        `${job.msg.type} called on uninitialized platform`,
+                    ),
+                );
+            } else {
+                try {
+                    platform[job.msg.type](job.msg, doneCallback);
+                } catch (err) {
+                    jobLog(`platform call failed ${err.toString()}`);
+                    sentry.reportError(err);
+                    reject(err);
+                }
+            }
+        });
+    };
+}
+
+/**
+ * Get a function which sends a message to the parent thread (PlatformInstance). The platform
+ * can call that function to send messages back to the client.
+ * @param command string containing the type of command to be sent. 'message' or 'close'
+ */
+function getSendFunction(command: string) {
+    return (msg: ActivityStream, special?: string) => {
+        if (platform.config.persist) {
+            process.send([command, msg, special]);
+        } else {
+            logger(
+                "sendToClient called on non-persistent platform, rejecting.",
+            );
+        }
+    };
+}
+
+/**
+ * When a user changes its actor name, the channel identifier changes, we need to ensure that
+ * both the queue thread (listening on the channel for jobs) and the logging object are updated.
+ * @param credentials
+ */
+async function updateActor(credentials: CredentialsObject): Promise<void> {
+    identifier = getPlatformId(platformName, credentials.actor.id);
+    logger(
+        `platform actor updated to ${credentials.actor.id} identifier ${identifier}`,
+    );
+    logger = debug(`sockethub:platform:${identifier}`);
+
+    // Update credentialsHash for persistent platforms (tracks actor-specific state)
+    if (isPersistentPlatform(platform)) {
+        platform.credentialsHash = crypto.objectHash(credentials.object);
+    }
+
+    platform.debug = debug(`sockethub:platform:${platformName}:${identifier}`);
+    process.send(["updateActor", undefined, identifier]);
+    await startQueueListener(true);
+}
+
+/**
+ * Starts listening on the queue for incoming jobs
+ * @param refresh boolean if the param is true, we re-init the `queue.process`
+ * (used when identifier changes)
+ */
+async function startQueueListener(refresh = false) {
+    if (jobWorkerStarted) {
+        if (refresh) {
+            await jobWorker.shutdown();
+        } else {
+            logger("start queue called multiple times, skipping");
+            return;
+        }
+    }
+    jobWorker = new JobWorker(
+        parentId,
+        identifier,
+        parentSecret1 + parentSecret2,
+        { url: redisUrl },
+    );
+    logger("listening on the queue for incoming jobs");
+    jobWorker.onJob(getJobHandler());
+    jobWorkerStarted = true;
+}

package/src/process-manager.ts

@@ -0,0 +1,88 @@
+import { getPlatformId } from "@sockethub/crypto";
+
+import type { IInitObject } from "./bootstrap/init.js";
+import PlatformInstance, {
+    platformInstances,
+    type PlatformInstanceParams,
+    type MessageFromParent,
+} from "./platform-instance.js";
+
+class ProcessManager {
+    private readonly parentId: string;
+    private readonly parentSecret1: string;
+    private readonly parentSecret2: string;
+    private init: IInitObject;
+
+    constructor(
+        parentId: string,
+        parentSecret1: string,
+        parentSecret2: string,
+        init: IInitObject,
+    ) {
+        this.parentId = parentId;
+        this.parentSecret1 = parentSecret1;
+        this.parentSecret2 = parentSecret2;
+        this.init = init;
+    }
+
+    get(
+        platform: string,
+        actorId: string,
+        sessionId?: string,
+    ): PlatformInstance {
+        const platformDetails = this.init.platforms.get(platform);
+        let pi: PlatformInstance;
+
+        if (platformDetails.config.persist) {
+            // ensure process is started - one for each actor
+            pi = this.ensureProcess(platform, sessionId, actorId);
+        } else {
+            // ensure process is started - one for all jobs
+            pi = this.ensureProcess(platform);
+        }
+        pi.config = platformDetails.config;
+        return pi;
+    }
+
+    private createPlatformInstance(
+        identifier: string,
+        platform: string,
+        actor?: string,
+    ): PlatformInstance {
+        const secrets: MessageFromParent = [
+            "secrets",
+            {
+                parentSecret1: this.parentSecret1,
+                parentSecret2: this.parentSecret2,
+            },
+        ];
+        const platformInstanceConfig: PlatformInstanceParams = {
+            identifier: identifier,
+            platform: platform,
+            parentId: this.parentId,
+            actor: actor,
+        };
+        const platformInstance = new PlatformInstance(platformInstanceConfig);
+        platformInstance.initQueue(this.parentSecret1 + this.parentSecret2);
+        platformInstance.process.send(secrets);
+        return platformInstance;
+    }
+
+    private ensureProcess(
+        platform: string,
+        sessionId?: string,
+        actor?: string,
+    ): PlatformInstance {
+        const identifier = getPlatformId(platform, actor);
+        const platformInstance =
+            platformInstances.get(identifier) ||
+            this.createPlatformInstance(identifier, platform, actor);
+        if (sessionId) {
+            platformInstance.registerSession(sessionId);
+        }
+        platformInstances.set(identifier, platformInstance);
+        return platformInstance;
+    }
+}
+
+export default ProcessManager;

package/src/routes.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it } from "bun:test";
+import { existsSync } from "fs";
+import * as sinon from "sinon";
+
+import routes, { basePaths, type IRoutePaths } from "./routes.js";
+
+describe("routes/base", () => {
+    afterEach(() => {
+        sinon.restore();
+    });
+
+    it("can find each of the base files it serves", () => {
+        Object.values(basePaths).forEach((fwd: string) => {
+            try {
+                // eslint-disable-next-line security/detect-non-literal-fs-filename
+                expect(existsSync(fwd)).toBeTrue();
+            } catch (e) {
+                throw new Error(`Unable to resolve path ${fwd}`);
+            }
+        });
+    });
+
+    it("adds base routes", () => {
+        const app = {
+            get: sinon.spy(),
+        };
+        routes.setup(app);
+        sinon.assert.callCount(app.get, Object.keys(basePaths).length);
+    });
+
+    it("handles calls to base routes as expected", () => {
+        const routeHandlers: any = {};
+        const app = {
+            get: (path: string | number, route: any) => {
+                routeHandlers[path] = route;
+            },
+        };
+        routes.setup(app);
+
+        function verifyPathRoutes(pathMap: IRoutePaths) {
+            Object.keys(pathMap).forEach((path) => {
+                const res = {
+                    setHeader: sinon.spy(),
+                    sendFile: sinon.spy(),
+                };
+                expect(pathMap[path].endsWith(".ejs")).toBeFalse();
+                routeHandlers[path]({ url: path }, res);
+                sinon.assert.called(res.setHeader);
+                sinon.assert.calledWith(res.sendFile, pathMap[path]);
+            });
+        }
+        verifyPathRoutes(basePaths);
+    });
+});

package/src/routes.ts

@@ -0,0 +1,61 @@
+import path from "node:path";
+import debug from "debug";
+
+import { __dirname } from "./util.js";
+
+const logger = debug("sockethub:server:routes");
+
+export interface IRoutePaths {
+    [key: string]: string;
+}
+
+export const basePaths: IRoutePaths = {
+    "/sockethub-client.js": path.resolve(
+        __dirname,
+        "..",
+        "res",
+        "sockethub-client.js",
+    ),
+    "/sockethub-client.min.js": path.resolve(
+        __dirname,
+        "..",
+        "res",
+        "sockethub-client.min.js",
+    ),
+    "/socket.io.js": path.resolve(__dirname, "..", "res", "socket.io.js"),
+};
+
+function prepFileRoutes(pathMap) {
+    const _routes = [];
+    for (const key of Object.keys(pathMap)) {
+        _routes.push({
+            meta: {
+                method: "GET",
+                path: key,
+            },
+            route: (req, res) => {
+                logger(`serving resource ${req.url}`);
+                res.setHeader("Access-Control-Allow-Origin", "*");
+                res.sendFile(pathMap[req.url]);
+            },
+        });
+    }
+    return _routes;
+}
+const baseRoutes = prepFileRoutes(basePaths);
+
+function addRoute(app) {
+    return (route) => {
+        app[route.meta.method.toLowerCase()](route.meta.path, route.route);
+    };
+}
+
+/**
+ * Setup
+ */
+const routes = {
+    setup: (app: unknown) => {
+        baseRoutes.forEach(addRoute(app));
+    },
+};
+export default routes;

package/src/sentry.test.ts

@@ -0,0 +1,106 @@
+import { beforeEach, describe, expect, it, mock } from "bun:test";
+import { join } from "path";
+
+// Mock config to avoid loading real configuration
+const mockConfig = {
+    get: mock((key: string) => {
+        if (key === "sentry:dsn") {
+            return "https://ffc702eb2f3b24d9e06ca20e1ef1fd09@o4508859714895872.ingest.de.sentry.io/4508859718369360";
+        }
+        if (key === "sentry") {
+            return {
+                dsn: "https://ffc702eb2f3b24d9e06ca20e1ef1fd09@o4508859714895872.ingest.de.sentry.io/4508859718369360",
+                environment: "test",
+                traceSampleRate: 1.0
+            };
+        }
+        return null;
+    })
+};
+
+describe("Sentry Integration Bug - Issue #918", () => {
+    beforeEach(() => {
+        // Clear any existing Sentry instances
+        delete require.cache[require.resolve("./sentry.js")];
+        mockConfig.get.mockClear();
+    });
+
+    it("should reproduce 'A Proxy's target should be an Object' error", async () => {
+        // This test reproduces the bug by initializing Sentry with Bun server instrumentation
+        // The error occurs when Sentry's Bun integration tries to instrument server options
+        let sentryError: Error | null = null;
+
+        try {
+            // Create a proper mock that implements the config interface
+            const configPath = require.resolve("./config.js");
+            
+            // Clear the config from cache first
+            delete require.cache[configPath];
+            
+            // Mock the config module before importing sentry
+            require.cache[configPath] = {
+                exports: { 
+                    default: mockConfig,
+                    __esModule: true
+                },
+                loaded: true,
+                children: [],
+                parent: null,
+                filename: configPath,
+                id: configPath,
+                paths: [],
+            };
+
+            // Import Sentry module which triggers initialization
+            const sentryPath = require.resolve("./sentry.js");
+            delete require.cache[sentryPath]; // Clear sentry from cache
+            await import("./sentry.js");
+        } catch (error) {
+            sentryError = error as Error;
+        }
+
+        // With the upgrade to @sentry/bun 10.15.0, this should now work without the Proxy error
+        // If we're still on the old version, we'd expect the Proxy error
+        // If we're on the new version, Sentry should initialize successfully
+        if (sentryError) {
+            // If there's still an error, it should NOT be the Proxy error (since we upgraded)
+            expect(sentryError.message).not.toContain("A Proxy's 'target' should be an Object");
+        } else {
+            // Success - the upgrade fixed the issue
+            expect(sentryError).toBeNull();
+        }
+    });
+
+    it("should verify the Sentry version has been upgraded to fix the bug", () => {
+        // This test documents that the problematic version has been fixed
+        const packageJson = require("../package.json");
+        const currentVersion = packageJson.dependencies["@sentry/bun"];
+        
+        // Should now be version 10.x or higher (which fixes the Proxy bug)
+        expect(currentVersion).toMatch(/^(\^?10\.|^10\.|latest)/);
+        
+        // Document the bug details for reference
+        const bugInfo = {
+            brokenVersion: "9.5.0",
+            fixedVersion: "10.15.0", 
+            bugDescription: "A Proxy's 'target' should be an Object",
+            location: "instrumentBunServeOptions in @sentry/bun"
+        };
+        
+        expect(bugInfo.brokenVersion).toBe("9.5.0");
+    });
+});
+
+describe("Sentry Integration Workaround", () => {
+    it("should suggest disabling Sentry DSN as temporary workaround", () => {
+        // Document the workaround: set sentry.dsn to empty string or remove it
+        const workaroundConfig = {
+            sentry: {
+                dsn: "", // Empty DSN disables Sentry
+                environment: "production"
+            }
+        };
+        
+        expect(workaroundConfig.sentry.dsn).toBe("");
+    });
+});

package/src/sentry.ts

@@ -0,0 +1,19 @@
+/**
+ * This file is only imported if sentry reporting is enabled in the Sockethub config.
+ */
+
+import * as Sentry from "@sentry/bun";
+import debug from "debug";
+import config from "./config";
+
+const logger = debug("sockethub:sentry");
+if (!config.get("sentry:dsn")) {
+    throw new Error("Sentry attempted initialization with no DSN provided");
+}
+logger("initialized");
+Sentry.init(config.get("sentry"));
+
+export function reportError(err: Error): void {
+    logger("reporting error");
+    Sentry.captureException(err);
+}