pingerchips-js-server 2.0.0

package/README.md

@@ -0,0 +1,124 @@
+# Pingerchips Server SDK
+
+Server-side SDK for triggering events and authenticating users with Pingerchips.
+
+## Installation
+
+```bash
+npm install pingerchips-js-server
+```
+
+## Usage
+
+### Initialize
+
+```javascript
+import PingerchipsServer from 'pingerchips-js-server';
+
+const pingerchips = new PingerchipsServer('app_id', 'app_secret', {
+  appKey: 'app_key',
+  endpoint: 'https://pinger-processor.pingerchips.com/api'
+});
+```
+
+### Trigger Events
+
+Send events to channels from your server:
+
+```javascript
+await pingerchips.trigger('lobby', 'message', {
+  text: 'Hello from server!',
+  timestamp: Date.now()
+});
+```
+
+### Authenticate Users (Private/Presence Channels)
+
+Implement an auth endpoint on your server:
+
+```javascript
+import express from 'express';
+
+const app = express();
+app.use(express.json());
+
+app.post('/auth', (req, res) => {
+  const { socket_id, channel_name, auth_info } = req.body;
+
+  // Validate user from session/token
+  const user = validateUser(auth_info);
+  if (!user) {
+    return res.status(403).json({ error: 'Unauthorized' });
+  }
+
+  // For presence channels, provide user data
+  const userData = channel_name.startsWith('presence-') ? {
+    user_id: user.id,
+    user_info: {
+      name: user.name,
+      avatar: user.avatar
+    }
+  } : null;
+
+  // Sign authentication with Pingerchips
+  const authData = pingerchips.authenticate(socket_id, channel_name, userData);
+  res.json(authData);
+});
+```
+
+## API Reference
+
+### `new PingerchipsServer(appId, appSecret, options)`
+
+Create a new server instance.
+
+**Options:**
+- `appKey` - Your app key (required for authentication)
+- `endpoint` - API endpoint URL
+- `token` - API token for internal endpoints
+- `mtls` - mTLS configuration for secure connections
+
+### `trigger(channel, event, data)`
+
+Send an event to a channel.
+
+```javascript
+await pingerchips.trigger('my-channel', 'my-event', { message: 'Hello' });
+```
+
+### `authenticate(socketId, channelName, userData?)`
+
+Generate signed authentication for private/presence channels.
+
+**Parameters:**
+- `socketId` - Socket ID from client
+- `channelName` - Channel name (e.g., "private-chat" or "presence-lobby")
+- `userData` - User data for presence channels (must include `user_id`)
+
+**Returns:**
+```javascript
+{
+  auth: "app_key:hmac_signature",
+  channel_data: "{\"user_id\":\"123\",...}" // presence channels only
+}
+```
+
+## mTLS Support
+
+For secure server-to-server communication:
+
+```javascript
+const pingerchips = new PingerchipsServer('app_id', 'app_secret', {
+  endpoint: 'https://pinger-processor.pingerchips.com/api',
+  mtls: {
+    enabled: true,
+    cert: '/path/to/client-cert.pem',
+    key: '/path/to/client-key.pem',
+    ca: '/path/to/ca-cert.pem'
+  }
+});
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,167 @@
+import fs from "fs";
+import https from "https";
+import crypto from "crypto";
+
+class PingerchipsServer {
+  constructor(appId, appSecret, options = {}) {
+    this.appId = appId;
+    this.appSecret = appSecret;
+    this.appKey = options.appKey || appId; // App key for signing
+    this.endpoint =
+      options.endpoint ||
+      process.env.PINGERCHIPS_API_ENDPOINT ||
+      process.env.NODE_ENV === "production"
+        ? "https://pinger-processor.pingerchips.com"
+        : "http://localhost:4000";
+    this.token = options.token;
+
+    // mTLS configuration
+    this.mtls = {
+      enabled: options.mtls?.enabled || false,
+      cert: options.mtls?.cert,
+      key: options.mtls?.key,
+      ca: options.mtls?.ca,
+      rejectUnauthorized: options.mtls?.rejectUnauthorized !== false,
+    };
+
+    this.fetchPromise = import("node-fetch").then((mod) => mod.default);
+  }
+
+  _createHttpsAgent() {
+    if (!this.mtls.enabled) {
+      return undefined;
+    }
+
+    const agentOptions = {
+      rejectUnauthorized: this.mtls.rejectUnauthorized,
+    };
+
+    // Load cert, key, and ca - support both file paths and direct content
+    if (this.mtls.cert) {
+      agentOptions.cert = this._loadCertificate(this.mtls.cert);
+    }
+    if (this.mtls.key) {
+      agentOptions.key = this._loadCertificate(this.mtls.key);
+    }
+    if (this.mtls.ca) {
+      agentOptions.ca = this._loadCertificate(this.mtls.ca);
+    }
+
+    return new https.Agent(agentOptions);
+  }
+
+  _loadCertificate(certOrPath) {
+    // If it looks like a certificate/key content (starts with -----), return as-is
+    if (
+      typeof certOrPath === "string" &&
+      certOrPath.trim().startsWith("-----")
+    ) {
+      return certOrPath;
+    }
+    // Otherwise, treat as file path
+    return fs.readFileSync(certOrPath, "utf8");
+  }
+
+  async trigger(channel, event, data) {
+    const fetch = await this.fetchPromise;
+    const url = `${this.endpoint}/apps/${this.appId}/trigger`;
+
+    const requestOptions = {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        token: this.token,
+      },
+      body: JSON.stringify({
+        app_id: this.appId,
+        app_secret: this.appSecret,
+        channel,
+        event,
+        data,
+      }),
+    };
+
+    // Add HTTPS agent if mTLS is enabled
+    if (this.mtls.enabled) {
+      requestOptions.agent = this._createHttpsAgent();
+    }
+
+    const response = await fetch(url, requestOptions);
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(
+        `Failed to trigger event: ${response.statusText} - ${error.error || ""}`
+      );
+    }
+
+    return await response.json();
+  }
+
+  /**
+   * Authenticate a user for a private or presence channel
+   *
+   * This method is called by your auth endpoint to sign user data.
+   * The signature proves that your server authorized the user to join the channel.
+   *
+   * @param {string} socketId - Socket ID from the client SDK
+   * @param {string} channelName - Channel name (e.g., "private-chat" or "presence-lobby")
+   * @param {object} userData - User data for presence channels (must include user_id)
+   * @returns {object} - Signed authentication data: { auth, channel_data? }
+   *
+   * @example
+   * // In your Express.js auth endpoint:
+   * app.post('/auth', (req, res) => {
+   *   const { socket_id, channel_name, auth_info } = req.body;
+   *
+   *   // Validate user from session/token
+   *   const user = req.session.user;
+   *   if (!user) return res.status(403).json({ error: 'Unauthorized' });
+   *
+   *   // For presence channels, provide user data
+   *   const userData = channel_name.startsWith('presence-') ? {
+   *     user_id: user.id,
+   *     user_info: { name: user.name, avatar: user.avatar }
+   *   } : null;
+   *
+   *   const authData = pingerchips.authenticate(socket_id, channel_name, userData);
+   *   res.json(authData);
+   * });
+   */
+  authenticate(socketId, channelName, userData = null) {
+    // Build the full topic name
+    const fullTopic = `app:${this.appKey}:room:${channelName}`;
+
+    // Build string to sign based on channel type
+    let stringToSign;
+    let channelData = null;
+
+    if (userData && channelName.startsWith("presence-")) {
+      // Presence channel: include user data in signature
+      channelData = JSON.stringify(userData);
+      stringToSign = `${socketId}:${fullTopic}:${channelData}`;
+    } else {
+      // Private channel: just socket_id and topic
+      stringToSign = `${socketId}:${fullTopic}`;
+    }
+
+    // Generate HMAC-SHA256 signature using app_secret
+    const signature = crypto
+      .createHmac("sha256", this.appSecret)
+      .update(stringToSign)
+      .digest("hex");
+
+    const auth = `${this.appKey}:${signature}`;
+
+    // Build response
+    const response = { auth };
+
+    if (channelData) {
+      response.channel_data = channelData;
+    }
+
+    return response;
+  }
+}
+
+export default PingerchipsServer;

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "pingerchips-js-server",
+  "version": "2.0.0",
+  "description": "Pingerchips server SDK for Node.js - trigger events and authenticate users",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "pingerchips",
+    "websocket",
+    "realtime",
+    "server",
+    "backend",
+    "pusher"
+  ],
+  "author": "Pingerchips",
+  "license": "MIT",
+  "dependencies": {
+    "node-fetch": "^3.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pingerchips/pingerchips-js-server"
+  },
+  "bugs": {
+    "url": "https://github.com/pingerchips/pingerchips-js-server/issues"
+  },
+  "homepage": "https://pingerchips.com",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}