node-opcua-role-set-server 2.174.0

package/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2022-2024  Sterfive SAS - 833264583 RCS ORLEANS - France (https://www.sterfive.com)
+
+Copyright (c) 2014-2022 Etienne Rossignon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# node-opcua-role-set-server
+
+Server-side **RoleSet management** for OPC UA (OPC 10000-18 — *Role-Based Security*).
+
+This package wires the `RoleSet` object of an OPC UA server to an identity-mapping
+store. It binds the `AddIdentity` / `RemoveIdentity` methods on each Role, keeps each
+Role's `Identities` property in sync with the store, registers a role resolver that
+maps incoming user identity tokens to roles, and optionally persists the mappings to
+disk.
+
+It builds on [`node-opcua-role-set-common`](../node-opcua-role-set-common) for the
+store, persistence and well-known role NodeIds.
+
+see http://node-opcua.github.io/
+
+## Installation
+
+```bash
+$ npm install node-opcua-role-set-server
+```
+
+## Quick start
+
+Call `installRoleSet` **after** the server has started, when the address space is
+available:
+
+```ts
+import { OPCUAServer } from "node-opcua";
+import { installRoleSet } from "node-opcua-role-set-server";
+
+const server = new OPCUAServer({ /* ... */ });
+await server.start();
+
+const { store, restrictionStore, resolver } = await installRoleSet(server, {
+    persistencePath: "./config/role-set.json",
+    persistenceSecret: process.env.ROLE_SET_SECRET // optional: encrypt at rest
+});
+```
+
+What `installRoleSet` does:
+
+1. Finds the `RoleSet` node (`i=15606`) in the address space.
+2. Loads the whole configuration from the consolidated archive at `persistencePath` (if any):
+   identity mappings, custom Role definitions and application/endpoint restrictions.
+3. Registers a `RoleSetResolver` on `server.roleResolvers` so sessions are mapped to roles at login.
+4. For each Role in the RoleSet:
+   - sets the initial `Identities` (and restriction) property values from the stores;
+   - binds the `AddIdentity` / `RemoveIdentity` and the application/endpoint restriction methods.
+5. Binds `RoleSet.AddRole` / `RoleSet.RemoveRole` (§4.2): custom Roles are created as
+   `ns=1;g=<uuid>` instances of `RoleType` (collision-proof, stable across restarts);
+   well-known Roles cannot be removed.
+6. After every mutation, refreshes the Role variables and atomically rewrites the archive.
+
+### Returned values
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `store` | `IIdentityMappingStore` | The identity-mapping store backing the RoleSet. |
+| `restrictionStore` | `IRoleRestrictionStore` | The per-Role application/endpoint restriction store. |
+| `resolver` | `RoleSetResolver` | The resolver registered on `server.roleResolvers`. |
+
+You can mutate `store` directly (e.g. to seed default mappings); call sites that go
+through the bound methods automatically persist, but direct store changes are not
+written to the archive until the next method-driven mutation.
+
+## User Management & one-call setup
+
+This package also installs **User Management** (§5) and offers a one-call helper
+that wires roles and users to a *single source of truth*. The complete
+end-to-end walkthrough lives in the
+[Role-Based Security & User Management guide](https://github.com/node-opcua/node-opcua/blob/master/documentation/role_based_security.md);
+in short:
+
+```ts
+import { createRoleBasedSecurity } from "node-opcua-role-set-server";
+import { WellKnownRoleIds } from "node-opcua-role-set-common";
+
+const security = createRoleBasedSecurity({
+    users: [{ userName: "admin", password: "admin-pw1", roles: [WellKnownRoleIds.SecurityAdmin] }]
+});
+const server = new OPCUAServer({ /* … */ userManager: security.userManager });
+await server.start();
+await security.install(server, { persistencePath: "./config/role-set.json" });
+```
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `createRoleBasedSecurity(options?)` | **Recommended** — one user store + one identity store behind the `userManager` bridge, with a two-phase `install(server, …)`. |
+| `installRoleSet(server, options?)` | Install RoleSet management (Roles, identities, restrictions, AddRole/RemoveRole). |
+| `installUserManagement(server, options?)` | Install User Management (§5): AddUser / ModifyUser / RemoveUser / ChangePassword. |
+| `createUserManager(userStore, identityStore)` | Build the server `userManager` bridge from a shared user + identity store. |
+| `InstallRoleSetOptions` | `{ store?, persistence?, persistencePath?, persistenceSecret? }`. |
+| `InstallRoleSetResult` | `{ store, restrictionStore, resolver }`. |
+| `InstallUserManagementOptions` / `InstallUserManagementResult` | User Management install options / result. |
+| `IServerForRoleSet` / `IServerForUserManagement` | Minimal server shapes required. |
+| `RoleSetResolver` | Adapts an `IIdentityMappingStore` to the server's `IRoleResolver` contract. |
+| `make…Handler` factories | Build the Method handlers (used internally; exposed for custom binding). |
+| `checkSecurityAdminAccess` / `checkEncryptedChannel` | Authorization helpers (SecurityAdmin Role / encrypted channel). |
+| `raiseAuditMethodEvent` | Raise an `AuditUpdateMethodEventType` (no secrets). |
+
+## Security model
+
+The sensitive RoleSet & User Management nodes are protected with the address
+space's own enforcement, so the checks run in the core *before* any bound
+handler (the per-Method guards are defense-in-depth):
+
+- **Administrative Methods require `SecurityAdmin` over an encrypted channel** —
+  AddRole/RemoveRole, AddIdentity/RemoveIdentity, the restriction Methods and
+  AddUser/ModifyUser/RemoveUser. `ChangePassword` stays callable by any
+  authenticated user (still encrypted).
+- **Non-admins cannot Browse them** (§4.4.1): each Role's `Identities` /
+  `Applications` / `Endpoints` Properties and config Methods, plus the `Users`
+  list, carry SecurityAdmin-only RolePermissions, so they are hidden and
+  unreadable. Role nodes themselves stay browsable.
+- **`EncryptionRequired`** on those nodes → reads over a None/Sign channel return
+  `Bad_SecurityModeInsufficient`.
+- **Disabling (ModifyUser) or removing (RemoveUser) a user terminates their live
+  sessions** (§5.2.6-7), not just their ability to re-authenticate.
+
+Status codes returned by the identity Method handlers:
+
+| Status | Condition |
+|--------|-----------|
+| `Good` | The identity was added / removed. |
+| `BadUserAccessDenied` | The session does not hold the `SecurityAdmin` role. |
+| `BadSecurityModeInsufficient` | The channel is not `SignAndEncrypt`. |
+| `BadInvalidArgument` | The input argument is not an `IdentityMappingRuleType`. |
+| `BadNoMatch` | `RemoveIdentity` — no matching rule was found. |
+| `BadAlreadyExists` | `AddRole` — the RoleName duplicates an existing (well-known or custom) Role. |
+| `BadRequestNotAllowed` | `RemoveRole` — well-known Roles cannot be removed. |
+
+## Persistence
+
+When `persistencePath` is supplied, the **entire** RoleSet configuration is kept in a
+single consolidated archive (identity mappings, custom Role definitions and
+application/endpoint restrictions):
+
+- the archive is loaded on install (a missing file is a no-op);
+- it is **atomically** rewritten (temp file + rename) after every successful mutation, so
+  a crash can never leave a half-written file;
+- when `persistenceSecret` is set the whole payload is encrypted at rest with AES-256-GCM
+  (key derived from the secret via scrypt); otherwise it is plain, human-readable JSON
+  with the identity mappings embedded as a base64 binary blob.
+
+The archive format (`readArchive` / `writeArchive`, version-checked) is defined in
+[`node-opcua-role-set-common`](../node-opcua-role-set-common).
+
+### Sharing the archive with User Management
+
+To keep **users** (salted scrypt hashes, never clear passwords) in the *same* file as the
+role configuration, create one `ArchiveStore` and pass it to both installers:
+
+```ts
+import { ArchiveStore } from "node-opcua-role-set-common";
+
+const persistence = new ArchiveStore("./config/role-set.json", {
+    secret: process.env.ROLE_SET_SECRET // optional encryption
+});
+await installRoleSet(server, { persistence });
+await installUserManagement(server, { persistence });
+```
+
+The coordinator gathers every registered section (identities / roles / restrictions / users)
+and rewrites the one file atomically on each mutation, so neither installer clobbers the
+other — a section with no provider yet keeps its last loaded value, so the result is
+independent of install order. Pass only `persistencePath` instead for a role-config-only
+(or users-only) file.
+
+## Related packages
+
+- [`node-opcua-role-set-common`](../node-opcua-role-set-common) — shared types, identity/user stores and persistence.
+- [`node-opcua-role-set-client`](../node-opcua-role-set-client) — client-side role browsing, identity & user management.
+- [`node-opcua-role-set-admin`](../node-opcua-role-set-admin) — the `role-set-admin` command-line tool.
+- [Role-Based Security & User Management guide](https://github.com/node-opcua/node-opcua/blob/master/documentation/role_based_security.md) — cross-package overview & getting started.
+
+# License
+
+Node-OPCUA is made available to you under the MIT open source license.
+
+See [LICENSE](./LICENSE) for details.
+
+# Copyright
+
+Copyright (c) 2022-2026 Sterfive SAS - https://www.sterfive.com
+
+Copyright (c) 2014-2022 Etienne Rossignon

package/dist/audit.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * Shared helper to raise an audit method event (a subtype of
+ * AuditUpdateMethodEventType) on the Server Object.
+ */
+import type { UAObject } from "node-opcua-address-space";
+import { NodeId } from "node-opcua-nodeid";
+import type { Variant } from "node-opcua-variant";
+export interface AuditMethodEventFields {
+    /** The Node the audited operation acted on (Role / UserManagement Object). */
+    sourceNode: NodeId;
+    /** A short label, e.g. "Method/AddIdentity". */
+    sourceName: string;
+    /** The audited Method NodeId (omit for events not raised from a single Method call). */
+    methodId?: NodeId;
+    /** The Session user who invoked the Method. */
+    clientUserId: string;
+    /** TRUE when the operation succeeded. */
+    status: boolean;
+    /** Human-readable message (must NOT contain secrets such as passwords). */
+    message: string;
+    /**
+     * The Method input arguments — include ONLY when they carry no secret
+     * (e.g. an IdentityMappingRule). Omit for password-bearing Methods.
+     */
+    inputArguments?: Variant[];
+}
+/**
+ * Raise `eventType` on the given Server Object with the standard
+ * AuditUpdateMethodEventType fields. No-op if there is no Server Object.
+ */
+export declare function raiseAuditMethodEvent(serverObject: UAObject | undefined, eventType: string, fields: AuditMethodEventFields): void;

package/dist/audit.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.raiseAuditMethodEvent = raiseAuditMethodEvent;
+const node_opcua_nodeid_1 = require("node-opcua-nodeid");
+const node_opcua_variant_1 = require("node-opcua-variant");
+/**
+ * Raise `eventType` on the given Server Object with the standard
+ * AuditUpdateMethodEventType fields. No-op if there is no Server Object.
+ */
+function raiseAuditMethodEvent(serverObject, eventType, fields) {
+    if (!serverObject) {
+        return;
+    }
+    serverObject.raiseEvent(eventType, {
+        actionTimeStamp: { dataType: "DateTime", value: new Date() },
+        status: { dataType: "Boolean", value: fields.status },
+        serverId: { dataType: "String", value: "" },
+        clientAuditEntryId: { dataType: "String", value: "" },
+        clientUserId: { dataType: "String", value: fields.clientUserId },
+        sourceNode: { dataType: "NodeId", value: fields.sourceNode },
+        sourceName: { dataType: "String", value: fields.sourceName },
+        methodId: { dataType: "NodeId", value: fields.methodId ?? node_opcua_nodeid_1.NodeId.nullNodeId },
+        severity: { dataType: "UInt16", value: 10 },
+        message: { dataType: "LocalizedText", value: fields.message },
+        inputArguments: { dataType: "Variant", arrayType: node_opcua_variant_1.VariantArrayType.Array, value: fields.inputArguments ?? [] }
+    });
+}
+//# sourceMappingURL=audit.js.map

package/dist/audit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.js","sourceRoot":"","sources":["../source/audit.ts"],"names":[],"mappings":";;AAmCA,sDAiBC;AA7CD,yDAA2C;AAE3C,2DAAsD;AAsBtD;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,YAAkC,EAAE,SAAiB,EAAE,MAA8B;IACvH,IAAI,CAAC,YAAY,EAAE,CAAC;QAChB,OAAO;IACX,CAAC;IACD,YAAY,CAAC,UAAU,CAAC,SAAS,EAAE;QAC/B,eAAe,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,IAAI,EAAE,EAAE;QAC5D,MAAM,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE;QACrD,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3C,kBAAkB,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE;QACrD,YAAY,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE;QAChE,UAAU,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE;QAC5D,UAAU,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,EAAE;QAC5D,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,CAAC,QAAQ,IAAI,0BAAM,CAAC,UAAU,EAAE;QAC7E,QAAQ,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE;QAC3C,OAAO,EAAE,EAAE,QAAQ,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE;QAC7D,cAAc,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,qCAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,cAAc,IAAI,EAAE,EAAE;KACjH,CAAC,CAAC;AACP,CAAC"}

package/dist/bind_restriction_methods.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * Method handlers for the RoleType application/endpoint restriction Methods
+ * (OPC 10000-18 §4.4.7-10): AddApplication / RemoveApplication / AddEndpoint /
+ * RemoveEndpoint, backed by an {@link IRoleRestrictionStore}.
+ *
+ * All require the SecurityAdmin Role and an encrypted channel, and raise a
+ * RoleMappingRuleChangedAuditEventType (§4.5, reusing the same audit hook as the
+ * identity Methods).
+ */
+import type { ISessionContext, UAMethod } from "node-opcua-address-space-base";
+import type { IRoleRestrictionStore } from "node-opcua-role-set-common";
+import type { CallMethodResultOptions } from "node-opcua-service-call";
+import type { Variant } from "node-opcua-variant";
+import type { RoleMappingRuleChangedAudit } from "./bind_role_methods.js";
+export interface BindRestrictionMethodsOptions {
+    restrictionStore: IRoleRestrictionStore;
+    /** Called after every successful mutation so the caller can persist / refresh. */
+    onMutation?: () => Promise<void>;
+    /** Called after an authorized attempt to raise an audit event. */
+    onAudit?: (audit: RoleMappingRuleChangedAudit) => void;
+}
+/** AddApplication (§4.4.7). */
+export declare function makeAddApplicationHandler(options: BindRestrictionMethodsOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;
+/** RemoveApplication (§4.4.8). */
+export declare function makeRemoveApplicationHandler(options: BindRestrictionMethodsOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;
+/** AddEndpoint (§4.4.9). */
+export declare function makeAddEndpointHandler(options: BindRestrictionMethodsOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;
+/** RemoveEndpoint (§4.4.10). */
+export declare function makeRemoveEndpointHandler(options: BindRestrictionMethodsOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;

package/dist/bind_restriction_methods.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeAddApplicationHandler = makeAddApplicationHandler;
+exports.makeRemoveApplicationHandler = makeRemoveApplicationHandler;
+exports.makeAddEndpointHandler = makeAddEndpointHandler;
+exports.makeRemoveEndpointHandler = makeRemoveEndpointHandler;
+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");
+function endpointFromArg(v) {
+    if (!v || !(v.value instanceof node_opcua_types_1.EndpointType)) {
+        return null;
+    }
+    const e = v.value;
+    return {
+        endpointUrl: e.endpointUrl ?? undefined,
+        securityMode: e.securityMode,
+        securityPolicyUri: e.securityPolicyUri ?? undefined,
+        transportProfileUri: e.transportProfileUri ?? undefined
+    };
+}
+/**
+ * Build a handler that, after the SecurityAdmin + encrypted-channel checks,
+ * applies `mutate` to the Role's restrictions, persists, and audits.
+ */
+function makeRestrictionHandler(options, method, mutate) {
+    const { onMutation, onAudit } = options;
+    return async function (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 roleNode = this.parent;
+        if (!roleNode) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInternalError };
+        }
+        const statusCode = mutate(roleNode.nodeId, inputArguments);
+        if (statusCode === null) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInvalidArgument };
+        }
+        if (statusCode === node_opcua_status_code_1.StatusCodes.Good && onMutation) {
+            await onMutation();
+        }
+        onAudit?.({
+            method,
+            roleNodeId: roleNode.nodeId,
+            methodNodeId: this.nodeId,
+            userName: context.getUserName(),
+            inputArguments,
+            statusCode
+        });
+        return { statusCode };
+    };
+}
+/** AddApplication (§4.4.7). */
+function makeAddApplicationHandler(options) {
+    return makeRestrictionHandler(options, "AddApplication", (roleNodeId, args) => {
+        const uri = (0, variant_args_js_1.asString)(args[0]);
+        if (uri === null)
+            return null;
+        return options.restrictionStore.addApplication(roleNodeId, uri) ? node_opcua_status_code_1.StatusCodes.Good : node_opcua_status_code_1.StatusCodes.BadAlreadyExists;
+    });
+}
+/** RemoveApplication (§4.4.8). */
+function makeRemoveApplicationHandler(options) {
+    return makeRestrictionHandler(options, "RemoveApplication", (roleNodeId, args) => {
+        const uri = (0, variant_args_js_1.asString)(args[0]);
+        if (uri === null)
+            return null;
+        return options.restrictionStore.removeApplication(roleNodeId, uri) ? node_opcua_status_code_1.StatusCodes.Good : node_opcua_status_code_1.StatusCodes.BadNotFound;
+    });
+}
+/** AddEndpoint (§4.4.9). */
+function makeAddEndpointHandler(options) {
+    return makeRestrictionHandler(options, "AddEndpoint", (roleNodeId, args) => {
+        const endpoint = endpointFromArg(args[0]);
+        if (endpoint === null)
+            return null;
+        return options.restrictionStore.addEndpoint(roleNodeId, endpoint) ? node_opcua_status_code_1.StatusCodes.Good : node_opcua_status_code_1.StatusCodes.BadAlreadyExists;
+    });
+}
+/** RemoveEndpoint (§4.4.10). */
+function makeRemoveEndpointHandler(options) {
+    return makeRestrictionHandler(options, "RemoveEndpoint", (roleNodeId, args) => {
+        const endpoint = endpointFromArg(args[0]);
+        if (endpoint === null)
+            return null;
+        return options.restrictionStore.removeEndpoint(roleNodeId, endpoint) ? node_opcua_status_code_1.StatusCodes.Good : node_opcua_status_code_1.StatusCodes.BadNotFound;
+    });
+}
+//# sourceMappingURL=bind_restriction_methods.js.map

package/dist/bind_restriction_methods.js.map

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

package/dist/bind_role_methods.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @module node-opcua-role-set-server
+ *
+ * Method handlers for RoleType AddIdentity / RemoveIdentity
+ * and RoleSetType AddRole / RemoveRole.
+ *
+ * Each handler follows the OPC UA method binding pattern:
+ *   - `this` is the UAMethod node
+ *   - `inputArguments` is Variant[]
+ *   - `context` is ISessionContext
+ *   - returns Promise<CallMethodResultOptions>
+ */
+import type { ISessionContext, UAMethod } from "node-opcua-address-space-base";
+import type { NodeId } from "node-opcua-nodeid";
+import { type IIdentityMappingStore } 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 an identity-mapping change, passed to {@link BindRoleMethodsOptions.onAudit}
+ * so the caller can raise a `RoleMappingRuleChangedAuditEventType` (OPC 10000-18 §4.5).
+ * Raised for every authorized attempt — both successful updates and refusals
+ * (e.g. immutable Role, duplicate) — with the resulting `statusCode`.
+ */
+export interface RoleMappingRuleChangedAudit {
+    method: "AddIdentity" | "RemoveIdentity" | "AddApplication" | "RemoveApplication" | "AddEndpoint" | "RemoveEndpoint";
+    roleNodeId: NodeId;
+    methodNodeId: NodeId;
+    userName: string;
+    inputArguments: Variant[];
+    statusCode: StatusCode;
+}
+export interface BindRoleMethodsOptions {
+    store: IIdentityMappingStore;
+    /** Called after every mutation (add/remove) so the caller can persist. */
+    onMutation?: () => Promise<void>;
+    /** Called after an authorized AddIdentity/RemoveIdentity attempt to raise an audit event. */
+    onAudit?: (audit: RoleMappingRuleChangedAudit) => void;
+}
+/**
+ * Create an AddIdentity method handler bound to the given store.
+ * The handler extracts the role NodeId from its parent Role object.
+ */
+export declare function makeAddIdentityHandler(options: BindRoleMethodsOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;
+/**
+ * Create a RemoveIdentity method handler bound to the given store.
+ */
+export declare function makeRemoveIdentityHandler(options: BindRoleMethodsOptions): (this: UAMethod, inputArguments: Variant[], context: ISessionContext) => Promise<CallMethodResultOptions>;

package/dist/bind_role_methods.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.makeAddIdentityHandler = makeAddIdentityHandler;
+exports.makeRemoveIdentityHandler = makeRemoveIdentityHandler;
+const node_opcua_nodeid_1 = require("node-opcua-nodeid");
+const node_opcua_role_set_common_1 = require("node-opcua-role-set-common");
+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");
+/**
+ * Well-known Roles whose mapping rules a Server shall not allow to be
+ * changed (OPC 10000-18 §4.3): Anonymous, AuthenticatedUser and
+ * TrustedApplication. (TrustedApplication has no constant in this build and
+ * is matched by NodeId when present.)
+ */
+function isImmutableRole(roleId) {
+    return (0, node_opcua_nodeid_1.sameNodeId)(roleId, node_opcua_role_set_common_1.WellKnownRoleIds.Anonymous) || (0, node_opcua_nodeid_1.sameNodeId)(roleId, node_opcua_role_set_common_1.WellKnownRoleIds.AuthenticatedUser);
+}
+/**
+ * Administrative Roles to which weak (Anonymous / AuthenticatedUser) identity
+ * rules must not be added (OPC 10000-18 §4.4.5: a Server should refuse to add
+ * an ANONYMOUS_5 rule to Roles with administrator privileges).
+ */
+function isPrivilegedRole(roleId) {
+    return (0, node_opcua_nodeid_1.sameNodeId)(roleId, node_opcua_role_set_common_1.WellKnownRoleIds.SecurityAdmin) || (0, node_opcua_nodeid_1.sameNodeId)(roleId, node_opcua_role_set_common_1.WellKnownRoleIds.ConfigureAdmin);
+}
+/** True for weak criteria that must not be granted to administrative Roles. */
+function isWeakCriteria(criteriaType) {
+    return criteriaType === node_opcua_types_1.IdentityCriteriaType.Anonymous || criteriaType === node_opcua_types_1.IdentityCriteriaType.AuthenticatedUser;
+}
+/**
+ * Extract the IdentityMappingRuleType from the first input argument.
+ */
+function extractIdentityRule(inputArguments) {
+    if (!inputArguments || inputArguments.length < 1) {
+        return null;
+    }
+    const value = inputArguments[0].value;
+    if (value instanceof node_opcua_types_1.IdentityMappingRuleType) {
+        return value;
+    }
+    return null;
+}
+/**
+ * Create an AddIdentity method handler bound to the given store.
+ * The handler extracts the role NodeId from its parent Role object.
+ */
+function makeAddIdentityHandler(options) {
+    const { store, onMutation, onAudit } = options;
+    return async function _addIdentity(inputArguments, context) {
+        // 1. The SecureChannel must be encrypted
+        const insecure = (0, security_checks_js_1.checkEncryptedChannel)(context);
+        if (insecure)
+            return insecure;
+        // 2. Security check
+        const denied = (0, security_checks_js_1.checkSecurityAdminAccess)(context);
+        if (denied)
+            return denied;
+        // 3. Extract the rule from input
+        const rule = extractIdentityRule(inputArguments);
+        if (!rule) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInvalidArgument };
+        }
+        // 4. The parent of this method is the Role object
+        const roleNode = this.parent;
+        if (!roleNode) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInternalError };
+        }
+        // 5-7. Compute the outcome of the authorized rule-change attempt
+        let statusCode;
+        if (isImmutableRole(roleNode.nodeId)) {
+            // well-known immutable Roles cannot be changed (§4.3)
+            statusCode = node_opcua_status_code_1.StatusCodes.BadRequestNotAllowed;
+        }
+        else if (isWeakCriteria(rule.criteriaType) && isPrivilegedRole(roleNode.nodeId)) {
+            // refuse weak (Anonymous/AuthenticatedUser) rules on administrative Roles (§4.4.5)
+            statusCode = node_opcua_status_code_1.StatusCodes.BadRequestNotAllowed;
+        }
+        else {
+            // duplicate rule is reported as Bad_AlreadyExists
+            statusCode = store.addIdentity(roleNode.nodeId, rule) ? node_opcua_status_code_1.StatusCodes.Good : node_opcua_status_code_1.StatusCodes.BadAlreadyExists;
+        }
+        if (statusCode === node_opcua_status_code_1.StatusCodes.Good && onMutation) {
+            await onMutation();
+        }
+        onAudit?.({
+            method: "AddIdentity",
+            roleNodeId: roleNode.nodeId,
+            methodNodeId: this.nodeId,
+            userName: context.getUserName(),
+            inputArguments,
+            statusCode
+        });
+        return { statusCode };
+    };
+}
+/**
+ * Create a RemoveIdentity method handler bound to the given store.
+ */
+function makeRemoveIdentityHandler(options) {
+    const { store, onMutation, onAudit } = options;
+    return async function _removeIdentity(inputArguments, context) {
+        // 1. The SecureChannel must be encrypted
+        const insecure = (0, security_checks_js_1.checkEncryptedChannel)(context);
+        if (insecure)
+            return insecure;
+        // 2. Security check
+        const denied = (0, security_checks_js_1.checkSecurityAdminAccess)(context);
+        if (denied)
+            return denied;
+        // 3. Extract the rule from input
+        const rule = extractIdentityRule(inputArguments);
+        if (!rule) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInvalidArgument };
+        }
+        // 4. The parent of this method is the Role object
+        const roleNode = this.parent;
+        if (!roleNode) {
+            return { statusCode: node_opcua_status_code_1.StatusCodes.BadInternalError };
+        }
+        // 5-6. Compute the outcome of the authorized rule-change attempt
+        let statusCode;
+        if (isImmutableRole(roleNode.nodeId)) {
+            statusCode = node_opcua_status_code_1.StatusCodes.BadRequestNotAllowed;
+        }
+        else {
+            statusCode = store.removeIdentity(roleNode.nodeId, rule) ? node_opcua_status_code_1.StatusCodes.Good : node_opcua_status_code_1.StatusCodes.BadNoMatch;
+        }
+        if (statusCode === node_opcua_status_code_1.StatusCodes.Good && onMutation) {
+            await onMutation();
+        }
+        onAudit?.({
+            method: "RemoveIdentity",
+            roleNodeId: roleNode.nodeId,
+            methodNodeId: this.nodeId,
+            userName: context.getUserName(),
+            inputArguments,
+            statusCode
+        });
+        return { statusCode };
+    };
+}
+//# sourceMappingURL=bind_role_methods.js.map

package/dist/bind_role_methods.js.map

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