homematic-manager 3.0.0-beta.18 → 3.0.0-beta.19

package/README.md

@@ -63,7 +63,7 @@ hard-coding it.
 | `--issue-cookie` | loopback binds only | hand the token to the browser on the page load |
 | `-a, --ccu` | - | CCU address; written to the configuration when it differs |
 | `--local` | - | we run on the CCU itself: talk to the interface processes directly |
-| `--callback-ip` | auto | address the interfaces call back to; needed where this host cannot see it (Docker) |
+| `--callback-ip` | auto | address the interfaces call back to; needed where this host cannot see it (Docker). Auto is this host's address in the CCU's network, else the one on the route to the CCU |
 | `--callback-xmlrpc-port`, `--callback-binrpc-port` | free ports | fixed callback ports, so a container can publish them |
 | `--callback-xmlrpc-default-port`, `--callback-binrpc-default-port` | - | callback ports while the configured ones are 0, a free port when one is taken (the CCU addon: 2031, 2032; never written to the configuration) |
 | `--demo` | off | serve the UI on its demo fixture and start no backend |

package/node_modules/@homematic-manager/backend/dist/api/backend.d.ts

@@ -20,6 +20,7 @@ import { InterfaceManager, type InterfaceManagerOptions } from '../interfaces/ma
 import { type MetaServiceOptions } from '../meta/service.js';
 import { RegaService, type RegaServiceOptions } from '../rega/client.js';
 import { ApiEventEmitter } from '../util/emitter.js';
+import { type CallbackNetwork } from '../util/net.js';
 /** How often the BidCos service messages are polled while the connection is up. */
 export declare const SERVICE_MESSAGE_POLL_MS = 300000;
 /** How long the HmIP `getParamset(:0, VALUES)` sweep waits for the device list to settle. */
@@ -45,6 +46,11 @@ export interface BackendOptions extends Omit<ConfigStoreOptions, 'version'> {
      * popup to say that the callback ports must be published unchanged.
      */
     readonly inContainer?: boolean;
+    /**
+     * B-53: the interfaces, name lookup and route probe the automatic callback address comes from.
+     * Absent, the machine's own - or, where `localAddresses` is injected, that list alone.
+     */
+    readonly network?: CallbackNetwork;
     readonly rpcTimeoutMs?: number;
     readonly watchdogIntervalMs?: number;
     readonly serviceMessagePollMs?: number;

package/node_modules/@homematic-manager/backend/dist/api/backend.js

@@ -28,6 +28,7 @@ import { MetaService } from '../meta/service.js';
 import { RegaService } from '../rega/client.js';
 import { listDevicesAnswer } from '../rpc/server.js';
 import { ApiEventEmitter } from '../util/emitter.js';
+import { describeCallbackAddresses, staticNetwork, systemNetwork } from '../util/net.js';
 import { RpcLog, isWriteMethod } from '../rpc/log.js';
 import { currentOrigin, runWithOrigin } from '../rpc/origin.js';
 import { ParamsetWriter } from '../write/paramset.js';
@@ -307,6 +308,8 @@ export class Backend {
                 return this.#discover();
             case 'config.clearCaches':
                 return this.#clearCaches();
+            case 'config.callbackAddresses':
+                return this.#callbackAddresses(p[0]);
             case 'interfaces.list':
                 return this.#manager?.states() ?? [];
             case 'interfaces.reconnect':
@@ -533,6 +536,8 @@ export class Backend {
                 ? {}
                 : { watchdogIntervalMs: this.#options.watchdogIntervalMs }),
             ...(this.#options.localAddresses === undefined ? {} : { localAddresses: this.#options.localAddresses }),
+            ...(this.#options.network === undefined ? {} : { network: this.#options.network }),
+            ...(this.#keepsConfiguredCallbackIp() ? { keepConfiguredCallbackIp: true } : {}),
             ...(this.#options.now === undefined ? {} : { now: this.#options.now }),
             ...this.#options.interfaceManagerOptions,
         });
@@ -956,6 +961,27 @@ export class Backend {
             }
         }
     }
+    /**
+     * B-53: a callback address set at start (task 38) or inside a container is taken as it is - the
+     * Docker host's address is none of the container's, and it is still the right one.
+     */
+    #keepsConfiguredCallbackIp() {
+        return this.#options.inContainer === true || this.#config.callbackPins?.ip === true;
+    }
+    #network() {
+        if (this.#options.network !== undefined) {
+            return this.#options.network;
+        }
+        const injected = this.#options.localAddresses;
+        return injected === undefined ? systemNetwork() : staticNetwork(injected);
+    }
+    /** B-53: `config.callbackAddresses` - for the host being typed, or the configured one. */
+    async #callbackAddresses(host) {
+        const { connection } = this.#config;
+        const target = typeof host === 'string' ? host.trim() : connection.host;
+        const info = await describeCallbackAddresses(target, this.#network(), connection.local === true);
+        return this.#keepsConfiguredCallbackIp() ? { ...info, keepsConfigured: true } : info;
+    }
     async #discover() {
         const discover = this.#options.discover ?? ((options) => discoverCcus(options));
         const found = await discover({ tls: this.#config.connection.tls });
@@ -1579,6 +1605,7 @@ export const API_METHOD_NAMES = [
     'config.set',
     'config.discover',
     'config.clearCaches',
+    'config.callbackAddresses',
     'interfaces.list',
     'interfaces.reconnect',
     'rega.state',

package/node_modules/@homematic-manager/backend/dist/interfaces/manager.d.ts

@@ -19,11 +19,11 @@
  * dialog. 2.x probed six ports with a 5 s timeout each before the window became usable, which is
  * the root of the "endless loading" issues #121, #126, #128 and #134.
  */
-import type { CallbackPins, ConnectionConfig, InterfaceState, ResolvedInterface } from '@homematic-manager/core';
+import type { CallbackPins, CallbackWarning, ConnectionConfig, InterfaceState, ResolvedInterface } from '@homematic-manager/core';
 import { type InterfaceTarget } from '../config/defaults.js';
 import { RpcClient, type RpcCallRecord, type RpcClientOptions } from '../rpc/client.js';
 import { type CallbackHandler, type CallbackServerSet } from '../rpc/server.js';
-import { type PortProbe } from '../util/net.js';
+import { type CallbackNetwork, type PortProbe } from '../util/net.js';
 /** How often the watchdog looks at every interface. 2.x used the same 15 s. */
 export declare const WATCHDOG_INTERVAL_MS = 15000;
 /** Where an interface process on this very box calls back (#144). */
@@ -95,8 +95,20 @@ export interface InterfaceManagerOptions {
     readonly createClient?: (options: RpcClientOptions) => RpcClient;
     readonly createCallbackServers?: (handler: CallbackHandler) => CallbackServerSet;
     readonly probe?: (host: string, port: number) => Promise<PortProbe>;
-    /** Injected for the callback address; defaults to this machine's IPv4 addresses. */
+    /**
+     * Injected for the callback address; defaults to this machine's IPv4 addresses. A list given
+     * here has no netmasks, so the automatic choice is its first entry (or the loopback for a CCU
+     * on the loopback) unless {@link network} is given as well.
+     */
     readonly localAddresses?: () => string[];
+    /** B-53: the interfaces, name lookup and route probe the automatic callback address is worked out from. */
+    readonly network?: CallbackNetwork;
+    /**
+     * B-53: take a set callback address as it is, even when it is no address of this machine - the
+     * host set it at start (task 38) or runs in a container, where the Docker host's address is the
+     * one that works. No fallback and no warning then.
+     */
+    readonly keepConfiguredCallbackIp?: boolean;
     /**
      * Overrides the port of one interface, for a process that does not sit on the well-known one:
      * the integration tests point at an hm-simulator on an ephemeral port, and an unusual proxy
@@ -134,8 +146,14 @@ export declare class InterfaceManager {
      * one address that changes - a new lease, another network - while `init` registrations survive
      * such a change in the interface process's handler list, and every other local subscriber on a
      * CCU registers on the loopback, which is what a look at that list expects to see.
+     *
+     * B-53 (#162, #165): with no address set, the one in the CCU's network, else the one the route
+     * to the CCU leaves from, else the first one that is not link-local - worked out again at every
+     * `init`. Until the first `init` this is the same choice without the name lookup and the route.
      */
     get callbackIp(): string;
+    /** B-53: the callback address set in the settings that does not fit, as of the last connect. */
+    get callbackWarning(): CallbackWarning | undefined;
     /** D-31: are the subscriptions currently dropped because nobody is looking? */
     get idle(): boolean;
     /** The interfaces whose ports answered the last background probe. */

package/node_modules/@homematic-manager/backend/dist/interfaces/manager.js

@@ -24,7 +24,7 @@ import { configError, connectionError, errorMessage, isAddressInUse, isConnectio
 import { interfaceTargets } from '../config/defaults.js';
 import { RpcClient } from '../rpc/client.js';
 import { CallbackServers } from '../rpc/server.js';
-import { localIPv4Addresses, probePortState, withTimeout } from '../util/net.js';
+import { describeCallbackAddresses, ipv4ToNumber, localIPv4Addresses, pickCallbackAddress, probePortState, staticNetwork, systemNetwork, withTimeout, } from '../util/net.js';
 /** How often the watchdog looks at every interface. 2.x used the same 15 s. */
 export const WATCHDOG_INTERVAL_MS = 15_000;
 /**
@@ -96,6 +96,11 @@ export class InterfaceManager {
     #callbackFailures = new Map();
     #reopening = new Map();
     #watchdog;
+    /** B-53: the callback address of the last connect, and what did not fit about the configured one. */
+    #callback;
+    #callbackRefresh;
+    /** B-53: the warning last logged, so a watchdog round does not log it again. */
+    #callbackNoted = '';
     #detected = [];
     #stopping = false;
     #idle = false;
@@ -132,17 +137,107 @@ export class InterfaceManager {
      * one address that changes - a new lease, another network - while `init` registrations survive
      * such a change in the interface process's handler list, and every other local subscriber on a
      * CCU registers on the loopback, which is what a look at that list expects to see.
+     *
+     * B-53 (#162, #165): with no address set, the one in the CCU's network, else the one the route
+     * to the CCU leaves from, else the first one that is not link-local - worked out again at every
+     * `init`. Until the first `init` this is the same choice without the name lookup and the route.
      */
     get callbackIp() {
-        const configured = this.#options.connection.callback.ip;
-        if (configured !== '') {
-            return configured;
+        return this.#callback?.ip ?? this.#immediateCallbackIp();
+    }
+    /** B-53: the callback address set in the settings that does not fit, as of the last connect. */
+    get callbackWarning() {
+        return this.#callback?.warning;
+    }
+    /** Read through a method, so that the check after an `await` is not narrowed away. */
+    #hasStopped() {
+        return this.#stopping;
+    }
+    #network() {
+        if (this.#options.network !== undefined) {
+            return this.#options.network;
         }
-        if (this.#options.connection.local === true) {
+        const injected = this.#options.localAddresses;
+        return injected === undefined ? systemNetwork() : staticNetwork(injected);
+    }
+    #immediateCallbackIp() {
+        const { host, local, callback } = this.#options.connection;
+        if (callback.ip !== '') {
+            return callback.ip;
+        }
+        if (local === true) {
             return LOOPBACK_IP;
         }
-        const addresses = (this.#options.localAddresses ?? (() => localIPv4Addresses()))();
-        return addresses[0] ?? LOOPBACK_IP;
+        const literal = ipv4ToNumber(host) === undefined ? undefined : host;
+        return pickCallbackAddress(host, literal, this.#network().interfaces(), undefined).auto.address;
+    }
+    /** B-53: works the callback address out once for every `init` that runs at the same time. */
+    #refreshCallback() {
+        this.#callbackRefresh ??= this.#resolveCallback().finally(() => {
+            this.#callbackRefresh = undefined;
+        });
+        return this.#callbackRefresh;
+    }
+    async #resolveCallback() {
+        const { host, local, callback } = this.#options.connection;
+        const configured = callback.ip;
+        let result;
+        if (local === true) {
+            // the addon: the loopback, or what was set - nothing on the CCU itself is second-guessed
+            result = { ip: configured === '' ? LOOPBACK_IP : configured };
+        }
+        else if (configured !== '' &&
+            (this.#options.keepConfiguredCallbackIp === true || configured === LOOPBACK_IP)) {
+            result = { ip: configured };
+        }
+        else {
+            let info;
+            try {
+                info = await describeCallbackAddresses(host, this.#network());
+            }
+            catch {
+                // the lookups never reject; an interface list that throws leaves the old rule
+                info = undefined;
+            }
+            if (info === undefined) {
+                result = { ip: configured === '' ? (localIPv4Addresses()[0] ?? LOOPBACK_IP) : configured };
+            }
+            else if (configured === '') {
+                result = { ip: info.auto.address };
+            }
+            else {
+                const candidate = info.addresses.find((entry) => entry.address === configured);
+                const auto = info.auto.address;
+                if (candidate === undefined) {
+                    result = { ip: auto, warning: { address: configured, reason: 'notLocal', auto } };
+                }
+                else if (info.hostAddress !== undefined && !candidate.inSubnet && configured !== auto) {
+                    result = { ip: configured, warning: { address: configured, reason: 'otherNetwork', auto } };
+                }
+                else {
+                    result = { ip: configured };
+                }
+            }
+        }
+        this.#callback = result;
+        this.#noteCallbackWarning(result.warning);
+        return result;
+    }
+    /** B-53: a warning is logged when it appears or changes, not at every watchdog `init`. */
+    #noteCallbackWarning(warning) {
+        const key = warning === undefined ? '' : `${warning.reason} ${warning.address} ${warning.auto}`;
+        if (key === this.#callbackNoted) {
+            return;
+        }
+        this.#callbackNoted = key;
+        if (warning === undefined) {
+            return;
+        }
+        this.#options.onNotice('warn', warning.reason === 'notLocal'
+            ? `callback address ${warning.address} from the settings is no address of this machine any more - ` +
+                `the automatic address ${warning.auto} is used instead; choose "Automatic" in the settings to keep it that way`
+            : `callback address ${warning.address} from the settings is not in the CCU's network - ` +
+                `the CCU may not reach it and send no events; the automatic address would be ${warning.auto}`);
     }
     /** D-31: are the subscriptions currently dropped because nobody is looking? */
     get idle() {
@@ -401,7 +496,8 @@ export class InterfaceManager {
         if (!entry.target.resolved.init || this.#callbackFailures.has(entry.target.resolved.protocol)) {
             return;
         }
-        const url = this.#callbackUrl(entry.target.resolved.protocol);
+        // the URL it was registered with: the automatic address may have moved since (B-53)
+        const url = entry.state.callbackUrl ?? this.#callbackUrl(entry.target.resolved.protocol);
         try {
             await withTimeout(entry.client.call('init', [url, ''], BACKGROUND), SHUTDOWN_TIMEOUT_MS, () => connectionError(`${entry.name}: de-registering timed out`));
         }
@@ -522,8 +618,13 @@ export class InterfaceManager {
             this.#noteNoCallbackServer(entry, this.#callbackFailures.get(resolved.protocol) ?? failure);
             return;
         }
-        const url = this.#callbackUrl(resolved.protocol);
-        this.#update(entry, { callbackUrl: url, callbackFailure: undefined });
+        const callback = await this.#refreshCallback();
+        // a name lookup may take seconds; a manager stopped meanwhile subscribes nothing any more
+        if (this.#hasStopped()) {
+            return;
+        }
+        const url = this.#servers.callbackUrl(resolved.protocol, callback.ip);
+        this.#update(entry, { callbackUrl: url, callbackFailure: undefined, callbackWarning: callback.warning });
         try {
             await entry.client.call('init', [url, resolved.ident], BACKGROUND);
             entry.lastEvent = this.#now();
@@ -627,6 +728,14 @@ export class InterfaceManager {
                 state.callbackFailure = changes.callbackFailure;
             }
         }
+        if ('callbackWarning' in changes) {
+            if (changes.callbackWarning === undefined) {
+                delete state.callbackWarning;
+            }
+            else {
+                state.callbackWarning = { ...changes.callbackWarning };
+            }
+        }
         entry.state = state;
     }
     #startWatchdog() {

package/node_modules/@homematic-manager/backend/dist/util/net.d.ts

@@ -7,8 +7,11 @@
  * 5 s timeout each before the window became usable) and it destroys the socket instead of leaving
  * it to time out.
  */
+import dgram from 'node:dgram';
+import dns from 'node:dns';
 import net from 'node:net';
 import os from 'node:os';
+import type { CallbackAddressInfo } from '@homematic-manager/core';
 /**
  * Every non-internal IPv4 address of this machine, then `127.0.0.1`; candidates for the callback
  * address. The loopback comes last so nothing that picked "the first candidate" changes - but it
@@ -17,6 +20,70 @@ import os from 'node:os';
  * can call back (openccu-lite task 28.10, maintainer 2026-09-08).
  */
 export declare function localIPv4Addresses(interfaces?: () => NodeJS.Dict<os.NetworkInterfaceInfo[]>): string[];
+/** One IPv4 address of this machine; `netmask` is absent where it is not known (an injected list). */
+export interface LocalIPv4 {
+    readonly address: string;
+    readonly netmask?: string;
+}
+/**
+ * B-53: every non-internal IPv4 address of this machine with its netmask, in the order
+ * `os.networkInterfaces()` gives them - the loopback is not in it.
+ */
+export declare function localIPv4Interfaces(interfaces?: () => NodeJS.Dict<os.NetworkInterfaceInfo[]>): LocalIPv4[];
+/** A dotted IPv4 address as a number; `undefined` for anything else. */
+export declare function ipv4ToNumber(address: string): number | undefined;
+/** True when `target` is in the network of `address/netmask`. False when any of them is no IPv4 address. */
+export declare function inSubnet(address: string, netmask: string, target: string): boolean;
+/** `169.254.0.0/16`, the address an interface gives itself when no DHCP server answered. */
+export declare function isLinkLocal(address: string): boolean;
+/** `127.0.0.0/8`. */
+export declare function isLoopback(address: string): boolean;
+/**
+ * B-53: what the automatic callback address is worked out from. Injected by the tests, so that no
+ * unit test depends on the network of the machine it runs on.
+ */
+export interface CallbackNetwork {
+    /** This machine's non-internal IPv4 addresses, see {@link localIPv4Interfaces}. */
+    readonly interfaces: () => LocalIPv4[];
+    /** The CCU host's IPv4 address; `undefined` when it does not resolve. Never rejects. */
+    readonly resolve: (host: string) => Promise<string | undefined>;
+    /** The local address the operating system sends from towards `address`; `undefined` when there is no route. Never rejects. */
+    readonly route: (address: string) => Promise<string | undefined>;
+}
+/** How long a name lookup for the callback address may take before the first address is used. */
+export declare const RESOLVE_TIMEOUT_MS = 3000;
+/** The CCU host's IPv4 address, through the system resolver (`/etc/hosts`, mDNS where the OS has it). */
+export declare function resolveIPv4(host: string, lookup?: typeof dns.promises.lookup): Promise<string | undefined>;
+/**
+ * The local address a UDP socket gets when it is `connect()`ed to `address`: the source address of
+ * the route the operating system would take. `connect` on a datagram socket only sets the default
+ * peer - no packet is sent - so this works for a CCU behind a router or a VPN as well as for one in
+ * the same network.
+ */
+export declare function routeSource(address: string, createSocket?: typeof dgram.createSocket): Promise<string | undefined>;
+/** The machine's own network, as the running host sees it. */
+export declare function systemNetwork(): CallbackNetwork;
+/**
+ * A network made of a fixed address list, for a caller that injects `localAddresses` (the tests and
+ * the e2e hosts): no netmasks, no name lookup beyond an address literal, no route.
+ */
+export declare function staticNetwork(addresses: () => string[]): CallbackNetwork;
+/**
+ * B-53 (#162, #165): the automatic callback address, and every address with whether it is in the
+ * CCU's network. Synchronous: `hostAddress` and `routed` are what {@link describeCallbackAddresses}
+ * found out, and `undefined` when nothing could be.
+ *
+ * The order: the CCU on the loopback (or `local`) is called back on the loopback; then the
+ * address in the CCU's network; then the route's source address; then the first address that is
+ * not link-local. A link-local address wins only as the CCU's own network, and the loopback is
+ * never chosen for a CCU elsewhere unless this machine has no other address at all.
+ */
+export declare function pickCallbackAddress(host: string, hostAddress: string | undefined, interfaces: readonly LocalIPv4[], routed: string | undefined, local?: boolean): CallbackAddressInfo;
+/**
+ * B-53: {@link pickCallbackAddress} with the facts looked up - the CCU's name resolved, and the route
+ * asked for only when no address shares the CCU's network. Never rejects.
+ */
+export declare function describeCallbackAddresses(host: string, network: CallbackNetwork, local?: boolean): Promise<CallbackAddressInfo>;
 export interface ProbeOptions {
     readonly timeoutMs?: number;
     /** Injected for the tests; defaults to `net.connect`. */

package/node_modules/@homematic-manager/backend/dist/util/net.js

@@ -7,6 +7,8 @@
  * 5 s timeout each before the window became usable) and it destroys the socket instead of leaving
  * it to time out.
  */
+import dgram from 'node:dgram';
+import dns from 'node:dns';
 import net from 'node:net';
 import os from 'node:os';
 /**
@@ -28,6 +30,205 @@ export function localIPv4Addresses(interfaces = os.networkInterfaces) {
     addresses.push('127.0.0.1');
     return addresses;
 }
+/** The address an interface process on this machine calls back on. */
+const LOOPBACK = '127.0.0.1';
+/**
+ * B-53: every non-internal IPv4 address of this machine with its netmask, in the order
+ * `os.networkInterfaces()` gives them - the loopback is not in it.
+ */
+export function localIPv4Interfaces(interfaces = os.networkInterfaces) {
+    const found = [];
+    for (const entries of Object.values(interfaces())) {
+        for (const entry of entries ?? []) {
+            if (entry.family === 'IPv4' && !entry.internal && !found.some((seen) => seen.address === entry.address)) {
+                found.push({ address: entry.address, netmask: entry.netmask });
+            }
+        }
+    }
+    return found;
+}
+/** A dotted IPv4 address as a number; `undefined` for anything else. */
+export function ipv4ToNumber(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4) {
+        return undefined;
+    }
+    let value = 0;
+    for (const part of parts) {
+        if (!/^\d{1,3}$/.test(part)) {
+            return undefined;
+        }
+        const byte = Number(part);
+        if (byte > 255) {
+            return undefined;
+        }
+        value = value * 256 + byte;
+    }
+    return value;
+}
+/** True when `target` is in the network of `address/netmask`. False when any of them is no IPv4 address. */
+export function inSubnet(address, netmask, target) {
+    const a = ipv4ToNumber(address);
+    const m = ipv4ToNumber(netmask);
+    const t = ipv4ToNumber(target);
+    if (a === undefined || m === undefined || t === undefined) {
+        return false;
+    }
+    // `>>> 0` keeps the results unsigned; `&` alone would make 192.168.x.x negative
+    return (a & m) >>> 0 === (t & m) >>> 0;
+}
+/** `169.254.0.0/16`, the address an interface gives itself when no DHCP server answered. */
+export function isLinkLocal(address) {
+    return address.startsWith('169.254.');
+}
+/** `127.0.0.0/8`. */
+export function isLoopback(address) {
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(address);
+}
+/** How long a name lookup for the callback address may take before the first address is used. */
+export const RESOLVE_TIMEOUT_MS = 3000;
+/** The CCU host's IPv4 address, through the system resolver (`/etc/hosts`, mDNS where the OS has it). */
+export async function resolveIPv4(host, lookup = dns.promises.lookup) {
+    if (ipv4ToNumber(host) !== undefined) {
+        return host;
+    }
+    if (host === '' || net.isIPv6(host)) {
+        return undefined;
+    }
+    try {
+        const result = await withTimeout(lookup(host, { family: 4 }), RESOLVE_TIMEOUT_MS, () => new Error('timeout'));
+        return result.address;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The local address a UDP socket gets when it is `connect()`ed to `address`: the source address of
+ * the route the operating system would take. `connect` on a datagram socket only sets the default
+ * peer - no packet is sent - so this works for a CCU behind a router or a VPN as well as for one in
+ * the same network.
+ */
+export function routeSource(address, createSocket = dgram.createSocket) {
+    return new Promise((resolve) => {
+        let socket;
+        try {
+            socket = createSocket('udp4');
+        }
+        catch {
+            resolve(undefined);
+            return;
+        }
+        let settled = false;
+        const done = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            try {
+                socket.close();
+            }
+            catch {
+                // already closed
+            }
+            resolve(result);
+        };
+        socket.on('error', () => {
+            done(undefined);
+        });
+        try {
+            // the port does not matter, nothing is sent; 9 is "discard"
+            socket.connect(9, address, () => {
+                try {
+                    done(socket.address().address);
+                }
+                catch {
+                    done(undefined);
+                }
+            });
+        }
+        catch {
+            done(undefined);
+        }
+    });
+}
+/** The machine's own network, as the running host sees it. */
+export function systemNetwork() {
+    return {
+        interfaces: () => localIPv4Interfaces(),
+        resolve: (host) => resolveIPv4(host),
+        route: (address) => routeSource(address),
+    };
+}
+/**
+ * A network made of a fixed address list, for a caller that injects `localAddresses` (the tests and
+ * the e2e hosts): no netmasks, no name lookup beyond an address literal, no route.
+ */
+export function staticNetwork(addresses) {
+    return {
+        interfaces: () => addresses()
+            .filter((address) => !isLoopback(address))
+            .map((address) => ({ address })),
+        resolve: (host) => Promise.resolve(ipv4ToNumber(host) === undefined ? undefined : host),
+        route: () => Promise.resolve(undefined),
+    };
+}
+/**
+ * B-53 (#162, #165): the automatic callback address, and every address with whether it is in the
+ * CCU's network. Synchronous: `hostAddress` and `routed` are what {@link describeCallbackAddresses}
+ * found out, and `undefined` when nothing could be.
+ *
+ * The order: the CCU on the loopback (or `local`) is called back on the loopback; then the
+ * address in the CCU's network; then the route's source address; then the first address that is
+ * not link-local. A link-local address wins only as the CCU's own network, and the loopback is
+ * never chosen for a CCU elsewhere unless this machine has no other address at all.
+ */
+export function pickCallbackAddress(host, hostAddress, interfaces, routed, local = false) {
+    const matches = (entry) => hostAddress !== undefined && entry.netmask !== undefined && inSubnet(entry.address, entry.netmask, hostAddress);
+    const ccuOnLoopback = local || (hostAddress !== undefined && isLoopback(hostAddress));
+    const addresses = interfaces.map((entry) => ({
+        address: entry.address,
+        inSubnet: matches(entry),
+        ...(isLinkLocal(entry.address) ? { linkLocal: true } : {}),
+    }));
+    addresses.push({ address: LOOPBACK, inSubnet: ccuOnLoopback });
+    const choose = () => {
+        if (ccuOnLoopback) {
+            return { address: LOOPBACK, reason: 'loopback' };
+        }
+        const subnet = interfaces.find((entry) => matches(entry));
+        if (subnet !== undefined) {
+            return { address: subnet.address, reason: 'subnet' };
+        }
+        if (routed !== undefined && !isLinkLocal(routed) && interfaces.some((entry) => entry.address === routed)) {
+            return { address: routed, reason: 'route' };
+        }
+        const first = interfaces.find((entry) => !isLinkLocal(entry.address));
+        return { address: first?.address ?? LOOPBACK, reason: 'first' };
+    };
+    return {
+        host,
+        ...(hostAddress === undefined ? {} : { hostAddress }),
+        auto: choose(),
+        addresses,
+    };
+}
+/**
+ * B-53: {@link pickCallbackAddress} with the facts looked up - the CCU's name resolved, and the route
+ * asked for only when no address shares the CCU's network. Never rejects.
+ */
+export async function describeCallbackAddresses(host, network, local = false) {
+    const interfaces = network.interfaces();
+    if (local) {
+        return pickCallbackAddress(host, undefined, interfaces, undefined, true);
+    }
+    const hostAddress = host === '' ? undefined : await network.resolve(host);
+    const inNetwork = hostAddress !== undefined &&
+        (isLoopback(hostAddress) ||
+            interfaces.some((entry) => entry.netmask !== undefined && inSubnet(entry.address, entry.netmask, hostAddress)));
+    const routed = hostAddress === undefined || inNetwork ? undefined : await network.route(hostAddress);
+    return pickCallbackAddress(host, hostAddress, interfaces, routed);
+}
 /** Whether a TCP connection to `host:port` is accepted, refused, or not answered in time. Never throws. */
 export function probePortState(host, port, options = {}) {
     const timeoutMs = options.timeoutMs ?? 2000;

package/node_modules/@homematic-manager/backend/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homematic-manager/backend",
-  "version": "3.0.0-beta.18",
+  "version": "3.0.0-beta.19",
   "type": "module",
   "description": "Homematic Manager backend: XML-RPC/BIN-RPC clients and callback servers, caches, optional ReGa",
   "license": "AGPL-3.0-or-later",