node-opcua-role-set-server 2.174.0

package/source/role_set_resolver.ts

@@ -0,0 +1,38 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * IRoleResolver adapter backed by an IIdentityMappingStore, optionally enforcing
+ * per-Role application/endpoint restrictions (OPC 10000-18 §4.4.1).
+ */
+import type { NodeId } from "node-opcua-nodeid";
+import type {
+    AnyUserIdentityToken,
+    IIdentityMappingStore,
+    IRoleRestrictionStore,
+    ResolutionContext
+} from "node-opcua-role-set-common";
+
+/**
+ * Adapts an {@link IIdentityMappingStore} (and an optional
+ * {@link IRoleRestrictionStore}) to the `IRoleResolver` contract so it can be
+ * registered on `OPCUAServer.roleResolvers`.
+ *
+ * A Role is granted when the UserIdentityToken matches **and** — if a
+ * restriction store is provided and a resolution context is available — the
+ * Session's application/endpoint comply with the Role's restrictions.
+ */
+export class RoleSetResolver {
+    constructor(
+        private readonly store: IIdentityMappingStore,
+        private readonly restrictionStore?: IRoleRestrictionStore
+    ) {}
+
+    public resolveRoles(userIdentityToken: AnyUserIdentityToken, context?: ResolutionContext): NodeId[] {
+        const roles = this.store.resolveRoles(userIdentityToken);
+        if (!this.restrictionStore || !context) {
+            return roles;
+        }
+        const restrictionStore = this.restrictionStore;
+        return roles.filter((roleId) => restrictionStore.complies(roleId, context));
+    }
+}

package/source/security_checks.ts

@@ -0,0 +1,47 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * Shared authorization checks for the RoleType and UserManagement Methods
+ * (OPC 10000-18 §4.4 / §5.2): all require the SecurityAdmin Role and an
+ * encrypted SecureChannel.
+ */
+import type { ISessionContext } from "node-opcua-address-space-base";
+import { sameNodeId } from "node-opcua-nodeid";
+import { WellKnownRoleIds } from "node-opcua-role-set-common";
+import type { CallMethodResultOptions } from "node-opcua-service-call";
+import { StatusCodes } from "node-opcua-status-code";
+import { MessageSecurityMode } from "node-opcua-types";
+
+/**
+ * Verify the calling session holds the SecurityAdmin role.
+ * @returns a `Bad_UserAccessDenied` denial, or `null` if authorized.
+ */
+export function checkSecurityAdminAccess(context: ISessionContext): CallMethodResultOptions | null {
+    const roles = context.getCurrentUserRoles();
+    const hasSecurityAdmin = roles.some((r) => sameNodeId(r, WellKnownRoleIds.SecurityAdmin));
+    if (!hasSecurityAdmin) {
+        return { statusCode: StatusCodes.BadUserAccessDenied };
+    }
+    return null;
+}
+
+/**
+ * Verify the call arrives over an encrypted (SignAndEncrypt) SecureChannel
+ * (OPC 10000-18 — `Bad_SecurityModeInsufficient`).
+ *
+ * When the channel security mode cannot be determined (e.g. an in-process
+ * `PseudoSession` with no channel), the check is skipped — such sessions are
+ * inherently local/trusted. Remote sessions always expose a channel mode.
+ *
+ * @returns a denial result, or `null` if the channel is acceptable.
+ */
+export function checkEncryptedChannel(context: ISessionContext): CallMethodResultOptions | null {
+    const securityMode = context.session?.channel?.securityMode;
+    if (securityMode === undefined) {
+        return null; // mode unknown (in-process) → cannot enforce
+    }
+    if (securityMode !== MessageSecurityMode.SignAndEncrypt) {
+        return { statusCode: StatusCodes.BadSecurityModeInsufficient };
+    }
+    return null;
+}

package/source/user_management_user_manager.ts

@@ -0,0 +1,104 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * Bridges an {@link IUserManagementStore} (and an optional role
+ * {@link IIdentityMappingStore}) to the OPC UA server `userManager` interface so
+ * that CreateSession / ActivateSession authenticate against the managed users.
+ *
+ * It records the StatusCode of the **last authentication** — in particular
+ * `Good_PasswordChangeRequired` for a user that must change the password
+ * (OPC 10000-18 §5.2.8). Because the OPC UA stack does not propagate that code
+ * into the ActivateSession response, the status is recorded here:
+ *  - per **session** ({@link IManagedUserManager.getSessionAuthStatus}),
+ *    keyed by the SessionId the client also holds, so it can be observed in the
+ *    context of the very session that activated;
+ *  - per **user** ({@link IManagedUserManager.lastAuthStatus}) for convenience.
+ *
+ * The server `userManager` invokes `isValidUser` with `this` bound to the
+ * ServerSession, which is how the SessionId is captured (non-breaking).
+ */
+import { WellKnownRoles } from "node-opcua-constants";
+import { makeNodeId, type NodeId, type NodeIdLike } from "node-opcua-nodeid";
+import type { AnyUserIdentityToken, IIdentityMappingStore, IUserManagementStore } from "node-opcua-role-set-common";
+import { type StatusCode, StatusCodes } from "node-opcua-status-code";
+import { type IdentityMappingRuleType, UserConfigurationMask, UserNameIdentityToken } from "node-opcua-types";
+
+/** The subset of the ServerSession that `isValidUser` is bound to (`this`). */
+interface SessionThis {
+    getSessionId?(): NodeId;
+    /** Set so ActivateSession returns Good_PasswordChangeRequired (node-opcua-server). */
+    passwordChangeRequired?: boolean;
+}
+
+export interface IManagedUserManager {
+    /** Validate credentials (sync). Returns true for Good and Good_PasswordChangeRequired. */
+    isValidUser(this: SessionThis, userName: string, password: string): boolean;
+    /** Resolve the Roles granted to a user (only Anonymous while a change is required). */
+    getUserRoles(userName: string): NodeId[];
+    /**
+     * The IdentityMappingRules configured for a Role. The server core binds each
+     * Role's `Identities` Property to this, so it stays in sync with the same
+     * identity store that drives {@link getUserRoles} — one source of truth.
+     */
+    getIdentitiesForRole(role: NodeId): IdentityMappingRuleType[];
+    /**
+     * StatusCode recorded at activation for the given session — `Good`,
+     * `Good_PasswordChangeRequired`, or a `Bad_*` code. Pass the SessionId the
+     * client holds (`clientSession.sessionId`). `undefined` if never activated.
+     */
+    getSessionAuthStatus(sessionId: NodeIdLike): StatusCode | undefined;
+    /** StatusCode of the last authentication for each user (convenience). */
+    readonly lastAuthStatus: ReadonlyMap<string, StatusCode>;
+}
+
+const has = (mask: number, bit: number): boolean => (mask & bit) === bit;
+
+/**
+ * Create a server `userManager` backed by the given user store. Roles are
+ * resolved from `identityStore` (a UserName identity rule per user); while a
+ * user must change the password, only the Anonymous Role is granted.
+ */
+export function createUserManager(userStore: IUserManagementStore, identityStore: IIdentityMappingStore): IManagedUserManager {
+    const lastAuthStatus = new Map<string, StatusCode>();
+    const statusBySession = new Map<string, StatusCode>();
+    const anonymousOnly = (): NodeId[] => [makeNodeId(WellKnownRoles.Anonymous)];
+
+    return {
+        lastAuthStatus,
+
+        getSessionAuthStatus(sessionId: NodeIdLike): StatusCode | undefined {
+            return statusBySession.get(sessionId.toString());
+        },
+
+        isValidUser(this: SessionThis, userName: string, password: string): boolean {
+            const result = userStore.authenticate(userName, password);
+            lastAuthStatus.set(userName, result.statusCode);
+            // `this` is the ServerSession; key the status by the SessionId the
+            // client also holds, so the outcome can be observed per session.
+            const sessionId = this?.getSessionId?.();
+            if (sessionId) {
+                statusBySession.set(sessionId.toString(), result.statusCode);
+            }
+            // flag the session so ActivateSession returns Good_PasswordChangeRequired
+            if (this) {
+                this.passwordChangeRequired = result.statusCode === StatusCodes.GoodPasswordChangeRequired;
+            }
+            return result.statusCode === StatusCodes.Good || result.statusCode === StatusCodes.GoodPasswordChangeRequired;
+        },
+
+        getUserRoles(userName: string): NodeId[] {
+            const user = userStore.getUsers().find((u) => u.userName === userName);
+            if (user && has(user.userConfiguration, UserConfigurationMask.MustChangePassword)) {
+                return anonymousOnly();
+            }
+            const token: AnyUserIdentityToken = new UserNameIdentityToken({ userName });
+            return identityStore.resolveRoles(token);
+        },
+
+        getIdentitiesForRole(role: NodeId): IdentityMappingRuleType[] {
+            // Backs each Role's `Identities` Property via the server core, from the
+            // same store as getUserRoles — so the two can never drift apart.
+            return identityStore.getIdentitiesForRole(role);
+        }
+    };
+}

package/source/variant_args.ts

@@ -0,0 +1,22 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * Small helpers to read Method input arguments out of a `Variant[]` safely.
+ */
+import type { UserConfigurationMask } from "node-opcua-types";
+import type { Variant } from "node-opcua-variant";
+
+/** The string value of an argument, or `null` if absent / not a string. */
+export function asString(v: Variant | undefined): string | null {
+    return v && typeof v.value === "string" ? v.value : null;
+}
+
+/** The boolean value of an argument (missing / non-boolean → `false`). */
+export function asBoolean(v: Variant | undefined): boolean {
+    return !!v && v.value === true;
+}
+
+/** The UserConfigurationMask value of an argument (missing / non-numeric → `0`). */
+export function asMask(v: Variant | undefined): UserConfigurationMask {
+    return (v && typeof v.value === "number" ? v.value : 0) as UserConfigurationMask;
+}