opcjs-client 0.1.26-alpha → 0.1.32-alpha

package/dist/index.cjs

@@ -92,17 +92,23 @@ var SessionService = class _SessionService extends ServiceBase {
     if (serviceResult !== void 0 && serviceResult !== opcjsBase.StatusCode.Good) {
       throw new Error(`CreateSessionRequest failed: ${opcjsBase.StatusCodeToString(serviceResult)}`);
     }
-    const endpoint = "opc." + this.secureChannel.getEndpointUrl();
-    const endpointUrl = new URL(endpoint);
+    const clientConnectionUrl = new URL("opc." + this.secureChannel.getEndpointUrl());
     const securityMode = this.secureChannel.getSecurityMode();
     const securityPolicyUri = this.secureChannel.getSecurityPolicy();
+    const normalizeEndpointUrl = (serverEndpointUrl) => {
+      const url = new URL(serverEndpointUrl);
+      url.hostname = clientConnectionUrl.hostname;
+      url.port = clientConnectionUrl.port;
+      return url;
+    };
     const serverEndpoint = castedResponse?.serverEndpoints?.find((currentEndpoint) => {
-      const currentEndpointUrl = new URL(currentEndpoint.endpointUrl);
-      return currentEndpointUrl.protocol === endpointUrl.protocol && currentEndpointUrl.pathname === endpointUrl.pathname && currentEndpointUrl.port === endpointUrl.port && currentEndpoint.securityMode === securityMode && currentEndpoint.securityPolicyUri === securityPolicyUri;
+      const normalized = normalizeEndpointUrl(currentEndpoint.endpointUrl);
+      return normalized.protocol === clientConnectionUrl.protocol && normalized.pathname === clientConnectionUrl.pathname && currentEndpoint.securityMode === securityMode && currentEndpoint.securityPolicyUri === securityPolicyUri;
     });
     if (!serverEndpoint) {
-      throw new Error(`Server endpoint ${endpoint} not found in CreateSessionResponse`);
+      throw new Error(`Server endpoint ${clientConnectionUrl.toString()} not found in CreateSessionResponse`);
     }
+    serverEndpoint.endpointUrl = normalizeEndpointUrl(serverEndpoint.endpointUrl).toString();
     this.logger.debug("Session created with id:", castedResponse.sessionId.identifier);
     return {
       sessionId: castedResponse.sessionId.identifier,
@@ -133,6 +139,24 @@ var SessionService = class _SessionService extends ServiceBase {
     }
     this.logger.debug("Session activated.");
   }
+  /**
+   * Closes the current session on the server (OPC UA Part 4, Section 5.7.4).
+   * @param deleteSubscriptions - When true the server deletes all Subscriptions
+   *   associated with this Session, freeing their resources immediately.
+   *   Pass false to keep Subscriptions alive for transfer to another Session.
+   */
+  async closeSession(deleteSubscriptions) {
+    this.logger.debug("Sending CloseSessionRequest...");
+    const request = new opcjsBase.CloseSessionRequest();
+    request.requestHeader = this.createRequestHeader();
+    request.deleteSubscriptions = deleteSubscriptions;
+    const response = await this.secureChannel.issueServiceRequest(request);
+    const result = response?.responseHeader?.serviceResult;
+    if (result !== void 0 && result !== opcjsBase.StatusCode.Good) {
+      throw new Error(`CloseSession failed: ${opcjsBase.StatusCodeToString(result)}`);
+    }
+    this.logger.debug("Session closed.");
+  }
   recreate(authToken) {
     return new _SessionService(authToken, this.secureChannel, this.configuration);
   }
@@ -194,23 +218,97 @@ var Session = class {
   getAuthToken() {
     return this.authToken;
   }
+  getSessionId() {
+    return this.sessionId;
+  }
+  getEndpoint() {
+    return this.endpoint;
+  }
+  /**
+   * Closes the session on the server (OPC UA Part 4, Section 5.7.4).
+   * @param deleteSubscriptions - When true the server deletes all Subscriptions
+   *   tied to this Session. Defaults to true.
+   */
+  async close(deleteSubscriptions = true) {
+    await this.sessionServices.closeSession(deleteSubscriptions);
+  }
 };
 
 // src/sessions/sessionHandler.ts
 var SessionHandler = class {
+  constructor(secureChannel, configuration) {
+    this.configuration = configuration;
+    this.sessionServices = new SessionService(opcjsBase.NodeId.newTwoByte(0), secureChannel, configuration);
+  }
   sessionServices;
+  logger = opcjsBase.getLogger("sessions.SessionHandler");
   async createNewSession(identity) {
     const ret = await this.sessionServices.createSession();
     this.sessionServices = this.sessionServices.recreate(ret.authToken);
     const session = new Session(ret.sessionId, ret.authToken, ret.endpoint, this.sessionServices);
+    this.validateUserTokenPolicy(identity, ret.endpoint);
     await session.activateSession(identity);
     return session;
   }
-  constructor(secureChannel, configuration) {
-    this.sessionServices = new SessionService(opcjsBase.NodeId.newTwoByte(0), secureChannel, configuration);
+  /**
+   * Attempts to reactivate an existing OPC UA session on the current (new) SecureChannel
+   * without calling CreateSession first (OPC UA Part 4, Section 5.7.3).
+   *
+   * This is the preferred recovery path when the SecureChannel drops but the server-side
+   * session has not yet timed out: only a new channel is needed, not a new session.
+   *
+   * @returns The reactivated Session if ActivateSession succeeded, or `null` if the server
+   *          rejected the request (e.g. the session had already expired).
+   */
+  async tryActivateExistingSession(existingAuthToken, existingSessionId, existingEndpoint, identity) {
+    const serviceForExistingSession = this.sessionServices.recreate(existingAuthToken);
+    try {
+      const session = new Session(existingSessionId, existingAuthToken, existingEndpoint, serviceForExistingSession);
+      await session.activateSession(identity);
+      return session;
+    } catch (err) {
+      this.logger.debug("ActivateSession for existing session failed:", err);
+      return null;
+    }
+  }
+  /**
+   * Closes the active session on the server (OPC UA Part 4, Section 5.7.4).
+   * @param deleteSubscriptions - Forwarded to CloseSessionRequest. Defaults to true.
+   */
+  async closeSession(deleteSubscriptions = true) {
+    await this.sessionServices.closeSession(deleteSubscriptions);
+  }
+  /**
+   * Validates the requested user-identity token type against:
+   *   1. The `allowedUserTokenTypes` from the client security configuration — the
+   *      client has explicitly restricted which token types it will use.
+   *   2. The token policies advertised by the server endpoint — verifies that the
+   *      server actually supports at least one of the allowed types.
+   *
+   * Throws with a descriptive message if either check fails.
+   */
+  validateUserTokenPolicy(identity, endpoint) {
+    const allowedTypes = this.configuration.securityConfiguration?.allowedUserTokenTypes;
+    if (!allowedTypes) return;
+    const requestedType = identity.getTokenType();
+    if (!allowedTypes.includes(requestedType)) {
+      throw new Error(
+        `User token type '${opcjsBase.UserTokenTypeEnum[requestedType]}' is not permitted by the client security configuration. Allowed types: ${allowedTypes.map((t) => opcjsBase.UserTokenTypeEnum[t]).join(", ")}.`
+      );
+    }
+    const serverTypes = endpoint.userIdentityTokens?.map((p) => p.tokenType) ?? [];
+    const intersection = allowedTypes.filter((t) => serverTypes.includes(t));
+    if (intersection.length === 0) {
+      throw new Error(
+        `Server endpoint does not offer any user token type from the allowed list: ${allowedTypes.map((t) => opcjsBase.UserTokenTypeEnum[t]).join(", ")}. Server offers: ${serverTypes.map((t) => opcjsBase.UserTokenTypeEnum[t]).join(", ")}.`
+      );
+    }
   }
 };
 
+// src/securityConfiguration.ts
+var SECURITY_POLICY_NONE_URI = "http://opcfoundation.org/UA/SecurityPolicy#None";
+
 // src/services/attributeServiceAttributes.ts
 var AttrIdValue = 13;
 
@@ -285,6 +383,10 @@ var SubscriptionHandler = class {
   entries = new Array();
   nextHandle = 0;
   isRunning = false;
+  /** Returns true when at least one subscription is active and the publish loop is running. */
+  hasActiveSubscription() {
+    return this.isRunning && this.entries.length > 0;
+  }
   async subscribe(ids, callback) {
     if (this.entries.length > 0) {
       throw new Error("Subscribing more than once is not implemented");
@@ -327,7 +429,8 @@ var SubscriptionHandler = class {
     }
     for (const notificationData of notificationDatas) {
       const decodedData = notificationData.data;
-      const typeNodeId = notificationData.typeId;
+      const rawTypeId = notificationData.typeId;
+      const typeNodeId = rawTypeId instanceof opcjsBase.ExpandedNodeId ? rawTypeId.nodeId : rawTypeId;
       if (typeNodeId.namespace === 0 && typeNodeId.identifier === NODE_ID_DATA_CHANGE_NOTIFICATION) {
         const dataChangeNotification = decodedData;
         for (const item of dataChangeNotification.monitoredItems) {
@@ -540,6 +643,8 @@ var BrowseNodeResult = class {
 };
 
 // src/client.ts
+var SERVER_STATUS_NODE_ID = opcjsBase.NodeId.newNumeric(0, 2256);
+var KEEP_ALIVE_INTERVAL_MS = 25e3;
 var Client = class {
   constructor(endpointUrl, configuration, identity) {
     this.configuration = configuration;
@@ -555,9 +660,12 @@ var Client = class {
   session;
   subscriptionHandler;
   logger;
-  // Stored after connect() so that refreshSession() can recreate services.
+  // Stored after connect() so that refreshSession() and disconnect() can use them.
   secureChannel;
+  secureChannelFacade;
+  ws;
   sessionHandler;
+  keepAliveTimer;
   getSession() {
     if (!this.session) {
       throw new Error("No session available");
@@ -586,20 +694,77 @@ var Client = class {
    * This covers the reactive case: a service call reveals that the server has
    * already dropped the session (e.g. due to timeout). The new session is
    * established transparently before re-running the original operation.
+   *
+   * For any other error (e.g. transport-level failures when the SecureChannel
+   * drops), this method attempts to reconnect the channel and reactivate the
+   * existing session first — falling back to a brand-new session only when
+   * reactivation fails — before retrying the operation once.
    */
   async withSessionRefresh(fn) {
     try {
       return await fn();
     } catch (err) {
-      if (!(err instanceof SessionInvalidError)) throw err;
-      this.logger.info(`Session invalid (${err.statusCode.toString(16)}), refreshing session...`);
-      this.session = await this.sessionHandler.createNewSession(this.identity);
-      this.initServices();
-      this.logger.info("Session refreshed, retrying operation.");
+      if (err instanceof SessionInvalidError) {
+        this.logger.info(`Session invalid (${err.statusCode.toString(16)}), refreshing session...`);
+        this.session = await this.sessionHandler.createNewSession(this.identity);
+        this.initServices();
+        this.logger.info("Session refreshed, retrying operation.");
+        return await fn();
+      }
+      this.logger.info("Service call failed, attempting channel reconnect and session reactivation...");
+      try {
+        await this.reconnectAndReactivate();
+        this.initServices();
+        this.logger.info("Reconnected successfully, retrying operation.");
+      } catch (reconnectErr) {
+        this.logger.warn("Channel reconnect failed:", reconnectErr);
+        throw err;
+      }
       return await fn();
     }
   }
+  /**
+   * Starts a periodic keep-alive timer that reads Server_ServerStatus when no subscription is
+   * active. OPC UA Part 4, Section 5.7.1 requires clients to keep the session alive; when no
+   * subscription Publish loop is running this is the only mechanism that does so.
+   */
+  startKeepAlive() {
+    this.keepAliveTimer = setInterval(() => {
+      if (this.subscriptionHandler?.hasActiveSubscription()) {
+        return;
+      }
+      if (this.attributeService) {
+        void this.attributeService.ReadValue([SERVER_STATUS_NODE_ID]).catch((err) => {
+          this.logger.warn("Keep-alive read failed:", err);
+        });
+      }
+    }, KEEP_ALIVE_INTERVAL_MS);
+  }
+  stopKeepAlive() {
+    clearInterval(this.keepAliveTimer);
+    this.keepAliveTimer = void 0;
+  }
   async connect() {
+    const { ws, sc } = await this.openTransportAndChannel();
+    this.secureChannel = sc;
+    this.secureChannelFacade = sc;
+    this.ws = ws;
+    this.logger.debug("Creating session...");
+    this.sessionHandler = new SessionHandler(sc, this.configuration);
+    this.session = await this.sessionHandler.createNewSession(this.identity);
+    this.logger.debug("Session created.");
+    this.logger.debug("Initializing services...");
+    this.initServices();
+    this.startKeepAlive();
+  }
+  /**
+   * Builds the full WebSocket → TCP → SecureChannel pipeline and returns the
+   * two objects needed to drive it: the raw WebSocket facade (for teardown)
+   * and the SecureChannelFacade (for service requests/session management).
+   *
+   * Extracted from `connect()` so it can be reused by `reconnectAndReactivate()`.
+   */
+  async openTransportAndChannel() {
     const wsOptions = { endpoint: this.endpointUrl };
     const ws = new opcjsBase.WebSocketFascade(wsOptions);
     const webSocketReadableStream = new opcjsBase.WebSocketReadableStream(ws, 1e3);
@@ -608,7 +773,7 @@ var Client = class {
     const tcpMessageInjector = new opcjsBase.TcpMessageInjector();
     const tcpConnectionHandler = new opcjsBase.TcpConnectionHandler(tcpMessageInjector, scContext);
     const tcpMessageDecoupler = new opcjsBase.TcpMessageDecoupler(tcpConnectionHandler.onTcpMessage.bind(tcpConnectionHandler));
-    const scMessageEncoder = new opcjsBase.SecureChannelMesssageEncoder(scContext);
+    const scMessageEncoder = new opcjsBase.SecureChannelMessageEncoder(scContext);
     const scTypeDecoder = new opcjsBase.SecureChannelTypeDecoder(
       this.configuration.decoder
     );
@@ -642,16 +807,106 @@ var Client = class {
     this.logger.debug("Opening secure channel...");
     await sc.openSecureChannel();
     this.logger.debug("Secure channel established.");
-    this.logger.debug("Creating session...");
-    this.sessionHandler = new SessionHandler(sc, this.configuration);
+    this.enforceChannelSecurityConfig(sc);
+    return { ws, sc };
+  }
+  /**
+   * Validates the negotiated channel's security policy and mode against the
+   * client's `SecurityConfiguration` (OPC UA Part 2, Security Administration).
+   *
+   * Throws if:
+   * - `allowSecurityPolicyNone` is `false` and the channel uses SecurityPolicy None.
+   * - `messageSecurityMode` is set and does not match the channel's actual mode.
+   */
+  enforceChannelSecurityConfig(sc) {
+    const config = this.configuration.securityConfiguration;
+    if (!config) return;
+    const negotiatedPolicy = sc.getSecurityPolicy();
+    const negotiatedMode = sc.getSecurityMode();
+    if (config.allowSecurityPolicyNone === false && negotiatedPolicy === SECURITY_POLICY_NONE_URI) {
+      throw new Error(
+        "Connection refused: SecurityPolicy None is disabled by the client security configuration. Only SecurityPolicy None is currently supported by this client implementation."
+      );
+    }
+    if (config.messageSecurityMode !== void 0 && config.messageSecurityMode !== negotiatedMode) {
+      throw new Error(
+        `Connection refused: negotiated MessageSecurityMode ${negotiatedMode} does not match the required mode ${config.messageSecurityMode} from the security configuration.`
+      );
+    }
+  }
+  /**
+   * Tears down the current (dead) channel and establishes a fresh one, then
+   * attempts to recover the existing OPC UA session via ActivateSession before
+   * falling back to a full CreateSession + ActivateSession.
+   *
+   * OPC UA Part 4, Section 5.7.1 / Session Client Auto Reconnect conformance unit:
+   * When the SecureChannel drops but the server-side session has not yet timed
+   * out, the client SHOULD reuse the existing session by calling ActivateSession
+   * on the new channel.  Only if that fails should the client create a new session.
+   */
+  async reconnectAndReactivate() {
+    this.logger.info("Tearing down dead channel before reconnect...");
+    try {
+      this.secureChannelFacade?.close();
+    } catch {
+    }
+    try {
+      this.ws?.close();
+    } catch {
+    }
+    this.secureChannelFacade = void 0;
+    this.secureChannel = void 0;
+    this.ws = void 0;
+    const { ws, sc } = await this.openTransportAndChannel();
     this.secureChannel = sc;
+    this.secureChannelFacade = sc;
+    this.ws = ws;
+    this.sessionHandler = new SessionHandler(sc, this.configuration);
+    if (this.session) {
+      const reactivated = await this.sessionHandler.tryActivateExistingSession(
+        this.session.getAuthToken(),
+        this.session.getSessionId(),
+        this.session.getEndpoint(),
+        this.identity
+      );
+      if (reactivated !== null) {
+        this.session = reactivated;
+        this.logger.info("Existing session successfully reactivated on new channel.");
+        return;
+      }
+      this.logger.info("ActivateSession for existing session failed; creating a fresh session...");
+    }
     this.session = await this.sessionHandler.createNewSession(this.identity);
-    this.logger.debug("Session created.");
-    this.logger.debug("Initializing services...");
-    this.initServices();
+    this.logger.info("Fresh session established on new channel.");
   }
+  /**
+   * Gracefully disconnects from the OPC UA server.
+   *
+   * Sequence per OPC UA Part 4, Section 5.7.4:
+   * 1. CloseSession (deleteSubscriptions=true) so the server frees all resources.
+   * 2. Close the SecureChannel, which cancels the pending token-renewal timer.
+   * 3. Close the WebSocket transport.
+   *
+   * CloseSession errors are swallowed so transport teardown always completes even
+   * when the session has already expired on the server side.
+   */
   async disconnect() {
     this.logger.info("Disconnecting from OPC UA server...");
+    this.stopKeepAlive();
+    if (this.session && this.sessionHandler) {
+      try {
+        await this.sessionHandler.closeSession(true);
+      } catch (err) {
+        this.logger.warn("CloseSession failed (continuing teardown):", err);
+      }
+      this.session = void 0;
+    }
+    this.secureChannelFacade?.close();
+    this.secureChannelFacade = void 0;
+    this.secureChannel = void 0;
+    this.ws?.close();
+    this.ws = void 0;
+    this.logger.info("Disconnected.");
   }
   async read(ids) {
     return this.withSessionRefresh(async () => {
@@ -720,8 +975,8 @@ var Client = class {
     if (recursive) {
       for (const ref of allReferences) {
         const childNodeId = opcjsBase.NodeId.newNumeric(
-          ref.nodeId.namespace,
-          ref.nodeId.identifier
+          ref.nodeId.nodeId.namespace,
+          ref.nodeId.nodeId.identifier
         );
         const childResults = await this.browseRecursive(
           childNodeId,
@@ -738,6 +993,14 @@ var Client = class {
   }
 };
 var ConfigurationClient = class _ConfigurationClient extends opcjsBase.Configuration {
+  /**
+   * Optional security restrictions applied during `Client.connect()`.
+   * When not set, permissive defaults are used (SecurityPolicy None allowed,
+   * all user-token types accepted).
+   *
+   * @see SecurityConfiguration
+   */
+  securityConfiguration;
   static getSimple(name, company, loggerFactory) {
     if (!loggerFactory) {
       loggerFactory = new opcjsBase.LoggerFactory({
@@ -830,6 +1093,7 @@ var UserIdentity = class _UserIdentity {
 exports.BrowseNodeResult = BrowseNodeResult;
 exports.Client = Client;
 exports.ConfigurationClient = ConfigurationClient;
+exports.SECURITY_POLICY_NONE_URI = SECURITY_POLICY_NONE_URI;
 exports.SessionInvalidError = SessionInvalidError;
 exports.UserIdentity = UserIdentity;
 //# sourceMappingURL=index.cjs.map