node-opcua-alias-name-server 2.176.0

package/source/install_alias_names.ts

@@ -0,0 +1,342 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * Install OPC 10000-17 AliasName support on a Server.
+ *
+ * Every node-opcua Server that loads the standard nodeset already exposes
+ * `Aliases`, `TagVariables` and `Topics`, each carrying a MANDATORY `FindAlias`
+ * Method that is bound to nothing. A conformance tester therefore sees the SDK
+ * advertise the AliasName feature and then fail its only required Method. This
+ * binds them.
+ */
+
+import type { IAddressSpace, ISessionContext, UAObject } from "node-opcua-address-space-base";
+import type { IAliasStore, LikeOptions } from "node-opcua-alias-name-common";
+import type { NodeId } from "node-opcua-nodeid";
+import { AddressSpaceAliasStore } from "./address_space_alias_store.js";
+import { collectAllCategories } from "./alias_hierarchy.js";
+import {
+    type BindAliasCategoryOptions,
+    bindAliasCategory,
+    getInstalledAliasNames,
+    setInstalledAliasNames
+} from "./bind_alias_category.js";
+import type { AliasComparator } from "./bind_find_alias.js";
+import { LastChangeTracker } from "./last_change.js";
+import { DEFAULT_MAX_RESULTS, WellKnownCategories } from "./well_known.js";
+
+export { DEFAULT_MAX_RESULTS };
+
+/**
+ * Supplies the `AliasNameCategoryType` instances to bind.
+ *
+ * Defaults to {@link defaultCategoryProvider}, which walks down from `Aliases`.
+ * Replace it when the category set is not a static tree — one category per
+ * customer, one per upstream Server, categories that appear and disappear at
+ * runtime. May be asynchronous, since the set may have to be fetched.
+ *
+ * A provider only decides *what installation binds*. Categories created after
+ * installation are bound with {@link bindAliasCategory}, or created already
+ * bound with {@link addAliasCategory}.
+ */
+export type CategoryProvider = (addressSpace: IAddressSpace) => UAObject[] | Promise<UAObject[]>;
+
+/**
+ * The default provider: every `AliasNameCategoryType` instance at or below
+ * `Aliases`, plus any roots named in `additionalCategoryRoots`.
+ *
+ * `additionalCategoryRoots` is expressed through this rather than as a parallel
+ * mechanism, so a custom provider can reuse it — `defaultCategoryProvider(roots)`
+ * composes with whatever else the Server knows about.
+ */
+export function defaultCategoryProvider(additionalRoots?: Array<NodeId | UAObject>): CategoryProvider {
+    return (addressSpace: IAddressSpace) => collectAllCategories(addressSpace, additionalRoots);
+}
+
+export interface InstallAliasNamesOptions {
+    /**
+     * Where aliases come from. Defaults to an {@link AddressSpaceAliasStore},
+     * which reads them straight out of the address space — so a Server whose
+     * NodeSet2.xml already models `AliasNameType` instances needs no options at
+     * all.
+     */
+    store?: IAliasStore;
+    /** Result cap per call (clause 6.3.2 Table 4). Defaults to {@link DEFAULT_MAX_RESULTS}. */
+    maxResults?: number;
+    /**
+     * Also bind `FindAliasVerbose` (clause 6.3.3, conformance unit
+     * AliasName FindAliasVerbose). On by default: it costs one extra Method per
+     * category and is what lets a Client see which category held a hit.
+     */
+    verbose?: boolean;
+    /**
+     * Also expose `AddAliasesToCategory` and `DeleteAliasesFromCategory`
+     * (clauses 6.3.4 and 6.3.5, conformance unit *AliasName Configuration
+     * Support*, CU 5874).
+     *
+     * **Off by default**: both Methods are Optional, and a write surface that
+     * appears without being asked for is a surface nobody reviewed. Turning it
+     * on is not by itself dangerous — every call is denied until
+     * {@link isWriteAllowed} says otherwise — but the Methods do become visible
+     * to a browsing Client.
+     */
+    configurationMethods?: boolean;
+    /** Passed to the `Like` matcher used by the default store. */
+    likeOptions?: LikeOptions;
+    /** Result ordering (clause 6.3.2, "best match first"). */
+    comparator?: AliasComparator;
+    /**
+     * Read gate, consulted **per category** and allowed to be asynchronous.
+     * Defaults to allowing everyone, so a Server that simply publishes its
+     * aliases is unaffected.
+     *
+     * A direct call on a denied category answers `Bad_UserAccessDenied`; a
+     * denied category reached by a recursive search is omitted and the call
+     * still returns `Good`, so nothing reveals that it exists.
+     *
+     * OPC 10000-17 defines no security model — four `Bad_UserAccessDenied` rows,
+     * no Security clause, no Roles, and no `RolePermissions` on any Part 17 node
+     * in the standard nodeset — so every Server has to supply its own rule.
+     */
+    isReadAllowed?: (context: ISessionContext, categoryNodeId: NodeId) => boolean | Promise<boolean>;
+    /**
+     * Write gate for the configuration Methods, mirroring
+     * {@link isReadAllowed}. **Defaults to denying everyone**: the write surface
+     * is the one place where a permissive default would be a security defect
+     * rather than a convenience.
+     */
+    isWriteAllowed?: (context: ISessionContext, categoryNodeId: NodeId) => boolean | Promise<boolean>;
+    /**
+     * File backing the persisted `LastChange` values (clause 6.3.1: *"The
+     * LastChange shall be persisted"*).
+     *
+     * Without it, every restart resets `LastChange` to zero — and a Client that
+     * sees a value older than the one it cached is required by clause 6.3.1 to
+     * clear its cache. So an unpersisted Server silently orders every connected
+     * Client to discard a still-valid cache on every restart. Set this on any
+     * Server that Clients cache against.
+     *
+     * The file is small JSON: a version and a map of category NodeId to
+     * VersionTime. Writes are atomic.
+     */
+    persistencePath?: string;
+    /**
+     * Add a `LastChange` Property to every category, not only the `Aliases` root.
+     *
+     * On by default. `LastChange` is Optional on `AliasNameCategoryType` and the
+     * shipped nodeset instantiates it only on the root, which clause 9.2 makes
+     * mandatory — but the clause 6.3.1 rollup is only observable where the
+     * Property exists, so a Client watching one branch needs it there. Turn it
+     * off to keep the address space exactly as the nodeset ships it.
+     */
+    lastChangeOnAllCategories?: boolean;
+    /**
+     * Supplies "now" as a VersionTime, for tests that need to pin it. A
+     * VersionTime has one-second resolution, which is otherwise awkward to
+     * assert against.
+     */
+    nowVersionTime?: () => number;
+    /**
+     * Extra roots to search for `AliasNameCategoryType` instances.
+     *
+     * Categories are discovered by walking down from `Aliases`, which is where
+     * clause 9.1 puts them. Name a category here if the Server models one
+     * outside that hierarchy, otherwise its MANDATORY `FindAlias` stays unbound.
+     *
+     * Ignored when {@link categoryProvider} is supplied — compose it in with
+     * {@link defaultCategoryProvider} instead of passing both.
+     */
+    additionalCategoryRoots?: Array<NodeId | UAObject>;
+    /**
+     * Replace category discovery entirely. See {@link CategoryProvider}.
+     */
+    categoryProvider?: CategoryProvider;
+    /**
+     * Declare the `ALIAS` ServerCapability (OPC 10000-12 Annex D Table D.1).
+     * **On by default.**
+     *
+     * A Server that does not advertise it is never discovered by anything
+     * looking for alias-capable Servers, and nothing reports the failure — so
+     * leaving it to each caller to remember means it will sometimes be
+     * forgotten, invisibly. Installing the feature and declaring it are the same
+     * decision, so they happen together.
+     *
+     * **Call `installAliasNames` before `server.start()`.** The address space
+     * exists from `initialize()` onwards, and mDNS/LDS registration reads the
+     * capability list during `start()` — afterwards the list is still correct
+     * for anything reading `ServerConfiguration`, but the registration has
+     * already gone out without it.
+     *
+     * Set false if the Server manages its own capability list.
+     */
+    advertiseCapability?: boolean;
+}
+
+export interface InstallAliasNamesResult {
+    /** The store that was used — the injected one, or the default. */
+    store: IAliasStore;
+    /** Every `AliasNameCategoryType` instance that had its Methods bound. */
+    categories: NodeId[];
+    /** True when this call did the work; false when AliasNames were already installed. */
+    installed: boolean;
+    /**
+     * Keeps `LastChange` correct across the hierarchy, and persists it
+     * (clause 6.3.1).
+     */
+    lastChange?: LastChangeTracker;
+    /**
+     * The options every category was bound with.
+     *
+     * Pass these to {@link bindAliasCategory} to bind a category created later
+     * exactly as the installed ones were bound, without reassembling them by
+     * hand and risking a different store or result cap.
+     */
+    bindingOptions: BindAliasCategoryOptions;
+}
+
+/** The server-like object we need: the address space, and the capability list. */
+export interface IServerForAliasNames {
+    engine: {
+        addressSpace: IAddressSpace | null;
+    };
+    /**
+     * The Server's OPC 10000-12 Annex D capability identifiers — on an
+     * `OPCUAServer` this is `capabilitiesForMDNS`. Optional so a caller can pass
+     * anything address-space-shaped; when present, `ALIAS` is added to it.
+     */
+    capabilitiesForMDNS?: string[];
+}
+
+/**
+ * The `ALIAS` ServerCapability identifier (OPC 10000-12 Annex D Table D.1).
+ *
+ * Part 17's prose writes it `Alias`; Part 12 Annex D is the normative source and
+ * writes `ALIAS`, matched case-insensitively.
+ */
+export const ALIAS_SERVER_CAPABILITY_ID = "ALIAS";
+
+/** The placeholder node-opcua uses for "no capabilities declared". */
+const NO_CAPABILITY_PLACEHOLDER = "NA";
+
+/**
+ * Add `ALIAS` to a Server's Annex D capability list, in place.
+ *
+ * Idempotent, case-insensitive, and replaces the `NA` placeholder rather than
+ * producing the meaningless `["NA", "ALIAS"]`.
+ *
+ * @returns true when the list was changed.
+ */
+export function advertiseAliasCapability(capabilities: string[]): boolean {
+    if (capabilities.some((c) => c.toUpperCase() === ALIAS_SERVER_CAPABILITY_ID)) {
+        return false;
+    }
+    // "NA" means "none"; it cannot coexist with a real capability
+    const placeholderIndex = capabilities.findIndex((c) => c.toUpperCase() === NO_CAPABILITY_PLACEHOLDER);
+    if (placeholderIndex >= 0) {
+        capabilities.splice(placeholderIndex, 1);
+    }
+    capabilities.push(ALIAS_SERVER_CAPABILITY_ID);
+    return true;
+}
+
+/**
+ * Install AliasName support on a Server.
+ *
+ * Call it **between `initialize()` and `start()`**: the address space exists
+ * from `initialize()`, and the `ALIAS` capability has to be in place before
+ * `start()` performs the mDNS/LDS registration that reads it.
+ *
+ * ```ts
+ * await server.initialize();
+ * await installAliasNames(server);
+ * await server.start();
+ * ```
+ */
+export async function installAliasNames(
+    server: IServerForAliasNames,
+    options?: InstallAliasNamesOptions
+): Promise<InstallAliasNamesResult> {
+    const addressSpace = server.engine.addressSpace;
+    if (!addressSpace) {
+        throw new Error("installAliasNames: address space is not available. Call this after server.initialize().");
+    }
+
+    const result = await installAliasNamesOnAddressSpace(addressSpace, options);
+
+    // Declaring the capability is part of installing the feature, not a separate
+    // thing to remember: a Server that omits it is never discovered, silently.
+    if ((options?.advertiseCapability ?? true) && server.capabilitiesForMDNS) {
+        advertiseAliasCapability(server.capabilitiesForMDNS);
+    }
+    return result;
+}
+
+/**
+ * Install AliasName support directly on an address space.
+ *
+ * The two-tier form used elsewhere in the SDK: this one needs no Server, so it
+ * can be driven from a test or from a tool that only has an address space.
+ */
+export async function installAliasNamesOnAddressSpace(
+    addressSpace: IAddressSpace,
+    options?: InstallAliasNamesOptions
+): Promise<InstallAliasNamesResult> {
+    const already = getInstalledAliasNames(addressSpace);
+    if (already) {
+        return { ...already, installed: false };
+    }
+
+    const aliasesRoot = addressSpace.findNode(WellKnownCategories.Aliases);
+    if (!aliasesRoot) {
+        throw new Error(
+            "installAliasNames: the Aliases Object (i=23470) is not in the address space. " +
+                "Load the standard nodeset (Opc.Ua.NodeSet2.xml) first."
+        );
+    }
+
+    const store = options?.store ?? new AddressSpaceAliasStore(addressSpace, { likeOptions: options?.likeOptions });
+
+    const lastChange = new LastChangeTracker(addressSpace, {
+        persistencePath: options?.persistencePath,
+        now: options?.nowVersionTime
+    });
+
+    const bindingOptions: BindAliasCategoryOptions = {
+        store,
+        maxResults: options?.maxResults ?? DEFAULT_MAX_RESULTS,
+        verbose: options?.verbose ?? true,
+        comparator: options?.comparator,
+        isReadAllowed: options?.isReadAllowed,
+        isWriteAllowed: options?.isWriteAllowed,
+        lastChangeProperty: options?.lastChangeOnAllCategories ?? true,
+        configurationMethods: options?.configurationMethods ?? false,
+        onChanged: (categoryNodeId: NodeId) => lastChange.touch(categoryNodeId).then(() => undefined)
+    };
+
+    const provider = options?.categoryProvider ?? defaultCategoryProvider(options?.additionalCategoryRoots);
+    const categories = await provider(addressSpace);
+
+    // one binding path, shared with bindAliasCategory, so a category created
+    // after installation cannot end up bound differently
+    for (const category of categories) {
+        bindAliasCategory(addressSpace, category, bindingOptions);
+    }
+
+    const installed = {
+        store,
+        categories: categories.map((c) => c.nodeId),
+        bindingOptions,
+        lastChange
+    };
+    // Recorded before restore, so anything the restore triggers can already find
+    // the tracker on the address space.
+    setInstalledAliasNames(addressSpace, installed);
+
+    // Bring persisted values back and publish them, including the zeros for
+    // categories that have never changed - a Property with no value at all reads
+    // as Bad_WaitingForInitialData rather than "nothing has happened yet".
+    await lastChange.restore();
+    lastChange.publishAll(installed.categories);
+
+    return { ...installed, installed: true };
+}

package/source/last_change.ts

@@ -0,0 +1,201 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * `LastChange` (OPC 10000-17 clause 6.3.1).
+ *
+ * A `VersionTime` — **a UInt32 count of seconds since 2000-01-01T00:00:00Z, not
+ * a DateTime**. Every other "last changed" Property in the SDK is a DateTime and
+ * the name gives no hint, which is what makes this the easiest thing here to get
+ * wrong.
+ *
+ * Clause 6.3.1 lists three things that move it:
+ *
+ * - an AliasName was added to or deleted from the category,
+ * - an AliasNameCategory was added or deleted,
+ * - the referenced Nodes of an AliasName in the category changed.
+ *
+ * and one rule that makes it a tree rather than a set of independent counters:
+ * *"For AliasNameCategoryType instances that are nested, the value of LastChange
+ * shall always be the latest VersionTime of all Organized AliasNames and
+ * AliasNameCategories."* So a change deep in the hierarchy moves every ancestor
+ * up to the root.
+ *
+ * ## One second of resolution
+ *
+ * Two changes inside the same second are indistinguishable — the value simply
+ * does not move. A Client must therefore treat an **equal** `LastChange` as
+ * "re-browse to be sure" rather than "nothing changed"; only a value *older*
+ * than the cached one carries the strong meaning clause 6.3.1 gives it, namely
+ * clear the cache. This is a property of `VersionTime`, not of this
+ * implementation, and there is nothing a Server can do about it.
+ */
+
+import type { BaseNode, IAddressSpace, UAObject, UAVariable } from "node-opcua-address-space-base";
+import { maxVersionTime, nowVersionTime } from "node-opcua-alias-name-common";
+import { BrowseDirection, NodeClass } from "node-opcua-data-model";
+import type { NodeId } from "node-opcua-nodeid";
+import { DataType } from "node-opcua-variant";
+import {
+    ALIAS_NAME_ARCHIVE_VERSION,
+    type AliasNameArchive,
+    readAliasNameArchive,
+    writeAliasNameArchive
+} from "./alias_name_archive.js";
+import { WellKnownCategories } from "./well_known.js";
+
+/** BrowseName of the Property, per clause 6.3.1 Table 2. */
+export const LAST_CHANGE_BROWSE_NAME = "LastChange";
+
+export interface LastChangeTrackerOptions {
+    /** File backing the persisted values. Omit to keep them in memory only. */
+    persistencePath?: string;
+    /**
+     * Supplies "now" as a VersionTime. Injectable so a test can pin it; a
+     * one-second resolution is otherwise painful to assert against.
+     */
+    now?: () => number;
+}
+
+/**
+ * Keeps every category's `LastChange` Property correct, including the rollup to
+ * ancestors, and persists the values across restart.
+ */
+export class LastChangeTracker {
+    private readonly addressSpace: IAddressSpace;
+    private readonly persistencePath?: string;
+    private readonly now: () => number;
+    /** Category NodeId string to VersionTime. */
+    private readonly values = new Map<string, number>();
+    /** Serialises saves so two rapid changes cannot interleave their writes. */
+    private savingChain: Promise<void> = Promise.resolve();
+
+    constructor(addressSpace: IAddressSpace, options?: LastChangeTrackerOptions) {
+        this.addressSpace = addressSpace;
+        this.persistencePath = options?.persistencePath;
+        this.now = options?.now ?? nowVersionTime;
+    }
+
+    /** The `VersionTime` currently recorded for a category. */
+    public get(categoryNodeId: NodeId): number {
+        return this.values.get(categoryNodeId.toString()) ?? 0;
+    }
+
+    /**
+     * Record that a category changed, and roll the change up to every ancestor.
+     *
+     * Ancestors are walked at write time rather than computed at read time, so
+     * the Property a Client subscribes to actually carries the value — a
+     * rollup that existed only inside the Server would be invisible on the
+     * wire, which is the whole point of the Property.
+     */
+    public async touch(categoryNodeId: NodeId, versionTime?: number): Promise<number> {
+        const value = versionTime ?? this.now();
+        for (const nodeId of this.selfAndAncestors(categoryNodeId)) {
+            const key = nodeId.toString();
+            this.values.set(key, maxVersionTime(this.values.get(key) ?? 0, value));
+            this.writeProperty(nodeId);
+        }
+        await this.save();
+        return value;
+    }
+
+    /** Restore persisted values and publish them to the address space. */
+    public async restore(): Promise<void> {
+        if (this.persistencePath) {
+            const archive = await readAliasNameArchive(this.persistencePath);
+            if (archive) {
+                for (const [key, value] of Object.entries(archive.lastChange)) {
+                    this.values.set(key, value);
+                }
+            }
+        }
+        for (const key of this.values.keys()) {
+            const node = this.addressSpace.findNode(key);
+            if (node) {
+                this.writeProperty(node.nodeId);
+            }
+        }
+    }
+
+    /** Publish the current value of every known category, including zeros. */
+    public publishAll(categoryNodeIds: NodeId[]): void {
+        for (const nodeId of categoryNodeIds) {
+            this.writeProperty(nodeId);
+        }
+    }
+
+    /** Snapshot for persistence or inspection. */
+    public snapshot(): Record<string, number> {
+        return Object.fromEntries(this.values.entries());
+    }
+
+    /** Persist, if a path was given. Saves are serialised, never concurrent. */
+    public async save(): Promise<void> {
+        if (!this.persistencePath) {
+            return;
+        }
+        const path = this.persistencePath;
+        const archive: AliasNameArchive = { version: ALIAS_NAME_ARCHIVE_VERSION, lastChange: this.snapshot() };
+        this.savingChain = this.savingChain.then(() => writeAliasNameArchive(path, archive));
+        await this.savingChain;
+    }
+
+    /** Write the value onto the category's `LastChange` Property, if it has one. */
+    private writeProperty(categoryNodeId: NodeId): void {
+        const node = this.addressSpace.findNode(categoryNodeId);
+        if (!node || node.nodeClass !== NodeClass.Object) {
+            return;
+        }
+        const property = (node as UAObject).getPropertyByName(LAST_CHANGE_BROWSE_NAME);
+        if (!property) {
+            // LastChange is Optional on AliasNameCategoryType; a category
+            // without one simply does not publish its version
+            return;
+        }
+        // VersionTime (i=20998) is a UInt32 subtype - not a DateTime
+        (property as UAVariable).setValueFromSource({
+            dataType: DataType.UInt32,
+            value: this.values.get(categoryNodeId.toString()) ?? 0
+        });
+    }
+
+    /**
+     * The category itself, then every `AliasNameCategoryType` ancestor up to and
+     * including the `Aliases` root.
+     *
+     * Cycle-safe: an address space that nests categories in a loop would
+     * otherwise hang the Method call that triggered the change.
+     */
+    private selfAndAncestors(categoryNodeId: NodeId): NodeId[] {
+        const result: NodeId[] = [];
+        const seen = new Set<string>();
+
+        const visit = (nodeId: NodeId): void => {
+            const key = nodeId.toString();
+            if (seen.has(key)) {
+                return;
+            }
+            seen.add(key);
+            result.push(nodeId);
+
+            const node = this.addressSpace.findNode(nodeId);
+            if (!node) {
+                return;
+            }
+            for (const parent of (node as BaseNode).findReferencesExAsObject("HierarchicalReferences", BrowseDirection.Inverse)) {
+                if (parent.nodeClass === NodeClass.Object) {
+                    visit(parent.nodeId);
+                }
+            }
+        };
+
+        visit(categoryNodeId);
+        // the root is always included even when the category was reached by a
+        // path that does not pass through it
+        const rootKey = WellKnownCategories.Aliases.toString();
+        if (!seen.has(rootKey) && this.addressSpace.findNode(WellKnownCategories.Aliases)) {
+            result.push(WellKnownCategories.Aliases);
+        }
+        return result;
+    }
+}

package/source/well_known.ts

@@ -0,0 +1,101 @@
+/**
+ * @module node-opcua-alias-name-server
+ *
+ * The fixed NodeIds of OPC 10000-17.
+ *
+ * Every well-known instance is resolved **by NodeId**, never by walking
+ * BrowseNames. Clause 9.1 gives these Objects static NodeIds precisely so they
+ * can be found without browsing, and a BrowseName walk would break on a Server
+ * that publishes the hierarchy under a localised DisplayName or that has a
+ * vendor Object of the same BrowseName elsewhere.
+ */
+
+import { DataTypeIds, MethodIds, ObjectIds, ObjectTypeIds, ReferenceTypeIds, VariableIds } from "node-opcua-constants";
+import { type NodeId, resolveNodeId } from "node-opcua-nodeid";
+
+/**
+ * Default result cap; beyond it a call answers `Bad_ResponseTooLarge`
+ * (clause 6.3.2 Table 4).
+ *
+ * Lives here rather than in `install_alias_names` so that `bind_alias_category`
+ * can use it without the two importing each other.
+ */
+export const DEFAULT_MAX_RESULTS = 1000;
+
+/** `AliasNameType` ObjectType (clause 6.2). */
+export const ALIAS_NAME_TYPE: NodeId = resolveNodeId(ObjectTypeIds.AliasNameType);
+
+/** `AliasNameCategoryType` ObjectType (clause 6.3). */
+export const ALIAS_NAME_CATEGORY_TYPE: NodeId = resolveNodeId(ObjectTypeIds.AliasNameCategoryType);
+
+/** `VersionTime` DataType (OPC 10000-4 clause 7.43) - a UInt32 subtype. */
+export const VERSION_TIME_DATA_TYPE: NodeId = resolveNodeId(DataTypeIds.VersionTime);
+
+/** `AliasFor` ReferenceType (clause 8.2); the default link to a target Node. */
+export const ALIAS_FOR: NodeId = resolveNodeId(ReferenceTypeIds.AliasFor);
+
+/** `PublishedDataSetType` (OPC 10000-14), the target type `Topics` restricts to. */
+export const PUBLISHED_DATA_SET_TYPE: NodeId = resolveNodeId(ObjectTypeIds.PublishedDataSetType);
+
+/** The three well-known category instances of clauses 9.2, 9.3 and 9.4. */
+export const WellKnownCategories = {
+    /** `Aliases`, the root of the hierarchy (clause 9.2). */
+    Aliases: resolveNodeId(ObjectIds.Aliases),
+    /** `TagVariables`; targets restricted to Variables (clause 9.3). */
+    TagVariables: resolveNodeId(ObjectIds.TagVariables),
+    /** `Topics`; targets restricted to PublishedDataSetType (clause 9.4). */
+    Topics: resolveNodeId(ObjectIds.Topics)
+} as const;
+
+/** `LastChange` on each well-known category (clause 6.3.1). */
+export const WellKnownLastChange = {
+    Aliases: resolveNodeId(VariableIds.Aliases_LastChange),
+    TagVariables: resolveNodeId(VariableIds.TagVariables_LastChange),
+    Topics: resolveNodeId(VariableIds.Topics_LastChange)
+} as const;
+
+/** The Method declarations on `AliasNameCategoryType`. */
+export const MethodDeclarations = {
+    FindAlias: resolveNodeId(MethodIds.AliasNameCategoryType_FindAlias),
+    FindAliasVerbose: resolveNodeId(MethodIds.AliasNameCategoryType_FindAliasVerbose),
+    AddAliasesToCategory: resolveNodeId(MethodIds.AliasNameCategoryType_AddAliasesToCategory),
+    DeleteAliasesFromCategory: resolveNodeId(MethodIds.AliasNameCategoryType_DeleteAliasesFromCategory)
+} as const;
+
+/**
+ * The NodeIds OPC 10000-17 reserves for the *optional* Methods on the three
+ * well-known categories.
+ *
+ * The shipped `Opc.Ua.NodeSet2.xml` declares these Methods on
+ * `AliasNameCategoryType` but does not instantiate them on `Aliases`,
+ * `TagVariables` or `Topics` — yet upstream still assigns them fixed NodeIds.
+ * When installation adds them it uses these rather than server-assigned ones,
+ * so an aggregating Server sees the standard NodeId it expects.
+ */
+export const WellKnownOptionalMethods = {
+    Aliases: {
+        FindAliasVerbose: resolveNodeId(MethodIds.Aliases_FindAliasVerbose),
+        AddAliasesToCategory: resolveNodeId(MethodIds.Aliases_AddAliasesToCategory),
+        DeleteAliasesFromCategory: resolveNodeId(MethodIds.Aliases_DeleteAliasesFromCategory)
+    },
+    TagVariables: {
+        FindAliasVerbose: resolveNodeId(MethodIds.TagVariables_FindAliasVerbose),
+        AddAliasesToCategory: resolveNodeId(MethodIds.TagVariables_AddAliasesToCategory),
+        DeleteAliasesFromCategory: resolveNodeId(MethodIds.TagVariables_DeleteAliasesFromCategory)
+    },
+    Topics: {
+        FindAliasVerbose: resolveNodeId(MethodIds.Topics_FindAliasVerbose),
+        AddAliasesToCategory: resolveNodeId(MethodIds.Topics_AddAliasesToCategory),
+        DeleteAliasesFromCategory: resolveNodeId(MethodIds.Topics_DeleteAliasesFromCategory)
+    }
+} as const;
+
+/**
+ * The `ALIAS` ServerCapability identifier (OPC 10000-12 Annex D Table D.1).
+ *
+ * A Server that does not advertise this will never be found by anything looking
+ * for alias-capable Servers, and nothing reports that failure. Part 17's prose
+ * writes it `Alias`; Part 12 Annex D is the normative source and writes `ALIAS`,
+ * matched case-insensitively.
+ */
+export const ALIAS_SERVER_CAPABILITY = "ALIAS";