Add secure-ws library

.github/workflows/npm-publish-secure-ws.yml

@@ -0,0 +1,89 @@
+name: Release and Publish secure-ws
+
+on: 
+  push:
+    paths:
+      - "secure-ws/**"
+
+env:
+  BRANCH_TAG: "${{ github.ref_name == 'main' && 'latest' || github.ref_name }}"
+  BRANCH: ${{ github.ref_name }}
+  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+jobs:   
+  publish_and_release:
+    name: Publish secure-ws package
+    environment: "${{ github.ref_name == 'main' && 'Prod' || 'Dev' }}"
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: "secure-ws"
+    steps:
+      - name: Generate token
+        if: ${{ github.ref_name == 'main'}}
+        id: generate_token
+        uses: tibdex/github-app-token@v1
+        with:
+          app_id: ${{ vars.FUNDABOT_APP_ID }}
+          private_key: ${{ secrets.FUNDABOT_PRIVATE_KEY }}
+
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+
+      - uses: actions/checkout@v3
+        with:
+          token: ${{ github.ref_name == 'main' && steps.generate_token.outputs.token || secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Version bump
+        id: version
+        uses: phips28/gh-action-bump-version@v9.1.0
+        with:
+          major-wording: ${{ env.BRANCH == 'main' && '[bump major]' || '[bump major --force]' }}
+          minor-wording: ${{ env.BRANCH == 'main' && '[bump minor]' || '[bump minor --force]' }}
+          patch-wording: ${{ null }}
+          rc-wording: ${{ null }}
+          default: "${{ env.BRANCH == 'main' && 'patch' || 'prerelease' }}"
+          PACKAGEJSON_DIR: "secure-ws"
+          preid: "${{ env.BRANCH }}"
+          skip-tag: "true"
+          skip-push: "true"
+          skip-commit: "true"
+          bump-policy: "ignore"
+
+      - name: Commit changes
+        env:
+          VERSION: ${{ steps.version.outputs.newTag }}
+        run: |
+          git config user.email "fundabot@fundwave.com"
+          git config user.name "fundabot"
+          git commit -a -m "CI: bumps secure-ws to $VERSION" -m "[skip ci]"
+
+      - name: Publish package to npm
+        run: |
+          echo //registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN} > ~/.npmrc
+          echo registry=https://registry.npmjs.org/ >> ~/.npmrc
+          npm publish --tag $BRANCH_TAG --access public
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPMJS_TOKEN}}
+
+      - name: Push changes
+        uses: ad-m/github-push-action@master
+        with:
+          github_token: ${{ env.GITHUB_TOKEN }}
+          branch: ${{ github.ref }}
+
+      - name: Release
+        if: ${{ github.ref_name == 'main'}}
+        env:
+          VERSION: ${{ steps.version.outputs.newTag }}
+        run: |
+          if [ "${BRANCH}" != "main" ]; then PRERELEASE="-p"; fi
+          echo "Releasing version ${VERSION} on branch ${BRANCH}"
+          gh release create ${VERSION} --target ${BRANCH} --generate-notes ${PRERELEASE}

.gitignore

@@ -0,0 +1,2 @@
+**/dist/**
+**/node_modules/**

.talismanrc

@@ -1,19 +1,23 @@
-threshold: medium
 fileignoreconfig:
-  - filename: aws-credentials-utils/store-credentials.sh
-    checksum: 784aec6e80314be796af73887ba630fbaf0e116cc4d11bd5cba787a20f9c4bbb
-  - filename: jwks-slim/README.md
-    checksum: a1954df51e49fc6a09d7fe04bac198fe60a4fb39b2569180475a749a72df472d
-  - filename: jwks-slim/package-lock.json
-    checksum: d014d548f9f2997cbe1d7c4f7ec312f8c634e88788bc453ccc606ea70e081a77
-  - filename: jwks-slim/tests/cache.test.js
-    checksum: 716f25000789d7ca18adfe07f968bae6eb2fbfa1c3d05e9e92897b9597ac5f17
-  - filename: jwks-slim/tests/mock.js
-    checksum: 0d2fd2ec4847acda384c398e04e8aab9a615a8599b0a06d685e7fb100e71537c
-  - filename: jwks-slim/tests/keys.js
-    checksum: 207c0d07dea4c069883822b2b268d3b34c8b18bdfd645b8aa3b2be20f280c270
-  - filename: jwks-slim/tests/index.test.js
-    checksum: 992a5c1f6c254fd344ae52955aa0c1c22a59e0472fe836b0450ff499255ef6f8
-  - filename: aws-ssm/package-lock.json
-    checksum: 4cf91061e42ed9b1aafb17bdf68c9b4b24a7f86b191133ab4095fa635f8f01a0
-version: ""
+- filename: aws-credentials-utils/store-credentials.sh
+  checksum: 784aec6e80314be796af73887ba630fbaf0e116cc4d11bd5cba787a20f9c4bbb
+- filename: aws-ssm/package-lock.json
+  checksum: 4cf91061e42ed9b1aafb17bdf68c9b4b24a7f86b191133ab4095fa635f8f01a0
+- filename: jwks-slim/README.md
+  checksum: a1954df51e49fc6a09d7fe04bac198fe60a4fb39b2569180475a749a72df472d
+- filename: jwks-slim/package-lock.json
+  checksum: d014d548f9f2997cbe1d7c4f7ec312f8c634e88788bc453ccc606ea70e081a77
+- filename: jwks-slim/tests/cache.test.js
+  checksum: 716f25000789d7ca18adfe07f968bae6eb2fbfa1c3d05e9e92897b9597ac5f17
+- filename: jwks-slim/tests/index.test.js
+  checksum: 992a5c1f6c254fd344ae52955aa0c1c22a59e0472fe836b0450ff499255ef6f8
+- filename: jwks-slim/tests/keys.js
+  checksum: 207c0d07dea4c069883822b2b268d3b34c8b18bdfd645b8aa3b2be20f280c270
+- filename: jwks-slim/tests/mock.js
+  checksum: 0d2fd2ec4847acda384c398e04e8aab9a615a8599b0a06d685e7fb100e71537c
+- filename: secure-ws/mocks/express-response.ts
+  checksum: 7774e72616894119c419f7ad86a3da579036b0391fd208766bcdcb96401b8d2c
+- filename: websocket-provider/package-lock.json
+  checksum: 605a2d92b91f08ee577d3b1e7ed38d27eef43573a044608c22466f05ab6eaff7
+threshold: medium
+version: "1.0"

secure-ws/.npmignore

@@ -0,0 +1,20 @@
+# Exclude TypeScript source files and configs
+src/
+*.ts
+*.tsx
+tsconfig.json
+# Exclude node_modules
+node_modules/
+# Exclude test files and folders
+test/
+*.spec.*
+*.test.*
+# Exclude build scripts and configs
+*.log
+*.env
+# Exclude editor and OS files
+.DS_Store
+.vscode/
+.idea/
+# Exclude other common files
+coverage/

secure-ws/README.md

@@ -0,0 +1,46 @@
+# secure-ws
+
+secure-ws is a TypeScript library for secure WebSocket servers that lets you run Express-style middleware during the upgrade handshake, ensuring unauthenticated connections are never left open.
+
+## Why use secure-ws
+
+- Run middleware during the WebSocket upgrade handshake
+- Reuse Express Middlewares for authentication, validation and more
+- Abstract away connection, upgrade, and messaging with Express-style routes, middleware, and controllers.
+
+## Installation
+
+```
+npm install --save secure-ws
+```
+
+## Usage
+
+```typescript
+import express from "express";
+import { WebSocketProvider } from 'secure-ws';
+
+const wsApp = new WebSocketProvider();
+const app = express();
+
+// app.get...
+// app.post...
+
+wsApp.addRoute(
+  "/extract/metrics",
+  {
+    onConnect: [authMiddleware1, authMiddleware2],
+    onMessage: [controller]
+  }
+);
+
+const httpServer = app.listen(PORT, () => {
+  console.info(`Service running at port: ${PORT}`);
+});
+
+httpServer.on('upgrade', wsApp.handleUpgrade);
+```
+
+## License
+
+MIT

secure-ws/core/web-socket-provider.ts

@@ -0,0 +1,99 @@
+import { WebSocketServer } from 'ws';
+import { IncomingMessage } from 'http';
+import { decode } from "@msgpack/msgpack";
+import { randomUUID } from "crypto";
+
+import { WSProtocolCodec } from './ws-protocol-codec';
+import { runExpressMiddleware } from '../utils/middleware-adapter';
+import { injectHttpRequest } from '../utils/inject-http-request';
+
+import { WSController } from '../types/ws-controller';
+import { AddRouteParams } from '../types/add-route-params';
+import { ClientSocket } from '../types/client-socket';
+import { Duplex } from 'stream';
+
+export class WebSocketProvider {
+  public server: WebSocketServer;
+  public clientSockets: Map<string, ClientSocket>;
+  private routes: Record<string, AddRouteParams>;
+
+  constructor() {
+    this.server = new WebSocketServer({ noServer: true });
+    this.server.on('connection', this.handleConnection);
+    this.routes = {};
+    this.clientSockets = new Map();
+  }
+
+  public addRoute = (
+    path: string, 
+    {
+      onConnect,
+      onMessage,
+    } : AddRouteParams
+  ) => {
+    this.routes[path] = {
+      onConnect,
+      onMessage
+    }
+  }
+  public handleUpgrade = (request: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const { pathname } = new URL(request.url!, 'wss://base.url');
+
+    if (this.routes[pathname]) {
+      this.server.handleUpgrade(request, socket, head, (ws: ClientSocket) => {
+
+        ws.id = `${Date.now()}-${randomUUID()}`;
+        this.clientSockets.set(ws.id, ws);
+        ws.on('close', () => {
+          this.clientSockets.delete(ws.id);
+        });
+
+        this.server.emit('connection', ws, request);
+      });
+    } else {
+      console.log('No route for path:', pathname);
+      socket.end();
+    }
+  };
+
+  private handleConnection = async (ws: ClientSocket, request: IncomingMessage) => {
+    const { pathname } = new URL(request.url!, 'wss://base.url');
+
+    let injectedRequest = {} as IncomingMessage;
+
+    if (typeof ws.protocol === 'string' && ws.protocol.trim() !== '') {
+      const httpRequest = WSProtocolCodec.decode(ws.protocol);
+      injectedRequest = injectHttpRequest(request, httpRequest);
+    }
+
+    if(!this.routes[pathname]) {
+      ws.close(1000, 'Unknown path');
+      return;
+    }
+
+    const { onConnect, onMessage } = this.routes[pathname];
+
+    for (const middleware of onConnect) {
+      const res = await runExpressMiddleware(middleware, injectedRequest, ws);
+      if (!res.success) {
+        console.error("Middleware rejected connection:", res.error);
+        ws.send(JSON.stringify({ error: res.error }));
+        ws.close(1000, res.error);
+        return;
+      }
+    }
+
+    ws.on('message', this.handleMessage(ws, onMessage));
+    ws.send(JSON.stringify({ type: "connection:ack" }));
+  };
+
+  private handleMessage = (socket: ClientSocket, onMessage: WSController[]) => {
+    return async (message) => {
+      const request = decode(message) as IncomingMessage;
+
+      for (const controller of onMessage) {
+        await controller(request, socket);
+      }
+    };
+  }
+}

secure-ws/core/ws-protocol-codec.ts

@@ -0,0 +1,16 @@
+export class WSProtocolCodec {
+  static encode(data: unknown): string {
+    const json = JSON.stringify(data);
+    return Buffer.from(json).toString('base64')
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/, "");
+  }
+
+  static decode<T = unknown>(encoded: string): T {
+    let str = encoded.replace(/-/g, "+").replace(/_/g, "/");
+    while (str.length % 4) str += "=";
+    const json = Buffer.from(str, 'base64').toString();
+    return JSON.parse(json) as T;
+  }
+}

secure-ws/index.ts

@@ -0,0 +1,2 @@
+export * from './core/web-socket-provider';
+export * from './core/ws-protocol-codec';

secure-ws/mocks/express-response.ts

@@ -0,0 +1,50 @@
+import { WebSocket } from "ws";
+import { MockResponse as MockResponseType } from "../types/mock-response";
+
+export class MockResponse implements MockResponseType {
+  private socket: WebSocket;
+  public statusCode: number = 200;
+
+  constructor(socket: WebSocket) {
+    this.socket = socket;
+  }
+
+  status(code: number) {
+    this.statusCode = code;
+    return this;
+  }
+
+  send(data) {
+    const responseType = this.statusCode >= 400 ? "error" : "success";
+    this.socket.send(JSON.stringify({ 
+      type: responseType,
+      status: this.statusCode, 
+      data: data 
+    }));
+    this.socket.close();
+    return this;
+  }
+
+  sendStatus(code: number) {
+    this.statusCode = code;
+    const responseType = code >= 400 ? "error" : "success";
+    this.socket.send(JSON.stringify({ 
+      status: code, 
+      statusText: this.getStatusText(),
+      type: responseType 
+    }));
+    this.socket.close();
+    return this;
+  }
+
+  private getStatusText(): string {
+    const statusTexts: { [key: number]: string } = {
+      200: 'OK',
+      401: 'Unauthorized',
+      403: 'Forbidden',
+      404: 'Not Found',
+      500: 'Internal Server Error'
+    };
+    return statusTexts[this.statusCode] || 'Unknown';
+  }
+};