node-opcua-role-set-server 2.174.0

package/source/bind_user_management.ts

@@ -0,0 +1,215 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * Method handlers for the UserManagementType Methods (OPC 10000-18 §5.2):
+ * AddUser, ModifyUser, RemoveUser and ChangePassword, backed by an
+ * {@link IUserManagementStore}.
+ *
+ * AddUser / ModifyUser / RemoveUser require the SecurityAdmin Role and an
+ * encrypted channel. ChangePassword is callable by the Session user itself but
+ * still requires an encrypted channel and a USERNAME user token (§5.2.8).
+ */
+import type { ISessionContext, UAMethod } from "node-opcua-address-space-base";
+import type { NodeId } from "node-opcua-nodeid";
+import type { IUserManagementStore } from "node-opcua-role-set-common";
+import type { CallMethodResultOptions } from "node-opcua-service-call";
+import { type StatusCode, StatusCodes } from "node-opcua-status-code";
+import { UserConfigurationMask, UserNameIdentityToken } from "node-opcua-types";
+import type { Variant } from "node-opcua-variant";
+import { checkEncryptedChannel, checkSecurityAdminAccess } from "./security_checks.js";
+import { asBoolean, asMask, asString } from "./variant_args.js";
+
+/**
+ * Details of a user-management change for {@link BindUserManagementOptions.onAudit}.
+ * Deliberately carries **no password** — only who did what to whom and the result —
+ * so an AuditUpdateMethodEventType can be raised without leaking secrets.
+ */
+export interface UserManagementAudit {
+    method: "AddUser" | "ModifyUser" | "RemoveUser" | "ChangePassword";
+    /** The user the operation targets (the Session user for ChangePassword). */
+    targetUserName: string;
+    /** The Session user who invoked the Method. */
+    callerUserName: string;
+    methodNodeId: NodeId;
+    statusCode: StatusCode;
+}
+
+export interface BindUserManagementOptions {
+    store: IUserManagementStore;
+    /** Called after every successful mutation so the caller can persist / refresh. */
+    onMutation?: () => Promise<void>;
+    /** Called after an authorized Method attempt to raise an audit event (no secrets). */
+    onAudit?: (audit: UserManagementAudit) => void;
+    /**
+     * Called after a user is effectively deactivated — disabled via ModifyUser
+     * (§5.2.6) or deleted via RemoveUser (§5.2.7) — so the caller can terminate
+     * that user's still-active sessions (a disabled user must lose access, not
+     * merely be barred from re-authenticating).
+     */
+    onUserDeactivated?: (userName: string) => void | Promise<void>;
+}
+
+const isDisabled = (mask: UserConfigurationMask): boolean =>
+    (mask & UserConfigurationMask.Disabled) === UserConfigurationMask.Disabled;
+
+/** Create an AddUser Method handler (§5.2.5). */
+export function makeAddUserHandler(options: BindUserManagementOptions) {
+    const { store, onMutation, onAudit } = options;
+    return async function _addUser(
+        this: UAMethod,
+        inputArguments: Variant[],
+        context: ISessionContext
+    ): Promise<CallMethodResultOptions> {
+        const insecure = checkEncryptedChannel(context);
+        if (insecure) return insecure;
+        const denied = checkSecurityAdminAccess(context);
+        if (denied) return denied;
+
+        const userName = asString(inputArguments[0]);
+        const password = asString(inputArguments[1]);
+        if (userName === null || password === null) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+        const userConfiguration = asMask(inputArguments[2]);
+        const description = asString(inputArguments[3]) ?? "";
+
+        const statusCode = store.addUser(userName, password, userConfiguration, description);
+        if (statusCode === StatusCodes.Good && onMutation) {
+            await onMutation();
+        }
+        onAudit?.({
+            method: "AddUser",
+            targetUserName: userName,
+            callerUserName: context.getUserName(),
+            methodNodeId: this.nodeId,
+            statusCode
+        });
+        return { statusCode };
+    };
+}
+
+/** Create a ModifyUser Method handler (§5.2.6). */
+export function makeModifyUserHandler(options: BindUserManagementOptions) {
+    const { store, onMutation, onAudit, onUserDeactivated } = options;
+    return async function _modifyUser(
+        this: UAMethod,
+        inputArguments: Variant[],
+        context: ISessionContext
+    ): Promise<CallMethodResultOptions> {
+        const insecure = checkEncryptedChannel(context);
+        if (insecure) return insecure;
+        const denied = checkSecurityAdminAccess(context);
+        if (denied) return denied;
+
+        const userName = asString(inputArguments[0]);
+        if (userName === null) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+        const modifyUserConfiguration = asBoolean(inputArguments[3]);
+        const userConfiguration = asMask(inputArguments[4]);
+        const statusCode = store.modifyUser(
+            userName,
+            {
+                modifyPassword: asBoolean(inputArguments[1]),
+                password: asString(inputArguments[2]) ?? "",
+                modifyUserConfiguration,
+                userConfiguration,
+                modifyDescription: asBoolean(inputArguments[5]),
+                description: asString(inputArguments[6]) ?? ""
+            },
+            context.getUserName()
+        );
+        if (statusCode === StatusCodes.Good) {
+            if (onMutation) await onMutation();
+            // a freshly disabled user must lose any live session, not just be barred from re-login
+            if (modifyUserConfiguration && isDisabled(userConfiguration) && onUserDeactivated) {
+                await onUserDeactivated(userName);
+            }
+        }
+        onAudit?.({
+            method: "ModifyUser",
+            targetUserName: userName,
+            callerUserName: context.getUserName(),
+            methodNodeId: this.nodeId,
+            statusCode
+        });
+        return { statusCode };
+    };
+}
+
+/** Create a RemoveUser Method handler (§5.2.7). */
+export function makeRemoveUserHandler(options: BindUserManagementOptions) {
+    const { store, onMutation, onAudit, onUserDeactivated } = options;
+    return async function _removeUser(
+        this: UAMethod,
+        inputArguments: Variant[],
+        context: ISessionContext
+    ): Promise<CallMethodResultOptions> {
+        const insecure = checkEncryptedChannel(context);
+        if (insecure) return insecure;
+        const denied = checkSecurityAdminAccess(context);
+        if (denied) return denied;
+
+        const userName = asString(inputArguments[0]);
+        if (userName === null) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+        const statusCode = store.removeUser(userName, context.getUserName());
+        if (statusCode === StatusCodes.Good) {
+            if (onMutation) await onMutation();
+            // a removed user must lose any live session as well (§5.2.7)
+            if (onUserDeactivated) await onUserDeactivated(userName);
+        }
+        onAudit?.({
+            method: "RemoveUser",
+            targetUserName: userName,
+            callerUserName: context.getUserName(),
+            methodNodeId: this.nodeId,
+            statusCode
+        });
+        return { statusCode };
+    };
+}
+
+/**
+ * Create a ChangePassword Method handler (§5.2.8).
+ *
+ * Operates on the Session user, requires an encrypted channel and a USERNAME
+ * user token (`Bad_InvalidState` otherwise). Does **not** require SecurityAdmin.
+ */
+export function makeChangePasswordHandler(options: BindUserManagementOptions) {
+    const { store, onMutation, onAudit } = options;
+    return async function _changePassword(
+        this: UAMethod,
+        inputArguments: Variant[],
+        context: ISessionContext
+    ): Promise<CallMethodResultOptions> {
+        const insecure = checkEncryptedChannel(context);
+        if (insecure) return insecure;
+
+        const token = context.session?.userIdentityToken;
+        if (!(token instanceof UserNameIdentityToken)) {
+            return { statusCode: StatusCodes.BadInvalidState };
+        }
+        const userName = token.userName ?? "";
+
+        const oldPassword = asString(inputArguments[0]);
+        const newPassword = asString(inputArguments[1]);
+        if (oldPassword === null || newPassword === null) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+
+        const statusCode = store.changePassword(userName, oldPassword, newPassword);
+        if (statusCode === StatusCodes.Good && onMutation) {
+            await onMutation();
+        }
+        onAudit?.({
+            method: "ChangePassword",
+            targetUserName: userName,
+            callerUserName: userName,
+            methodNodeId: this.nodeId,
+            statusCode
+        });
+        return { statusCode };
+    };
+}

package/source/harden.ts

@@ -0,0 +1,46 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * Browse / channel hardening for the security-sensitive RoleSet & User
+ * Management nodes (OPC 10000-18 §4.4.1 / §5), built entirely on the two
+ * mechanisms the address space already enforces — no custom Browse filter or
+ * read hook:
+ *
+ *  - **RolePermissions** — a node that carries RolePermissions grants *nothing*
+ *    to a Role that is not listed. Restricting a node to `SecurityAdmin` both
+ *    hides it from a non-admin's Browse (`isBrowseAccessRestricted`) and denies
+ *    Read/Call (`Bad_UserAccessDenied`).
+ *  - **AccessRestrictions(EncryptionRequired)** — the node may only be
+ *    read/called over a `SignAndEncrypt` channel, otherwise the core returns
+ *    `Bad_SecurityModeInsufficient`, so identity/user data never leaves the
+ *    server over an unencrypted channel.
+ *
+ * Both checks run in the core (`ua_variable_impl` / `ua_method_impl`) *before*
+ * the bound Method handler, so the per-Method `checkSecurityAdminAccess` /
+ * `checkEncryptedChannel` guards become defense-in-depth rather than the only
+ * line of defense.
+ */
+import type { BaseNode } from "node-opcua-address-space";
+import { AccessRestrictionsFlag, allPermissions } from "node-opcua-data-model";
+import { WellKnownRoleIds } from "node-opcua-role-set-common";
+
+/**
+ * Restrict a node to the `SecurityAdmin` Role, reachable only over an encrypted
+ * channel — used for the admin-only configuration Methods and the sensitive
+ * identity/restriction/user Properties.
+ */
+export function hardenAdminOnly(node: BaseNode | null | undefined): void {
+    if (!node) return;
+    node.setRolePermissions([{ roleId: WellKnownRoleIds.SecurityAdmin, permissions: allPermissions }]);
+    node.setAccessRestrictions(AccessRestrictionsFlag.EncryptionRequired);
+}
+
+/**
+ * Require an encrypted channel for a node that must stay visible/callable to
+ * ordinary authenticated users (e.g. `ChangePassword`, §5.2.8) — no Role
+ * restriction, just `EncryptionRequired`.
+ */
+export function hardenEncryptedOnly(node: BaseNode | null | undefined): void {
+    if (!node) return;
+    node.setAccessRestrictions(AccessRestrictionsFlag.EncryptionRequired);
+}

package/source/index.ts

@@ -0,0 +1,48 @@
+/**
+ * @module node-opcua-role-set-server
+ */
+
+export { type AuditMethodEventFields, raiseAuditMethodEvent } from "./audit.js";
+export {
+    type BindRestrictionMethodsOptions,
+    makeAddApplicationHandler,
+    makeAddEndpointHandler,
+    makeRemoveApplicationHandler,
+    makeRemoveEndpointHandler
+} from "./bind_restriction_methods.js";
+export {
+    type BindRoleMethodsOptions,
+    makeAddIdentityHandler,
+    makeRemoveIdentityHandler,
+    type RoleMappingRuleChangedAudit
+} from "./bind_role_methods.js";
+export {
+    type BindUserManagementOptions,
+    makeAddUserHandler,
+    makeChangePasswordHandler,
+    makeModifyUserHandler,
+    makeRemoveUserHandler,
+    type UserManagementAudit
+} from "./bind_user_management.js";
+export {
+    type CreateRoleBasedSecurityOptions,
+    createRoleBasedSecurity,
+    type InstallRoleBasedSecurityOptions,
+    type RoleBasedSecurity,
+    type RoleBasedUser
+} from "./install_role_based_security.js";
+export {
+    type InstallRoleSetOptions,
+    type InstallRoleSetResult,
+    type IServerForRoleSet,
+    installRoleSet
+} from "./install_role_set.js";
+export {
+    type InstallUserManagementOptions,
+    type InstallUserManagementResult,
+    type IServerForUserManagement,
+    installUserManagement
+} from "./install_user_management.js";
+export { RoleSetResolver } from "./role_set_resolver.js";
+export { checkEncryptedChannel, checkSecurityAdminAccess } from "./security_checks.js";
+export { createUserManager, type IManagedUserManager } from "./user_management_user_manager.js";

package/source/install_role_based_security.ts

@@ -0,0 +1,130 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * One-call wiring for role-based security (OPC 10000-18) with a **single source
+ * of truth**. It owns one user store and one identity store and exposes them
+ * through the server `userManager` bridge — the only integration point the
+ * server core uses to resolve a session's Roles (`getUserRoles`) and to back
+ * each Role's `Identities` Property (`getIdentitiesForRole`).
+ *
+ * Because the `userManager` is created **before** the server (it is a
+ * constructor option) but the RoleSet / User Management Methods are installed
+ * **after** `server.start()`, this comes in two phases:
+ *
+ * ```ts
+ * const security = createRoleBasedSecurity({
+ *     users: [{ userName: "admin", password: "pw", roles: [WellKnownRoleIds.SecurityAdmin] }]
+ * });
+ * const server = new OPCUAServer({ ..., userManager: security.userManager });
+ * await server.start();
+ * await security.install(server, { persistencePath: "./role-set.json" });
+ * ```
+ *
+ * Everything (resolution, the `Identities` Property, the AddIdentity/AddUser
+ * Methods, persistence) is backed by the same two stores, so the "legacy"
+ * (userManager) and "modern" (RoleSet Methods) views can never drift apart.
+ */
+import type { NodeId } from "node-opcua-nodeid";
+import {
+    ArchiveStore,
+    InMemoryIdentityMappingStore,
+    InMemoryUserManagementStore,
+    type PasswordPolicy
+} from "node-opcua-role-set-common";
+import { IdentityCriteriaType, IdentityMappingRuleType, UserConfigurationMask } from "node-opcua-types";
+import { type InstallRoleSetResult, type IServerForRoleSet, installRoleSet } from "./install_role_set.js";
+import {
+    type InstallUserManagementResult,
+    type IServerForUserManagement,
+    installUserManagement
+} from "./install_user_management.js";
+import { createUserManager, type IManagedUserManager } from "./user_management_user_manager.js";
+
+/** A user to seed, with the well-known/custom Roles it holds. */
+export interface RoleBasedUser {
+    userName: string;
+    password: string;
+    /** Role NodeIds granted to this user (e.g. `WellKnownRoleIds.Operator`). */
+    roles?: NodeId[];
+    userConfiguration?: UserConfigurationMask;
+    description?: string;
+}
+
+export interface CreateRoleBasedSecurityOptions {
+    /** Password policy enforced by the user store. */
+    policy?: PasswordPolicy;
+    /** Users to seed up front (more can be added later via the Methods). */
+    users?: RoleBasedUser[];
+}
+
+export interface InstallRoleBasedSecurityOptions {
+    /** A shared archive coordinator. When omitted, one is built from `persistencePath`. */
+    persistence?: ArchiveStore;
+    /** Path to a single consolidated archive for roles + users. */
+    persistencePath?: string;
+    /** Encrypt that archive at rest (AES-256-GCM, key derived from this secret). */
+    persistenceSecret?: string;
+}
+
+/** The shared stores + bridge produced by {@link createRoleBasedSecurity}. */
+export interface RoleBasedSecurity {
+    /** The single user store (passwords / user lifecycle). */
+    userStore: InMemoryUserManagementStore;
+    /** The single identity store (UserName -> Role mappings). */
+    identityStore: InMemoryIdentityMappingStore;
+    /** The server `userManager` to pass to the `OPCUAServer` constructor. */
+    userManager: IManagedUserManager;
+    /**
+     * Install the RoleSet + User Management Methods on the running server,
+     * bound to the same two stores. Call **after** `server.start()`.
+     */
+    install(
+        server: IServerForRoleSet & IServerForUserManagement,
+        options?: InstallRoleBasedSecurityOptions
+    ): Promise<{ roleSet: InstallRoleSetResult; userManagement: InstallUserManagementResult }>;
+}
+
+const userNameRule = (userName: string): IdentityMappingRuleType =>
+    new IdentityMappingRuleType({ criteriaType: IdentityCriteriaType.UserName, criteria: userName });
+
+/**
+ * Create the shared stores and the `userManager` bridge, seeding any initial
+ * users and their Roles. Pass `userManager` to the `OPCUAServer` constructor,
+ * then call {@link RoleBasedSecurity.install} after `server.start()`.
+ */
+export function createRoleBasedSecurity(options?: CreateRoleBasedSecurityOptions): RoleBasedSecurity {
+    const userStore = new InMemoryUserManagementStore(options?.policy);
+    const identityStore = new InMemoryIdentityMappingStore();
+
+    for (const user of options?.users ?? []) {
+        userStore.addUser(
+            user.userName,
+            user.password,
+            user.userConfiguration ?? UserConfigurationMask.None,
+            user.description ?? ""
+        );
+        for (const role of user.roles ?? []) {
+            identityStore.addIdentity(role, userNameRule(user.userName));
+        }
+    }
+
+    const userManager = createUserManager(userStore, identityStore);
+
+    return {
+        userStore,
+        identityStore,
+        userManager,
+        async install(server, installOptions) {
+            // one coordinator shared by both installers (so users + roles land in one file)
+            const persistence =
+                installOptions?.persistence ??
+                (installOptions?.persistencePath
+                    ? new ArchiveStore(installOptions.persistencePath, { secret: installOptions.persistenceSecret })
+                    : undefined);
+
+            const roleSet = await installRoleSet(server, { store: identityStore, persistence });
+            const userManagement = await installUserManagement(server, { store: userStore, persistence });
+            return { roleSet, userManagement };
+        }
+    };
+}