opcjs-client 0.1.26-alpha → 0.1.32-alpha

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum, UaPrimitive } from 'opcjs-base';
+import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, MessageSecurityModeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum, UaPrimitive } from 'opcjs-base';
 
 declare abstract class ServiceBase {
     private authToken;
@@ -35,6 +35,13 @@ declare class SessionService extends ServiceBase {
      * @param identityToken - User identity token (anonymous, username/password, certificate, or issued token).
      */
     activateSession(identityToken: UserIdentityToken): Promise<void>;
+    /**
+     * 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.
+     */
+    closeSession(deleteSubscriptions: boolean): Promise<void>;
     recreate(authToken: NodeId): SessionService;
     constructor(authToken: NodeId, secureChannel: ISecureChannel, configuration: Configuration);
 }
@@ -84,6 +91,14 @@ declare class Session {
     private sessionServices;
     activateSession(identity: UserIdentity): Promise<void>;
     getAuthToken(): NodeId;
+    getSessionId(): number;
+    getEndpoint(): EndpointDescription;
+    /**
+     * 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.
+     */
+    close(deleteSubscriptions?: boolean): Promise<void>;
     constructor(sessionId: number, authToken: NodeId, endpoint: EndpointDescription, sessionServices: SessionService);
 }
 
@@ -93,7 +108,100 @@ declare class ReadValueResult {
     constructor(value: unknown, statusCode: number);
 }
 
+/** URI for the SecurityPolicy None profile. */
+declare const SECURITY_POLICY_NONE_URI = "http://opcfoundation.org/UA/SecurityPolicy#None";
+/**
+ * How the client should handle a server certificate it cannot verify.
+ *
+ * - `'reject'` — abort the connection (secure default when `trustedCAs` is configured).
+ * - `'trust'`  — accept any certificate without verification (development convenience;
+ *                **insecure in production**).
+ *
+ * @note Enforcement is deferred until certificate-based security policies are
+ *       implemented. The value is stored and will be honoured when that support lands.
+ */
+type UnknownCertificatePolicy = 'reject' | 'trust';
+/**
+ * OPC UA client security configuration (OPC UA Part 2, Security Administration CU).
+ *
+ * Restricts which security options the client will accept when connecting to or
+ * negotiating with a server. All fields are optional; omitting a field applies
+ * the permissive default so that existing callers need no changes.
+ *
+ * @example
+ * ```ts
+ * const config = ConfigurationClient.getSimple('MyApp', 'MyCompany')
+ * config.securityConfiguration = {
+ *   allowedUserTokenTypes: [UserTokenTypeEnum.UserName],
+ *   allowSecurityPolicyNone: false,   // require an encrypted channel
+ * }
+ * ```
+ */
+type SecurityConfiguration = {
+    /**
+     * User-identity-token types the client is willing to accept.
+     *
+     * When set, `connect()` will throw if:
+     * - The supplied `UserIdentity`'s token type is not in this list, OR
+     * - The server endpoint does not offer any type from this list.
+     *
+     * Default: all token types are accepted (no restriction).
+     */
+    allowedUserTokenTypes?: UserTokenTypeEnum[];
+    /**
+     * Allow connecting when the negotiated SecurityPolicy is `None` (unencrypted,
+     * unsigned channel).
+     *
+     * Set to `false` to require a secure channel — `connect()` will throw rather
+     * than establish a cleartext connection.
+     *
+     * Currently the only supported security policy is `None`. Setting this to `false`
+     * will therefore cause `connect()` to always throw until non-None policies are
+     * added to this client implementation.
+     *
+     * Default: `true` (SecurityPolicy None is permitted).
+     */
+    allowSecurityPolicyNone?: boolean;
+    /**
+     * Required `MessageSecurityMode` for the secure channel.
+     *
+     * When set, `connect()` verifies that the channel's negotiated mode matches
+     * this value and throws otherwise.
+     *
+     * Currently only `MessageSecurityModeEnum.None` is supported.
+     *
+     * Default: no requirement (any mode is accepted).
+     */
+    messageSecurityMode?: MessageSecurityModeEnum;
+    /**
+     * DER-encoded X.509 trusted CA certificates used to verify the server's
+     * application instance certificate.
+     *
+     * @note Reserved for future use. Certificate verification is not yet implemented.
+     *       Providing this field has no effect until non-None security policies land.
+     */
+    trustedCAs?: Uint8Array[];
+    /**
+     * How to handle a server certificate that cannot be verified against `trustedCAs`.
+     *
+     * - `'reject'` — refuse the connection (default when `trustedCAs` is provided).
+     * - `'trust'`  — accept any certificate (development only; insecure in production).
+     *
+     * @note Reserved for future use. Has no effect until certificate verification is
+     *       implemented alongside non-None security policies.
+     */
+    unknownCertificatePolicy?: UnknownCertificatePolicy;
+};
+
 declare class ConfigurationClient extends 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?: SecurityConfiguration;
     static getSimple(name: string, company: string, loggerFactory?: ILoggerFactory): ConfigurationClient;
     constructor(applicationName: string, applicationUri: string, productName: string, productUri: string, encoder: Encoder, decoder: Decoder, loggerFactory: ILoggerFactory);
 }
@@ -126,7 +234,10 @@ declare class Client {
     private subscriptionHandler?;
     private logger;
     private secureChannel?;
+    private secureChannelFacade?;
+    private ws?;
     private sessionHandler?;
+    private keepAliveTimer?;
     getSession(): Session;
     /**
      * (Re-)initialises all session-scoped services from the current `this.session`.
@@ -140,9 +251,60 @@ declare class Client {
      * 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.
      */
     private withSessionRefresh;
+    /**
+     * 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.
+     */
+    private startKeepAlive;
+    private stopKeepAlive;
     connect(): Promise<void>;
+    /**
+     * 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()`.
+     */
+    private openTransportAndChannel;
+    /**
+     * 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.
+     */
+    private enforceChannelSecurityConfig;
+    /**
+     * 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.
+     */
+    private reconnectAndReactivate;
+    /**
+     * 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.
+     */
     disconnect(): Promise<void>;
     read(ids: NodeId[]): Promise<ReadValueResult[]>;
     /**
@@ -178,4 +340,4 @@ declare class SessionInvalidError extends Error {
     constructor(statusCode: number);
 }
 
-export { BrowseNodeResult, Client, ConfigurationClient, SessionInvalidError, UserIdentity };
+export { BrowseNodeResult, Client, ConfigurationClient, SECURITY_POLICY_NONE_URI, type SecurityConfiguration, SessionInvalidError, type UnknownCertificatePolicy, UserIdentity };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum, UaPrimitive } from 'opcjs-base';
+import { ISecureChannel, RequestHeader, NodeId, EndpointDescription, UserIdentityToken, Configuration, UserTokenTypeEnum, MessageSecurityModeEnum, ILoggerFactory, Encoder, Decoder, ExpandedNodeId, QualifiedName, LocalizedText, NodeClassEnum, UaPrimitive } from 'opcjs-base';
 
 declare abstract class ServiceBase {
     private authToken;
@@ -35,6 +35,13 @@ declare class SessionService extends ServiceBase {
      * @param identityToken - User identity token (anonymous, username/password, certificate, or issued token).
      */
     activateSession(identityToken: UserIdentityToken): Promise<void>;
+    /**
+     * 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.
+     */
+    closeSession(deleteSubscriptions: boolean): Promise<void>;
     recreate(authToken: NodeId): SessionService;
     constructor(authToken: NodeId, secureChannel: ISecureChannel, configuration: Configuration);
 }
@@ -84,6 +91,14 @@ declare class Session {
     private sessionServices;
     activateSession(identity: UserIdentity): Promise<void>;
     getAuthToken(): NodeId;
+    getSessionId(): number;
+    getEndpoint(): EndpointDescription;
+    /**
+     * 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.
+     */
+    close(deleteSubscriptions?: boolean): Promise<void>;
     constructor(sessionId: number, authToken: NodeId, endpoint: EndpointDescription, sessionServices: SessionService);
 }
 
@@ -93,7 +108,100 @@ declare class ReadValueResult {
     constructor(value: unknown, statusCode: number);
 }
 
+/** URI for the SecurityPolicy None profile. */
+declare const SECURITY_POLICY_NONE_URI = "http://opcfoundation.org/UA/SecurityPolicy#None";
+/**
+ * How the client should handle a server certificate it cannot verify.
+ *
+ * - `'reject'` — abort the connection (secure default when `trustedCAs` is configured).
+ * - `'trust'`  — accept any certificate without verification (development convenience;
+ *                **insecure in production**).
+ *
+ * @note Enforcement is deferred until certificate-based security policies are
+ *       implemented. The value is stored and will be honoured when that support lands.
+ */
+type UnknownCertificatePolicy = 'reject' | 'trust';
+/**
+ * OPC UA client security configuration (OPC UA Part 2, Security Administration CU).
+ *
+ * Restricts which security options the client will accept when connecting to or
+ * negotiating with a server. All fields are optional; omitting a field applies
+ * the permissive default so that existing callers need no changes.
+ *
+ * @example
+ * ```ts
+ * const config = ConfigurationClient.getSimple('MyApp', 'MyCompany')
+ * config.securityConfiguration = {
+ *   allowedUserTokenTypes: [UserTokenTypeEnum.UserName],
+ *   allowSecurityPolicyNone: false,   // require an encrypted channel
+ * }
+ * ```
+ */
+type SecurityConfiguration = {
+    /**
+     * User-identity-token types the client is willing to accept.
+     *
+     * When set, `connect()` will throw if:
+     * - The supplied `UserIdentity`'s token type is not in this list, OR
+     * - The server endpoint does not offer any type from this list.
+     *
+     * Default: all token types are accepted (no restriction).
+     */
+    allowedUserTokenTypes?: UserTokenTypeEnum[];
+    /**
+     * Allow connecting when the negotiated SecurityPolicy is `None` (unencrypted,
+     * unsigned channel).
+     *
+     * Set to `false` to require a secure channel — `connect()` will throw rather
+     * than establish a cleartext connection.
+     *
+     * Currently the only supported security policy is `None`. Setting this to `false`
+     * will therefore cause `connect()` to always throw until non-None policies are
+     * added to this client implementation.
+     *
+     * Default: `true` (SecurityPolicy None is permitted).
+     */
+    allowSecurityPolicyNone?: boolean;
+    /**
+     * Required `MessageSecurityMode` for the secure channel.
+     *
+     * When set, `connect()` verifies that the channel's negotiated mode matches
+     * this value and throws otherwise.
+     *
+     * Currently only `MessageSecurityModeEnum.None` is supported.
+     *
+     * Default: no requirement (any mode is accepted).
+     */
+    messageSecurityMode?: MessageSecurityModeEnum;
+    /**
+     * DER-encoded X.509 trusted CA certificates used to verify the server's
+     * application instance certificate.
+     *
+     * @note Reserved for future use. Certificate verification is not yet implemented.
+     *       Providing this field has no effect until non-None security policies land.
+     */
+    trustedCAs?: Uint8Array[];
+    /**
+     * How to handle a server certificate that cannot be verified against `trustedCAs`.
+     *
+     * - `'reject'` — refuse the connection (default when `trustedCAs` is provided).
+     * - `'trust'`  — accept any certificate (development only; insecure in production).
+     *
+     * @note Reserved for future use. Has no effect until certificate verification is
+     *       implemented alongside non-None security policies.
+     */
+    unknownCertificatePolicy?: UnknownCertificatePolicy;
+};
+
 declare class ConfigurationClient extends 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?: SecurityConfiguration;
     static getSimple(name: string, company: string, loggerFactory?: ILoggerFactory): ConfigurationClient;
     constructor(applicationName: string, applicationUri: string, productName: string, productUri: string, encoder: Encoder, decoder: Decoder, loggerFactory: ILoggerFactory);
 }
@@ -126,7 +234,10 @@ declare class Client {
     private subscriptionHandler?;
     private logger;
     private secureChannel?;
+    private secureChannelFacade?;
+    private ws?;
     private sessionHandler?;
+    private keepAliveTimer?;
     getSession(): Session;
     /**
      * (Re-)initialises all session-scoped services from the current `this.session`.
@@ -140,9 +251,60 @@ declare class Client {
      * 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.
      */
     private withSessionRefresh;
+    /**
+     * 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.
+     */
+    private startKeepAlive;
+    private stopKeepAlive;
     connect(): Promise<void>;
+    /**
+     * 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()`.
+     */
+    private openTransportAndChannel;
+    /**
+     * 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.
+     */
+    private enforceChannelSecurityConfig;
+    /**
+     * 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.
+     */
+    private reconnectAndReactivate;
+    /**
+     * 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.
+     */
     disconnect(): Promise<void>;
     read(ids: NodeId[]): Promise<ReadValueResult[]>;
     /**
@@ -178,4 +340,4 @@ declare class SessionInvalidError extends Error {
     constructor(statusCode: number);
 }
 
-export { BrowseNodeResult, Client, ConfigurationClient, SessionInvalidError, UserIdentity };
+export { BrowseNodeResult, Client, ConfigurationClient, SECURITY_POLICY_NONE_URI, type SecurityConfiguration, SessionInvalidError, type UnknownCertificatePolicy, UserIdentity };