ocpp-ws-io 1.0.0-alpha

package/src/server-client.ts

@@ -0,0 +1,65 @@
+import { WebSocket } from "ws";
+import { OCPPClient } from "./client.js";
+import {
+  ConnectionState,
+  type ClientOptions,
+  type HandshakeInfo,
+} from "./types.js";
+
+/**
+ * OCPPServerClient — A server-side client representation.
+ *
+ * Created by OCPPServer when a charging station connects.
+ * Extends OCPPClient but is pre-connected (cannot call connect()).
+ */
+export class OCPPServerClient extends OCPPClient {
+  private _serverSession: Record<string, unknown>;
+  private _serverHandshake: HandshakeInfo;
+
+  constructor(
+    options: ClientOptions,
+    context: {
+      ws: WebSocket;
+      handshake: HandshakeInfo;
+      session: Record<string, unknown>;
+    },
+  ) {
+    super(options);
+
+    this._serverSession = context.session;
+    this._serverHandshake = context.handshake;
+
+    // Set state to OPEN directly (already connected via server)
+    this._state = ConnectionState.OPEN;
+    this._identity = this._options.identity;
+    this._ws = context.ws;
+    this._protocol = context.ws.protocol;
+
+    // Attach WebSocket handlers
+    this._attachWebsocket(context.ws);
+  }
+
+  /**
+   * Session data associated with this client connection.
+   */
+  get session(): Record<string, unknown> {
+    return this._serverSession;
+  }
+
+  /**
+   * Handshake information from the initial connection.
+   */
+  get handshake(): HandshakeInfo {
+    return this._serverHandshake;
+  }
+
+  /**
+   * Server clients cannot initiate connections.
+   * @throws Always throws — use OCPPClient for outbound connections.
+   */
+  override async connect(): Promise<never> {
+    throw new Error(
+      "Cannot connect from server client — connection is managed by the server",
+    );
+  }
+}

package/src/server.ts

@@ -0,0 +1,374 @@
+import { EventEmitter } from "node:events";
+import {
+  createServer as createHttpServer,
+  type IncomingMessage,
+  type Server,
+} from "node:http";
+import { createServer as createHttpsServer } from "node:https";
+import type { Duplex } from "node:stream";
+import type { TLSSocket } from "node:tls";
+import { WebSocketServer } from "ws";
+
+import { OCPPServerClient } from "./server-client.js";
+import { abortHandshake, parseSubprotocols } from "./ws-util.js";
+
+import {
+  SecurityProfile,
+  type ServerOptions,
+  type CloseOptions,
+  type ListenOptions,
+  type HandshakeInfo,
+  type AuthCallback,
+  type AuthAccept,
+  type EventAdapterInterface,
+  type ClientOptions,
+} from "./types.js";
+
+/**
+ * OCPPServer — A typed WebSocket RPC server for OCPP communication.
+ *
+ * Supports all 3 OCPP Security Profiles:
+ * - Profile 1: Basic Auth over unsecured WS
+ * - Profile 2: TLS + Basic Auth (HTTPS server)
+ * - Profile 3: Mutual TLS (HTTPS server with requestCert)
+ */
+export class OCPPServer extends EventEmitter {
+  private _options: ServerOptions;
+  private _authCallback: AuthCallback | null = null;
+  private _clients = new Set<OCPPServerClient>();
+  private _httpServers = new Set<Server>();
+  private _wss: WebSocketServer | null = null;
+  private _adapter: EventAdapterInterface | null = null;
+  private _httpServerAbortControllers = new Set<AbortController>();
+
+  constructor(options: ServerOptions = {}) {
+    super();
+
+    if (options.strictMode) {
+      if (!options.strictModeValidators && !options.protocols?.length) {
+        throw new Error(
+          "strictMode requires either strictModeValidators or protocols to be specified",
+        );
+      }
+    }
+
+    this._options = {
+      securityProfile: SecurityProfile.NONE,
+      callTimeoutMs: 30000,
+      pingIntervalMs: 30000,
+      deferPingsOnActivity: false,
+      callConcurrency: 1,
+      maxBadMessages: Infinity,
+      respondWithDetailedErrors: false,
+      ...options,
+    };
+  }
+
+  // ─── Getters ─────────────────────────────────────────────────
+
+  get clients(): ReadonlySet<OCPPServerClient> {
+    return this._clients;
+  }
+
+  // ─── Auth ────────────────────────────────────────────────────
+
+  auth(callback: AuthCallback): void {
+    this._authCallback = callback;
+  }
+
+  // ─── Listen ──────────────────────────────────────────────────
+
+  async listen(
+    port = 0,
+    host?: string,
+    options?: ListenOptions,
+  ): Promise<Server> {
+    let httpServer: Server;
+
+    if (options?.server) {
+      // Use existing HTTP/HTTPS server
+      httpServer = options.server;
+    } else {
+      // Create server based on security profile
+      const profile = this._options.securityProfile ?? SecurityProfile.NONE;
+
+      if (
+        profile === SecurityProfile.TLS_BASIC_AUTH ||
+        profile === SecurityProfile.TLS_CLIENT_CERT
+      ) {
+        const tlsOpts = this._options.tls ?? {};
+        const httpsOptions: Record<string, unknown> = {};
+
+        if (tlsOpts.cert) httpsOptions.cert = tlsOpts.cert;
+        if (tlsOpts.key) httpsOptions.key = tlsOpts.key;
+        if (tlsOpts.ca) httpsOptions.ca = tlsOpts.ca;
+        if (tlsOpts.passphrase) httpsOptions.passphrase = tlsOpts.passphrase;
+
+        // Profile 3: Request client certificate (mTLS)
+        if (profile === SecurityProfile.TLS_CLIENT_CERT) {
+          httpsOptions.requestCert = true;
+          httpsOptions.rejectUnauthorized = tlsOpts.rejectUnauthorized ?? true;
+        }
+
+        httpServer = createHttpsServer(httpsOptions);
+      } else {
+        httpServer = createHttpServer();
+      }
+    }
+
+    // Create WebSocketServer attached to noServer mode
+    if (!this._wss) {
+      this._wss = new WebSocketServer({ noServer: true });
+    }
+
+    // Handle upgrade requests
+    const upgradeHandler = (
+      req: IncomingMessage,
+      socket: Duplex,
+      head: Buffer,
+    ) => {
+      this._handleUpgrade(req, socket, head).catch((err) => {
+        this.emit("upgradeError", { error: err, socket });
+      });
+    };
+
+    httpServer.on("upgrade", upgradeHandler);
+    this._httpServers.add(httpServer);
+
+    // Handle abort signal
+    if (options?.signal) {
+      const ac = new AbortController();
+      this._httpServerAbortControllers.add(ac);
+
+      options.signal.addEventListener(
+        "abort",
+        () => {
+          ac.abort();
+          httpServer.close();
+          this._httpServers.delete(httpServer);
+        },
+        { once: true },
+      );
+    }
+
+    // Start listening if we created the server
+    if (!options?.server) {
+      await new Promise<void>((resolve, reject) => {
+        httpServer.on("error", reject);
+        httpServer.listen(port, host, () => {
+          httpServer.removeListener("error", reject);
+          resolve();
+        });
+      });
+    }
+
+    return httpServer;
+  }
+
+  // ─── Handle Upgrade ──────────────────────────────────────────
+
+  get handleUpgrade(): (
+    req: IncomingMessage,
+    socket: Duplex,
+    head: Buffer,
+  ) => Promise<void> {
+    return (req, socket, head) => this._handleUpgrade(req, socket, head);
+  }
+
+  private async _handleUpgrade(
+    req: IncomingMessage,
+    socket: Duplex,
+    head: Buffer,
+  ): Promise<void> {
+    const url = new URL(
+      req.url ?? "/",
+      `http://${req.headers.host ?? "localhost"}`,
+    );
+    const pathParts = url.pathname.split("/").filter(Boolean);
+    const identity = decodeURIComponent(pathParts[pathParts.length - 1] ?? "");
+
+    if (!identity) {
+      abortHandshake(socket, 400, "Missing identity in URL path");
+      return;
+    }
+
+    // Parse subprotocols
+    let protocols = new Set<string>();
+    const protocolHeader = req.headers["sec-websocket-protocol"];
+    if (protocolHeader) {
+      try {
+        protocols = parseSubprotocols(protocolHeader);
+      } catch {
+        abortHandshake(socket, 400, "Invalid Sec-WebSocket-Protocol header");
+        return;
+      }
+    }
+
+    // Negotiate protocol
+    const serverProtocols = this._options.protocols ?? [];
+    let selectedProtocol: string | undefined;
+
+    if (serverProtocols.length > 0 && protocols.size > 0) {
+      selectedProtocol = serverProtocols.find((p) => protocols.has(p));
+      if (!selectedProtocol) {
+        abortHandshake(socket, 400, "No matching subprotocol");
+        return;
+      }
+    }
+
+    // Parse Basic Auth
+    let password: Buffer | undefined;
+    const authHeader = req.headers["authorization"];
+    if (authHeader && authHeader.startsWith("Basic ")) {
+      const decoded = Buffer.from(authHeader.slice(6), "base64").toString();
+      const colonIndex = decoded.indexOf(":");
+      if (colonIndex !== -1) {
+        password = Buffer.from(decoded.slice(colonIndex + 1));
+      }
+    }
+
+    // Get client certificate (Profile 3)
+    let clientCertificate:
+      | ReturnType<TLSSocket["getPeerCertificate"]>
+      | undefined;
+    const profile = this._options.securityProfile ?? SecurityProfile.NONE;
+    if (
+      profile === SecurityProfile.TLS_CLIENT_CERT &&
+      "getPeerCertificate" in socket
+    ) {
+      clientCertificate = (socket as TLSSocket).getPeerCertificate();
+    }
+
+    const handshake: HandshakeInfo = {
+      identity,
+      remoteAddress: req.socket.remoteAddress ?? "",
+      headers: req.headers as Record<string, string | string[] | undefined>,
+      protocols,
+      endpoint: url.pathname,
+      query: url.searchParams,
+      request: req,
+      password,
+      clientCertificate,
+      securityProfile: profile,
+    };
+
+    // Auth callback
+    if (this._authCallback) {
+      const ac = new AbortController();
+
+      try {
+        await new Promise<AuthAccept | void>((resolve, reject) => {
+          let settled = false;
+
+          const accept = (opts?: AuthAccept) => {
+            if (settled) throw new Error("Auth already settled");
+            settled = true;
+            if (opts?.protocol) selectedProtocol = opts.protocol;
+            resolve(opts);
+          };
+
+          const rejectAuth = (code = 401, message = "Unauthorized") => {
+            if (settled) throw new Error("Auth already settled");
+            settled = true;
+            reject({ code, message });
+          };
+
+          this._authCallback!(accept, rejectAuth, handshake, ac.signal);
+        });
+      } catch (err) {
+        const { code, message } = err as { code: number; message: string };
+        abortHandshake(socket, code ?? 401, message ?? "Unauthorized");
+        return;
+      }
+    }
+
+    // Complete WebSocket upgrade
+    if (!this._wss) return;
+
+    this._wss.handleUpgrade(req, socket, head, (ws) => {
+      // Build options for the server-side client
+      const clientOptions: ClientOptions = {
+        identity,
+        endpoint: "",
+        callTimeoutMs: this._options.callTimeoutMs,
+        pingIntervalMs: this._options.pingIntervalMs,
+        deferPingsOnActivity: this._options.deferPingsOnActivity,
+        callConcurrency: this._options.callConcurrency,
+        maxBadMessages: this._options.maxBadMessages,
+        respondWithDetailedErrors: this._options.respondWithDetailedErrors,
+        strictMode: this._options.strictMode,
+        strictModeValidators: this._options.strictModeValidators,
+        reconnect: false,
+      };
+
+      const client = new OCPPServerClient(clientOptions, {
+        ws,
+        handshake,
+        session: {},
+      });
+
+      this._clients.add(client);
+
+      client.on("close", () => {
+        this._clients.delete(client);
+      });
+
+      this.emit("client", client);
+    });
+  }
+
+  // ─── Close ───────────────────────────────────────────────────
+
+  async close(options: CloseOptions = {}): Promise<void> {
+    // Close all clients
+    const closePromises = Array.from(this._clients).map((client) =>
+      client.close(options).catch(() => {}),
+    );
+    await Promise.allSettled(closePromises);
+
+    // Abort all controllers
+    for (const ac of this._httpServerAbortControllers) {
+      ac.abort();
+    }
+    this._httpServerAbortControllers.clear();
+
+    // Close WebSocket server
+    if (this._wss) {
+      this._wss.close();
+      this._wss = null;
+    }
+
+    // Close all HTTP servers
+    const serverClosePromises = Array.from(this._httpServers).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          server.close(() => resolve());
+        }),
+    );
+    await Promise.allSettled(serverClosePromises);
+    this._httpServers.clear();
+
+    // Disconnect adapter
+    if (this._adapter) {
+      await this._adapter.disconnect();
+    }
+  }
+
+  // ─── Reconfigure ─────────────────────────────────────────────
+
+  reconfigure(options: Partial<ServerOptions>): void {
+    Object.assign(this._options, options);
+  }
+
+  // ─── Pub/Sub Adapter ─────────────────────────────────────────
+
+  setAdapter(adapter: EventAdapterInterface): void {
+    this._adapter = adapter;
+  }
+
+  async publish(channel: string, data: unknown): Promise<void> {
+    if (this._adapter) {
+      await this._adapter.publish(channel, data);
+    }
+  }
+}

package/src/standard-validators.ts

@@ -0,0 +1,18 @@
+import {
+  createValidator,
+  type Validator,
+  type ValidatorSchema,
+} from "./validator.js";
+import ocpp16 from "./schemas/ocpp1_6.json";
+import ocpp201 from "./schemas/ocpp2_0_1.json";
+import ocpp21 from "./schemas/ocpp2_1.json";
+
+/**
+ * Pre-built validators for all supported OCPP protocol versions.
+ * These are automatically registered when strict mode is enabled.
+ */
+export const standardValidators: Validator[] = [
+  createValidator("ocpp1.6", ocpp16 as ValidatorSchema[]),
+  createValidator("ocpp2.0.1", ocpp201 as ValidatorSchema[]),
+  createValidator("ocpp2.1", ocpp21 as ValidatorSchema[]),
+];