node-opcua-alias-name-server 2.176.0

package/source/bind_configuration_methods.ts

@@ -0,0 +1,219 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * `AddAliasesToCategory` (clause 6.3.4) and `DeleteAliasesFromCategory`
+ * (clause 6.3.5) — the *AliasName Configuration Support* facet, CU 5874.
+ *
+ * Both report **per item**: the Method itself succeeds and an `ErrorCodes` array
+ * parallel to `AliasNames` says what happened to each one. A single bad entry
+ * does not fail the call, which is why the store interface returns
+ * `StatusCode[]` rather than throwing.
+ */
+
+import type { ISessionContext, UAMethod, UAObject } from "node-opcua-address-space-base";
+import type { AliasEntry, IAliasStore } from "node-opcua-alias-name-common";
+import { type ExpandedNodeId, type NodeId, NodeId as NodeIdClass } from "node-opcua-nodeid";
+import type { CallMethodResultOptions } from "node-opcua-service-call";
+import { type StatusCode, StatusCodes } from "node-opcua-status-code";
+import { DataType, type Variant, VariantArrayType } from "node-opcua-variant";
+import { ALIAS_FOR } from "./well_known.js";
+
+export interface ConfigurationBindingOptions {
+    /** The store that performs the mutation. Must implement `add` / `delete`. */
+    store: IAliasStore;
+    /**
+     * Write gate (clause 6.3.4 Table 11 / 6.3.5 Table 15). **Defaults to denying
+     * everyone** — the write surface is the one place a permissive default would
+     * be a security defect rather than a convenience.
+     */
+    isWriteAllowed?: (context: ISessionContext, categoryNodeId: NodeId) => boolean | Promise<boolean>;
+    /** Called after a successful mutation so `LastChange` can move. */
+    onChanged?: (categoryNodeId: NodeId) => void | Promise<void>;
+}
+
+/** Read a String[] argument, tolerating null for "empty". */
+function readStringArray(inputArguments: Variant[], index: number): string[] | null {
+    const value = inputArguments?.[index]?.value;
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    return value.map((v) => (typeof v === "string" ? v : String(v)));
+}
+
+/** Read an ExpandedNodeId[] argument, tolerating null for "empty". */
+function readNodeIdArray(inputArguments: Variant[], index: number): ExpandedNodeId[] | null {
+    const value = inputArguments?.[index]?.value;
+    if (value === null || value === undefined) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    return value as ExpandedNodeId[];
+}
+
+/** Build the OutputArguments Variant for an ErrorCodes array. */
+function errorCodesResult(codes: StatusCode[]): CallMethodResultOptions {
+    return {
+        statusCode: StatusCodes.Good,
+        outputArguments: [
+            {
+                dataType: DataType.StatusCode,
+                arrayType: VariantArrayType.Array,
+                value: codes
+            }
+        ]
+    };
+}
+
+/**
+ * Handler for `AddAliasesToCategory` (clause 6.3.4).
+ *
+ * Table 11 governs the *call*: `Bad_InvalidArgument` when an argument is the
+ * wrong type, when the arrays other than `TargetServers` differ in length, or
+ * when all arrays are empty. Table 10 governs each *item*.
+ */
+export function makeAddAliasesToCategoryHandler(options: ConfigurationBindingOptions) {
+    return async function addAliasesToCategoryHandler(
+        this: UAMethod,
+        inputArguments: Variant[],
+        context: ISessionContext
+    ): Promise<CallMethodResultOptions> {
+        const category = this.parent as UAObject | null;
+        if (!category) {
+            return { statusCode: StatusCodes.BadInternalError };
+        }
+
+        // clause 6.3.4 Table 11
+        if (!(await isWriteAllowed(options, context, category.nodeId))) {
+            return { statusCode: StatusCodes.BadUserAccessDenied };
+        }
+
+        const aliasNames = readStringArray(inputArguments, 0);
+        const targetNodes = readNodeIdArray(inputArguments, 1);
+        const targetServers = readStringArray(inputArguments, 2);
+        const targetReferenceTypeRaw = inputArguments?.[3]?.value;
+
+        if (aliasNames === null || targetNodes === null || targetServers === null) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+        // "the size of the arrays for all arguments except TargetServers is not
+        // the same" - TargetServers is excluded because Table 9 lets it be null
+        // or empty to mean "all local"
+        if (aliasNames.length !== targetNodes.length) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+        // "or if all arrays are empty"
+        if (aliasNames.length === 0) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+        if (targetServers.length !== 0 && targetServers.length !== aliasNames.length) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+
+        // Table 9: "If null, it defaults to AliasFor."
+        const referenceTypeId =
+            targetReferenceTypeRaw instanceof NodeIdClass && !targetReferenceTypeRaw.isEmpty() ? targetReferenceTypeRaw : ALIAS_FOR;
+
+        const entries: AliasEntry[] = aliasNames.map((aliasName, i) => {
+            // Table 9: "The ServerIndex in the ExpandedNodeId shall be ignored
+            // and the TargetServers Uri shall be used."
+            const serverUri = targetServers[i] ? targetServers[i] : null;
+            return {
+                aliasName,
+                referencedNodes: [targetNodes[i]],
+                serverUris: [serverUri],
+                categoryNodeId: category.nodeId,
+                referenceTypeIds: [referenceTypeId]
+            };
+        });
+
+        if (!options.store.add) {
+            // a read-only store: every item is unsupported, but the call itself
+            // succeeded in reporting that
+            return errorCodesResult(entries.map(() => StatusCodes.BadNotSupported));
+        }
+
+        const codes = await options.store.add(category.nodeId, entries);
+        if (codes.some((code) => code.isGood())) {
+            await options.onChanged?.(category.nodeId);
+        }
+        return errorCodesResult(codes);
+    };
+}
+
+/**
+ * Handler for `DeleteAliasesFromCategory` (clause 6.3.5).
+ *
+ * Table 15 governs the call: unlike Add, **every** array must be the same
+ * length — "the size of the arrays for all arguments is not the same", with no
+ * exception, because there is no `TargetServers` here.
+ */
+export function makeDeleteAliasesFromCategoryHandler(options: ConfigurationBindingOptions) {
+    return async function deleteAliasesFromCategoryHandler(
+        this: UAMethod,
+        inputArguments: Variant[],
+        context: ISessionContext
+    ): Promise<CallMethodResultOptions> {
+        const category = this.parent as UAObject | null;
+        if (!category) {
+            return { statusCode: StatusCodes.BadInternalError };
+        }
+
+        if (!(await isWriteAllowed(options, context, category.nodeId))) {
+            return { statusCode: StatusCodes.BadUserAccessDenied };
+        }
+
+        const aliasNames = readStringArray(inputArguments, 0);
+        const targetNodes = readNodeIdArray(inputArguments, 1);
+
+        if (aliasNames === null || targetNodes === null) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+        if (aliasNames.length === 0) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+        // Table 13: "The length of each of the arrays shall be the same." A null
+        // TargetNodes array is the documented way to say "every target", so an
+        // empty array is accepted and expanded.
+        if (targetNodes.length !== 0 && targetNodes.length !== aliasNames.length) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+
+        const entries = aliasNames.map((aliasName, i) => {
+            // "If the TargetNodes array entry is null or empty, all AliasNames
+            // with the provided name are deleted from the AliasNameCategory."
+            const target = targetNodes[i];
+            const referencedNodes = target && !target.isEmpty() ? [target] : [];
+            return { aliasName, referencedNodes };
+        });
+
+        if (!options.store.delete) {
+            return errorCodesResult(entries.map(() => StatusCodes.BadNotSupported));
+        }
+
+        const codes = await options.store.delete(category.nodeId, entries);
+        if (codes.some((code) => code.isGood())) {
+            await options.onChanged?.(category.nodeId);
+        }
+        return errorCodesResult(codes);
+    };
+}
+
+/** The write gate, defaulting to deny. */
+async function isWriteAllowed(
+    options: ConfigurationBindingOptions,
+    context: ISessionContext,
+    categoryNodeId: NodeId
+): Promise<boolean> {
+    if (!options.isWriteAllowed) {
+        // Writing is off unless the Server says who may do it. OPC 10000-17
+        // defines no security model at all, so there is no safe default rule to
+        // fall back on - only a safe default answer.
+        return false;
+    }
+    return await options.isWriteAllowed(context, categoryNodeId);
+}

package/source/bind_find_alias.ts

@@ -0,0 +1,290 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * The `FindAlias` (clause 6.3.2) and `FindAliasVerbose` (clause 6.3.3) Method
+ * handlers.
+ *
+ * The two Methods are identical in every respect except the DataType they
+ * return, so both are produced from one implementation: whatever the FindAlias
+ * suite proves is proved for FindAliasVerbose too.
+ */
+
+import type { ISessionContext, UAMethod, UAObject } from "node-opcua-address-space-base";
+import { type AliasEntry, type AliasQuery, type IAliasStore, InvalidLikePatternError } from "node-opcua-alias-name-common";
+import { type NodeId, NodeId as NodeIdClass } from "node-opcua-nodeid";
+import type { CallMethodResultOptions } from "node-opcua-service-call";
+import { StatusCodes } from "node-opcua-status-code";
+import { AliasNameDataType, AliasNameVerboseDataType } from "node-opcua-types";
+import { DataType, type Variant, VariantArrayType } from "node-opcua-variant";
+
+/**
+ * Orders results before they are returned.
+ *
+ * Clause 6.3.2 requires the Server to return "what it recommends as the best
+ * match first", and says the criteria are Server specific — the examples it
+ * gives (ServerStatus of the Server holding the Node, load balancing) only mean
+ * anything once more than one Server is involved. A Server publishing its own
+ * aliases has no basis to prefer one of its own Nodes over another, so the
+ * default preserves discovery order, which is at least deterministic and
+ * therefore stable across calls. Replace it when the Server does have a basis.
+ */
+export type AliasComparator = (a: AliasEntry, b: AliasEntry) => number;
+
+/** The default: keep discovery order (a stable no-op comparator). */
+export const insertionOrderComparator: AliasComparator = () => 0;
+
+export interface FindAliasBindingOptions {
+    /** Where the aliases come from. */
+    store: IAliasStore;
+    /**
+     * Beyond this many results the call fails with `Bad_ResponseTooLarge`
+     * (clause 6.3.2 Table 4).
+     */
+    maxResults: number;
+    /** Result ordering; defaults to {@link insertionOrderComparator}. */
+    comparator?: AliasComparator;
+    /**
+     * Read gate. Return false to answer `Bad_UserAccessDenied`
+     * (clause 6.3.2 Table 4). Defaults to allowing everyone, matching a Server
+     * that publishes its aliases openly.
+     *
+     * Receives the category the Method was called on, so a Server with
+     * per-customer or per-tenant categories can answer "may this user see *this*
+     * category" rather than only "may this user read aliases at all". May return
+     * a Promise: the handler is async anyway, so a permission lookup that hits a
+     * database costs nothing structurally.
+     */
+    isReadAllowed?: (context: ISessionContext, categoryNodeId: NodeId) => boolean | Promise<boolean>;
+}
+
+/** Read `AliasNameSearchPattern` (argument 0). */
+function readPattern(inputArguments: Variant[]): string | null {
+    const value = inputArguments?.[0]?.value;
+    if (value === null || value === undefined) {
+        // clause 6.3.2 gives no meaning to a null pattern; treat it as "match
+        // everything" would silently dump the whole hierarchy, so reject it
+        return null;
+    }
+    return typeof value === "string" ? value : null;
+}
+
+/** Read `ReferenceTypeFilter` (argument 1). */
+function readReferenceTypeFilter(inputArguments: Variant[]): NodeId | undefined {
+    const value = inputArguments?.[1]?.value;
+    return value instanceof NodeIdClass ? value : undefined;
+}
+
+/**
+ * Merge entries that share an AliasName.
+ *
+ * `AliasNameDataType` is "an array of ExpandedNodeId for a single AliasName"
+ * (clause 7.2), so the non-verbose Method reports one entry per distinct name
+ * with all of its targets. The verbose form does *not* merge: its
+ * `AliasNameCategoryId` names the category that held the alias, which differs
+ * between entries.
+ */
+function mergeByAliasName(entries: AliasEntry[]): AliasEntry[] {
+    const byName = new Map<string, AliasEntry>();
+    // Membership is kept in a Set per name rather than rescanning the growing
+    // array: with a linear scan, a name shared by many entries makes this
+    // quadratic in the size of the result set.
+    const seenTargets = new Map<string, Set<string>>();
+
+    for (const entry of entries) {
+        const existing = byName.get(entry.aliasName);
+        if (!existing) {
+            byName.set(entry.aliasName, { ...entry, referencedNodes: [...entry.referencedNodes] });
+            seenTargets.set(entry.aliasName, new Set(entry.referencedNodes.map((n) => n.toString())));
+            continue;
+        }
+        // written alongside byName above, so it is always present
+        const seen = seenTargets.get(entry.aliasName) ?? new Set<string>();
+        seenTargets.set(entry.aliasName, seen);
+        for (const node of entry.referencedNodes) {
+            const key = node.toString();
+            if (!seen.has(key)) {
+                seen.add(key);
+                existing.referencedNodes.push(node);
+            }
+        }
+    }
+    return [...byName.values()];
+}
+
+/**
+ * Resolve each entry's AliasName namespace index, once per call.
+ *
+ * The namespace reported is the one the alias was published in, taken from the
+ * store. Using the *category's* namespace instead would put every alias on the
+ * three well-known categories into namespace 0, which is reserved for the OPC
+ * Foundation and is not what clause 6.2 intends. A store that does not know its
+ * namespace falls back to the Server's own, never to 0.
+ *
+ * Clients ignore the namespace when comparing AliasNames (clause 6.2), so this
+ * is not a matching concern — it is a matter of reporting truthfully.
+ */
+function makeNamespaceResolver(category: UAObject): (entry: AliasEntry) => number {
+    const addressSpace = category.addressSpace;
+    const ownNamespaceIndex = addressSpace.getOwnNamespace().index;
+    const cache = new Map<string, number>();
+
+    return (entry: AliasEntry): number => {
+        if (!entry.aliasNameNamespaceUri) {
+            return ownNamespaceIndex;
+        }
+        const cached = cache.get(entry.aliasNameNamespaceUri);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const index = addressSpace.getNamespaceIndex(entry.aliasNameNamespaceUri);
+        // an unregistered URI resolves to -1; reporting the Server's own
+        // namespace is closer to the truth than reporting namespace 0
+        const resolved = index >= 0 ? index : ownNamespaceIndex;
+        cache.set(entry.aliasNameNamespaceUri, resolved);
+        return resolved;
+    };
+}
+
+/**
+ * Build a handler for `FindAlias` or `FindAliasVerbose`.
+ *
+ * `this` is the Method node, so the category searched is the Method's parent —
+ * that is what makes one handler serve every instance of
+ * `AliasNameCategoryType`, including vendor subcategories created through the
+ * `<SubAliasNameCategories>` placeholder.
+ */
+export function makeFindAliasHandler(options: FindAliasBindingOptions, verbose: boolean) {
+    const comparator = options.comparator ?? insertionOrderComparator;
+
+    return async function findAliasHandler(
+        this: UAMethod,
+        inputArguments: Variant[],
+        context: ISessionContext
+    ): Promise<CallMethodResultOptions> {
+        const category = this.parent as UAObject | null;
+        if (!category) {
+            return { statusCode: StatusCodes.BadInternalError };
+        }
+
+        // The gate is consulted per category, and each category at most once per
+        // call. Memoised because a recursive search reaches the same category
+        // through every alias it holds, and the rule may hit a database.
+        const gate = options.isReadAllowed;
+        const decisions = new Map<string, boolean>();
+        const mayRead = async (categoryNodeId: NodeId): Promise<boolean> => {
+            if (!gate) {
+                return true;
+            }
+            const key = categoryNodeId.toString();
+            const cached = decisions.get(key);
+            if (cached !== undefined) {
+                return cached;
+            }
+            const allowed = await gate(context, categoryNodeId);
+            decisions.set(key, allowed);
+            return allowed;
+        };
+
+        // A direct call on a category the caller may not read is
+        // Bad_UserAccessDenied: there is nothing left to filter, so silence
+        // would be a lie rather than a non-disclosure.
+        if (!(await mayRead(category.nodeId))) {
+            return { statusCode: StatusCodes.BadUserAccessDenied };
+        }
+
+        const pattern = readPattern(inputArguments);
+        if (pattern === null) {
+            return { statusCode: StatusCodes.BadInvalidArgument };
+        }
+
+        const query: AliasQuery = {
+            pattern,
+            referenceTypeFilter: readReferenceTypeFilter(inputArguments),
+            categoryNodeId: category.nodeId,
+            maxResults: options.maxResults,
+            // Handed the same memoised closure the filter below uses, so the
+            // rule is evaluated at most once per category per call however many
+            // times it is consulted. Passed only when a gate is configured, so
+            // an ungated Server takes exactly the path it took before.
+            isVisible: gate ? mayRead : undefined
+        };
+
+        let found: AliasEntry[];
+        try {
+            found = await options.store.find(query);
+        } catch (err) {
+            if (err instanceof InvalidLikePatternError) {
+                // clause 6.3.2 Table 4: "The input string is not a valid search string"
+                return { statusCode: StatusCodes.BadInvalidArgument };
+            }
+            throw err;
+        }
+
+        // clause 6.3.2 Table 4: too large to return, "try new filter and repeat find".
+        //
+        // Applied to what the store produced, *before* filtering and merging.
+        // The store stops collecting one entry past the cap, so a count that
+        // reaches it means "there may be more"; reducing the count first would
+        // report a truncated scan as a complete answer. The code names no
+        // category, so it discloses nothing a gated caller should not see.
+        if (found.length > options.maxResults) {
+            return { statusCode: StatusCodes.BadResponseTooLarge };
+        }
+
+        // A nested category the caller may not read is omitted, and the call
+        // still succeeds: an error, or a count that changed, would confirm the
+        // category exists. Absence is the only answer that discloses nothing.
+        //
+        // The store was given the same predicate and should already have skipped
+        // these, so this is normally a no-op. It stays as a backstop: an injected
+        // store written by someone else may ignore `isVisible`, and the cost of
+        // that must be a wasted scan, never a leak.
+        const visible: AliasEntry[] = [];
+        for (const entry of found) {
+            if (await mayRead(entry.categoryNodeId)) {
+                visible.push(entry);
+            }
+        }
+
+        // Filtering happens before the verbose/plain split, so FindAliasVerbose
+        // cannot reveal a ServerUri or an AliasNameCategoryId for a category
+        // that FindAlias would have hidden.
+        const results = verbose ? visible : mergeByAliasName(visible);
+
+        // sort() is stable in modern JavaScript, so a comparator that returns 0
+        // leaves discovery order untouched
+        const ordered = [...results].sort(comparator);
+
+        // No match is Good with an empty AliasNodeList (clause 6.3.2 Table 3),
+        // never an error.
+        const namespaceIndexOf = makeNamespaceResolver(category);
+        const value = verbose
+            ? ordered.map(
+                  (entry) =>
+                      new AliasNameVerboseDataType({
+                          aliasName: { name: entry.aliasName, namespaceIndex: namespaceIndexOf(entry) },
+                          referencedNodes: entry.referencedNodes,
+                          serverUris: entry.serverUris,
+                          aliasNameCategoryId: entry.categoryNodeId
+                      })
+              )
+            : ordered.map(
+                  (entry) =>
+                      new AliasNameDataType({
+                          aliasName: { name: entry.aliasName, namespaceIndex: namespaceIndexOf(entry) },
+                          referencedNodes: entry.referencedNodes
+                      })
+              );
+
+        return {
+            statusCode: StatusCodes.Good,
+            outputArguments: [
+                {
+                    dataType: DataType.ExtensionObject,
+                    arrayType: VariantArrayType.Array,
+                    value
+                }
+            ]
+        };
+    };
+}

package/source/index.ts

@@ -0,0 +1,74 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * Server-side OPC 10000-17 (AliasNames).
+ *
+ * Publishes **this Server's own** AliasNames. Aggregating AliasNames collected
+ * from other Servers (Annex B, Annex C) and the Annex D PubSub change
+ * notification are out of scope.
+ */
+
+export { type AddAliasOptions, AliasNameError, addAlias, findAlias, removeAlias } from "./add_alias.js";
+export { AddressSpaceAliasStore, type AddressSpaceAliasStoreOptions } from "./address_space_alias_store.js";
+export {
+    aliasesOf,
+    collectAllCategories,
+    collectCategories,
+    findAliasNameCategoryType,
+    findAliasNameType,
+    isAliasName,
+    isAliasNameCategory,
+    presentWellKnownCategories
+} from "./alias_hierarchy.js";
+export {
+    ALIAS_NAME_ARCHIVE_VERSION,
+    type AliasNameArchive,
+    readAliasNameArchive,
+    writeAliasNameArchive
+} from "./alias_name_archive.js";
+export {
+    type AddAliasCategoryOptions,
+    addAliasCategory,
+    type BindAliasCategoryOptions,
+    bindAliasCategory,
+    ensureLastChangeProperty,
+    ensureOptionalMethod,
+    findMethodByDeclaration,
+    getInstalledAliasNames,
+    type InstalledAliasNames,
+    removeAliasCategory
+} from "./bind_alias_category.js";
+export {
+    type AliasComparator,
+    type FindAliasBindingOptions,
+    insertionOrderComparator,
+    makeFindAliasHandler
+} from "./bind_find_alias.js";
+export {
+    ALIAS_SERVER_CAPABILITY_ID,
+    advertiseAliasCapability,
+    type CategoryProvider,
+    DEFAULT_MAX_RESULTS,
+    defaultCategoryProvider,
+    type InstallAliasNamesOptions,
+    type InstallAliasNamesResult,
+    type IServerForAliasNames,
+    installAliasNames,
+    installAliasNamesOnAddressSpace
+} from "./install_alias_names.js";
+export {
+    LAST_CHANGE_BROWSE_NAME,
+    LastChangeTracker,
+    type LastChangeTrackerOptions
+} from "./last_change.js";
+export {
+    ALIAS_FOR,
+    ALIAS_NAME_CATEGORY_TYPE,
+    ALIAS_NAME_TYPE,
+    ALIAS_SERVER_CAPABILITY,
+    MethodDeclarations,
+    PUBLISHED_DATA_SET_TYPE,
+    WellKnownCategories,
+    WellKnownLastChange,
+    WellKnownOptionalMethods
+} from "./well_known.js";