node-opcua-role-set-server 2.174.0

package/dist/bind_user_management.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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 } from "node-opcua-status-code";
+import type { Variant } from "node-opcua-variant";
+/**
+ * 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>;
+}
+/** Create an AddUser Method handler (§5.2.5). */
+export declare function makeAddUserHandler(options: BindUserManagementOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;
+/** Create a ModifyUser Method handler (§5.2.6). */
+export declare function makeModifyUserHandler(options: BindUserManagementOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;
+/** Create a RemoveUser Method handler (§5.2.7). */
+export declare function makeRemoveUserHandler(options: BindUserManagementOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;
+/**
+ * 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 declare function makeChangePasswordHandler(options: BindUserManagementOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;

package/dist/bind_user_management.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeAddUserHandler = makeAddUserHandler;
+exports.makeModifyUserHandler = makeModifyUserHandler;
+exports.makeRemoveUserHandler = makeRemoveUserHandler;
+exports.makeChangePasswordHandler = makeChangePasswordHandler;
+const node_opcua_status_code_1 = require("node-opcua-status-code");
+const node_opcua_types_1 = require("node-opcua-types");
+const security_checks_js_1 = require("./security_checks.js");
+const variant_args_js_1 = require("./variant_args.js");
+const isDisabled = (mask) => (mask & node_opcua_types_1.UserConfigurationMask.Disabled) === node_opcua_types_1.UserConfigurationMask.Disabled;
+/** Create an AddUser Method handler (§5.2.5). */
+function makeAddUserHandler(options) {
+    const { store, onMutation, onAudit } = options;
+    return async function _addUser(inputArguments, context) {
+        const insecure = (0, security_checks_js_1.checkEncryptedChannel)(context);
+        if (insecure)
+            return insecure;
+        const denied = (0, security_checks_js_1.checkSecurityAdminAccess)(context);
+        if (denied)
+            return denied;
+        const userName = (0, variant_args_js_1.asString)(inputArguments[0]);
+        const password = (0, variant_args_js_1.asString)(inputArguments[1]);
+        if (userName === null || password === null) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInvalidArgument };
+        }
+        const userConfiguration = (0, variant_args_js_1.asMask)(inputArguments[2]);
+        const description = (0, variant_args_js_1.asString)(inputArguments[3]) ?? "";
+        const statusCode = store.addUser(userName, password, userConfiguration, description);
+        if (statusCode === node_opcua_status_code_1.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). */
+function makeModifyUserHandler(options) {
+    const { store, onMutation, onAudit, onUserDeactivated } = options;
+    return async function _modifyUser(inputArguments, context) {
+        const insecure = (0, security_checks_js_1.checkEncryptedChannel)(context);
+        if (insecure)
+            return insecure;
+        const denied = (0, security_checks_js_1.checkSecurityAdminAccess)(context);
+        if (denied)
+            return denied;
+        const userName = (0, variant_args_js_1.asString)(inputArguments[0]);
+        if (userName === null) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInvalidArgument };
+        }
+        const modifyUserConfiguration = (0, variant_args_js_1.asBoolean)(inputArguments[3]);
+        const userConfiguration = (0, variant_args_js_1.asMask)(inputArguments[4]);
+        const statusCode = store.modifyUser(userName, {
+            modifyPassword: (0, variant_args_js_1.asBoolean)(inputArguments[1]),
+            password: (0, variant_args_js_1.asString)(inputArguments[2]) ?? "",
+            modifyUserConfiguration,
+            userConfiguration,
+            modifyDescription: (0, variant_args_js_1.asBoolean)(inputArguments[5]),
+            description: (0, variant_args_js_1.asString)(inputArguments[6]) ?? ""
+        }, context.getUserName());
+        if (statusCode === node_opcua_status_code_1.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). */
+function makeRemoveUserHandler(options) {
+    const { store, onMutation, onAudit, onUserDeactivated } = options;
+    return async function _removeUser(inputArguments, context) {
+        const insecure = (0, security_checks_js_1.checkEncryptedChannel)(context);
+        if (insecure)
+            return insecure;
+        const denied = (0, security_checks_js_1.checkSecurityAdminAccess)(context);
+        if (denied)
+            return denied;
+        const userName = (0, variant_args_js_1.asString)(inputArguments[0]);
+        if (userName === null) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInvalidArgument };
+        }
+        const statusCode = store.removeUser(userName, context.getUserName());
+        if (statusCode === node_opcua_status_code_1.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.
+ */
+function makeChangePasswordHandler(options) {
+    const { store, onMutation, onAudit } = options;
+    return async function _changePassword(inputArguments, context) {
+        const insecure = (0, security_checks_js_1.checkEncryptedChannel)(context);
+        if (insecure)
+            return insecure;
+        const token = context.session?.userIdentityToken;
+        if (!(token instanceof node_opcua_types_1.UserNameIdentityToken)) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInvalidState };
+        }
+        const userName = token.userName ?? "";
+        const oldPassword = (0, variant_args_js_1.asString)(inputArguments[0]);
+        const newPassword = (0, variant_args_js_1.asString)(inputArguments[1]);
+        if (oldPassword === null || newPassword === null) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInvalidArgument };
+        }
+        const statusCode = store.changePassword(userName, oldPassword, newPassword);
+        if (statusCode === node_opcua_status_code_1.StatusCodes.Good && onMutation) {
+            await onMutation();
+        }
+        onAudit?.({
+            method: "ChangePassword",
+            targetUserName: userName,
+            callerUserName: userName,
+            methodNodeId: this.nodeId,
+            statusCode
+        });
+        return { statusCode };
+    };
+}
+//# sourceMappingURL=bind_user_management.js.map

package/dist/bind_user_management.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind_user_management.js","sourceRoot":"","sources":["../source/bind_user_management.ts"],"names":[],"mappings":"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"}

package/dist/harden.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @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";
+/**
+ * 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 declare function hardenAdminOnly(node: BaseNode | null | undefined): void;
+/**
+ * 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 declare function hardenEncryptedOnly(node: BaseNode | null | undefined): void;

package/dist/harden.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hardenAdminOnly = hardenAdminOnly;
+exports.hardenEncryptedOnly = hardenEncryptedOnly;
+const node_opcua_data_model_1 = require("node-opcua-data-model");
+const node_opcua_role_set_common_1 = require("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.
+ */
+function hardenAdminOnly(node) {
+    if (!node)
+        return;
+    node.setRolePermissions([{ roleId: node_opcua_role_set_common_1.WellKnownRoleIds.SecurityAdmin, permissions: node_opcua_data_model_1.allPermissions }]);
+    node.setAccessRestrictions(node_opcua_data_model_1.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`.
+ */
+function hardenEncryptedOnly(node) {
+    if (!node)
+        return;
+    node.setAccessRestrictions(node_opcua_data_model_1.AccessRestrictionsFlag.EncryptionRequired);
+}
+//# sourceMappingURL=harden.js.map

package/dist/harden.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harden.js","sourceRoot":"","sources":["../source/harden.ts"],"names":[],"mappings":";;AA+BA,0CAIC;AAOD,kDAGC;AAtBD,iEAA+E;AAC/E,2EAA8D;AAE9D;;;;GAIG;AACH,SAAgB,eAAe,CAAC,IAAiC;IAC7D,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,IAAI,CAAC,kBAAkB,CAAC,CAAC,EAAE,MAAM,EAAE,6CAAgB,CAAC,aAAa,EAAE,WAAW,EAAE,sCAAc,EAAE,CAAC,CAAC,CAAC;IACnG,IAAI,CAAC,qBAAqB,CAAC,8CAAsB,CAAC,kBAAkB,CAAC,CAAC;AAC1E,CAAC;AAED;;;;GAIG;AACH,SAAgB,mBAAmB,CAAC,IAAiC;IACjE,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,IAAI,CAAC,qBAAqB,CAAC,8CAAsB,CAAC,kBAAkB,CAAC,CAAC;AAC1E,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @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/dist/index.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * @module node-opcua-role-set-server
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createUserManager = exports.checkSecurityAdminAccess = exports.checkEncryptedChannel = exports.RoleSetResolver = exports.installUserManagement = exports.installRoleSet = exports.createRoleBasedSecurity = exports.makeRemoveUserHandler = exports.makeModifyUserHandler = exports.makeChangePasswordHandler = exports.makeAddUserHandler = exports.makeRemoveIdentityHandler = exports.makeAddIdentityHandler = exports.makeRemoveEndpointHandler = exports.makeRemoveApplicationHandler = exports.makeAddEndpointHandler = exports.makeAddApplicationHandler = exports.raiseAuditMethodEvent = void 0;
+var audit_js_1 = require("./audit.js");
+Object.defineProperty(exports, "raiseAuditMethodEvent", { enumerable: true, get: function () { return audit_js_1.raiseAuditMethodEvent; } });
+var bind_restriction_methods_js_1 = require("./bind_restriction_methods.js");
+Object.defineProperty(exports, "makeAddApplicationHandler", { enumerable: true, get: function () { return bind_restriction_methods_js_1.makeAddApplicationHandler; } });
+Object.defineProperty(exports, "makeAddEndpointHandler", { enumerable: true, get: function () { return bind_restriction_methods_js_1.makeAddEndpointHandler; } });
+Object.defineProperty(exports, "makeRemoveApplicationHandler", { enumerable: true, get: function () { return bind_restriction_methods_js_1.makeRemoveApplicationHandler; } });
+Object.defineProperty(exports, "makeRemoveEndpointHandler", { enumerable: true, get: function () { return bind_restriction_methods_js_1.makeRemoveEndpointHandler; } });
+var bind_role_methods_js_1 = require("./bind_role_methods.js");
+Object.defineProperty(exports, "makeAddIdentityHandler", { enumerable: true, get: function () { return bind_role_methods_js_1.makeAddIdentityHandler; } });
+Object.defineProperty(exports, "makeRemoveIdentityHandler", { enumerable: true, get: function () { return bind_role_methods_js_1.makeRemoveIdentityHandler; } });
+var bind_user_management_js_1 = require("./bind_user_management.js");
+Object.defineProperty(exports, "makeAddUserHandler", { enumerable: true, get: function () { return bind_user_management_js_1.makeAddUserHandler; } });
+Object.defineProperty(exports, "makeChangePasswordHandler", { enumerable: true, get: function () { return bind_user_management_js_1.makeChangePasswordHandler; } });
+Object.defineProperty(exports, "makeModifyUserHandler", { enumerable: true, get: function () { return bind_user_management_js_1.makeModifyUserHandler; } });
+Object.defineProperty(exports, "makeRemoveUserHandler", { enumerable: true, get: function () { return bind_user_management_js_1.makeRemoveUserHandler; } });
+var install_role_based_security_js_1 = require("./install_role_based_security.js");
+Object.defineProperty(exports, "createRoleBasedSecurity", { enumerable: true, get: function () { return install_role_based_security_js_1.createRoleBasedSecurity; } });
+var install_role_set_js_1 = require("./install_role_set.js");
+Object.defineProperty(exports, "installRoleSet", { enumerable: true, get: function () { return install_role_set_js_1.installRoleSet; } });
+var install_user_management_js_1 = require("./install_user_management.js");
+Object.defineProperty(exports, "installUserManagement", { enumerable: true, get: function () { return install_user_management_js_1.installUserManagement; } });
+var role_set_resolver_js_1 = require("./role_set_resolver.js");
+Object.defineProperty(exports, "RoleSetResolver", { enumerable: true, get: function () { return role_set_resolver_js_1.RoleSetResolver; } });
+var security_checks_js_1 = require("./security_checks.js");
+Object.defineProperty(exports, "checkEncryptedChannel", { enumerable: true, get: function () { return security_checks_js_1.checkEncryptedChannel; } });
+Object.defineProperty(exports, "checkSecurityAdminAccess", { enumerable: true, get: function () { return security_checks_js_1.checkSecurityAdminAccess; } });
+var user_management_user_manager_js_1 = require("./user_management_user_manager.js");
+Object.defineProperty(exports, "createUserManager", { enumerable: true, get: function () { return user_management_user_manager_js_1.createUserManager; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../source/index.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,uCAAgF;AAA1C,iHAAA,qBAAqB,OAAA;AAC3D,6EAMuC;AAJnC,wIAAA,yBAAyB,OAAA;AACzB,qIAAA,sBAAsB,OAAA;AACtB,2IAAA,4BAA4B,OAAA;AAC5B,wIAAA,yBAAyB,OAAA;AAE7B,+DAKgC;AAH5B,8HAAA,sBAAsB,OAAA;AACtB,iIAAA,yBAAyB,OAAA;AAG7B,qEAOmC;AAL/B,6HAAA,kBAAkB,OAAA;AAClB,oIAAA,yBAAyB,OAAA;AACzB,gIAAA,qBAAqB,OAAA;AACrB,gIAAA,qBAAqB,OAAA;AAGzB,mFAM0C;AAJtC,yIAAA,uBAAuB,OAAA;AAK3B,6DAK+B;AAD3B,qHAAA,cAAc,OAAA;AAElB,2EAKsC;AADlC,mIAAA,qBAAqB,OAAA;AAEzB,+DAAyD;AAAhD,uHAAA,eAAe,OAAA;AACxB,2DAAuF;AAA9E,2HAAA,qBAAqB,OAAA;AAAE,8HAAA,wBAAwB,OAAA;AACxD,qFAAgG;AAAvF,oIAAA,iBAAiB,OAAA"}

package/dist/install_role_based_security.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @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 { UserConfigurationMask } from "node-opcua-types";
+import { type InstallRoleSetResult, type IServerForRoleSet } from "./install_role_set.js";
+import { type InstallUserManagementResult, type IServerForUserManagement } from "./install_user_management.js";
+import { 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;
+    }>;
+}
+/**
+ * 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 declare function createRoleBasedSecurity(options?: CreateRoleBasedSecurityOptions): RoleBasedSecurity;

package/dist/install_role_based_security.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRoleBasedSecurity = createRoleBasedSecurity;
+const node_opcua_role_set_common_1 = require("node-opcua-role-set-common");
+const node_opcua_types_1 = require("node-opcua-types");
+const install_role_set_js_1 = require("./install_role_set.js");
+const install_user_management_js_1 = require("./install_user_management.js");
+const user_management_user_manager_js_1 = require("./user_management_user_manager.js");
+const userNameRule = (userName) => new node_opcua_types_1.IdentityMappingRuleType({ criteriaType: node_opcua_types_1.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()`.
+ */
+function createRoleBasedSecurity(options) {
+    const userStore = new node_opcua_role_set_common_1.InMemoryUserManagementStore(options?.policy);
+    const identityStore = new node_opcua_role_set_common_1.InMemoryIdentityMappingStore();
+    for (const user of options?.users ?? []) {
+        userStore.addUser(user.userName, user.password, user.userConfiguration ?? node_opcua_types_1.UserConfigurationMask.None, user.description ?? "");
+        for (const role of user.roles ?? []) {
+            identityStore.addIdentity(role, userNameRule(user.userName));
+        }
+    }
+    const userManager = (0, user_management_user_manager_js_1.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 node_opcua_role_set_common_1.ArchiveStore(installOptions.persistencePath, { secret: installOptions.persistenceSecret })
+                    : undefined);
+            const roleSet = await (0, install_role_set_js_1.installRoleSet)(server, { store: identityStore, persistence });
+            const userManagement = await (0, install_user_management_js_1.installUserManagement)(server, { store: userStore, persistence });
+            return { roleSet, userManagement };
+        }
+    };
+}
+//# sourceMappingURL=install_role_based_security.js.map

package/dist/install_role_based_security.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install_role_based_security.js","sourceRoot":"","sources":["../source/install_role_based_security.ts"],"names":[],"mappings":";;AA8FA,0DAmCC;AAtGD,2EAKoC;AACpC,uDAAwG;AACxG,+DAA0G;AAC1G,6EAIsC;AACtC,uFAAgG;AA8ChG,MAAM,YAAY,GAAG,CAAC,QAAgB,EAA2B,EAAE,CAC/D,IAAI,0CAAuB,CAAC,EAAE,YAAY,EAAE,uCAAoB,CAAC,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC;AAErG;;;;GAIG;AACH,SAAgB,uBAAuB,CAAC,OAAwC;IAC5E,MAAM,SAAS,GAAG,IAAI,wDAA2B,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IACnE,MAAM,aAAa,GAAG,IAAI,yDAA4B,EAAE,CAAC;IAEzD,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QACtC,SAAS,CAAC,OAAO,CACb,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,QAAQ,EACb,IAAI,CAAC,iBAAiB,IAAI,wCAAqB,CAAC,IAAI,EACpD,IAAI,CAAC,WAAW,IAAI,EAAE,CACzB,CAAC;QACF,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;YAClC,aAAa,CAAC,WAAW,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;QACjE,CAAC;IACL,CAAC;IAED,MAAM,WAAW,GAAG,IAAA,mDAAiB,EAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IAEhE,OAAO;QACH,SAAS;QACT,aAAa;QACb,WAAW;QACX,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,cAAc;YAChC,gFAAgF;YAChF,MAAM,WAAW,GACb,cAAc,EAAE,WAAW;gBAC3B,CAAC,cAAc,EAAE,eAAe;oBAC5B,CAAC,CAAC,IAAI,yCAAY,CAAC,cAAc,CAAC,eAAe,EAAE,EAAE,MAAM,EAAE,cAAc,CAAC,iBAAiB,EAAE,CAAC;oBAChG,CAAC,CAAC,SAAS,CAAC,CAAC;YAErB,MAAM,OAAO,GAAG,MAAM,IAAA,oCAAc,EAAC,MAAM,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC,CAAC;YACpF,MAAM,cAAc,GAAG,MAAM,IAAA,kDAAqB,EAAC,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC,CAAC;YAC9F,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC;QACvC,CAAC;KACJ,CAAC;AACN,CAAC"}

package/dist/install_role_set.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * Install RoleSet management on an OPC UA server.
+ *
+ * This function is designed to be called **after** the server has started
+ * (when the address space is available). It:
+ *   - Creates an InMemoryIdentityMappingStore (optionally loaded from disk)
+ *   - Registers a RoleSetResolver on server.roleResolvers
+ *   - Binds AddIdentity / RemoveIdentity on each Role and keeps the Identities
+ *     Property in sync with the store
+ *   - Binds AddRole / RemoveRole (OPC 10000-18 §4.2): custom Roles are created
+ *     as `ns=1;g=<uuid>` instances of RoleType (collision-proof, stable when
+ *     persisted); well-known Roles cannot be removed.
+ */
+import type { IAddressSpace } from "node-opcua-address-space";
+import { ArchiveStore, type IIdentityMappingStore, type IRoleRestrictionStore } from "node-opcua-role-set-common";
+import { RoleSetResolver } from "./role_set_resolver.js";
+export interface InstallRoleSetOptions {
+    /**
+     * Path to a single consolidated archive file holding the whole RoleSet
+     * configuration (identity mappings, custom Role definitions and
+     * application/endpoint restrictions). Written atomically on every change.
+     */
+    persistencePath?: string;
+    /**
+     * When set, the archive is encrypted at rest (AES-256-GCM, key derived from
+     * this operator-supplied secret). Omit to store plain JSON (relying on
+     * filesystem permissions); the stored password material is salted scrypt
+     * hashes either way.
+     */
+    persistenceSecret?: string;
+    /**
+     * A shared {@link ArchiveStore} coordinating one consolidated file across
+     * `installRoleSet` and `installUserManagement`. Pass the **same** instance to
+     * both so users and roles live in one archive. When omitted, an internal one
+     * is created from `persistencePath`/`persistenceSecret` (role config only).
+     */
+    persistence?: ArchiveStore;
+    /**
+     * Identity-mapping store to bind the RoleSet to. When omitted a new
+     * {@link InMemoryIdentityMappingStore} is created. Inject a shared store so the
+     * **same** mappings drive role resolution (e.g. via the server `userManager`),
+     * the `Identities` Property shown in clients, and the RoleSet Methods —
+     * keeping a single source of truth. Persisted mappings (if any) are merged in.
+     */
+    store?: IIdentityMappingStore;
+}
+export interface InstallRoleSetResult {
+    /** The identity mapping store backing the role set. */
+    store: IIdentityMappingStore;
+    /** The per-Role application/endpoint restriction store (§4.4.1). */
+    restrictionStore: IRoleRestrictionStore;
+    /** The resolver registered on server.roleResolvers. */
+    resolver: RoleSetResolver;
+}
+/**
+ * The server-like object we need — just needs `roleResolvers` and
+ * access to the address space.
+ */
+export interface IServerForRoleSet {
+    roleResolvers: Array<{
+        resolveRoles(token: unknown): unknown[];
+    }>;
+    engine: {
+        addressSpace: IAddressSpace | null;
+    };
+}
+/**
+ * Install RoleSet management on an OPC UA server. Call this **after**
+ * `server.start()` so the address space is available.
+ */
+export declare function installRoleSet(server: IServerForRoleSet, options?: InstallRoleSetOptions): Promise<InstallRoleSetResult>;