homematic-manager 3.0.0-beta.17 → 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/dist/occulite.d.ts

@@ -8,8 +8,9 @@
  *
  * On openccu-lite nobody logs in *here*. The box's shell has already done it, lighttpd's gate has
  * already refused everyone who has no session (their D-28), and the shell opens an addon page with
- * the session on the URL: `?sid=@xxxxxxxxxx@`, the CCU convention. That session id **is** a valid
- * credential for the box's own APIs, so the check is one request:
+ * the session on the URL: `?sid=@xxxxxxxxxx@`, the CCU convention. On an image from before their
+ * task 125 that session id **is** a valid credential for the box's own APIs, so the check is one
+ * request (on a newer image the shell sends the gate's `X-Occulite-Session` instead, see below):
  *
  * ```
  * GET /api/meta/v1/enums   Authorization: Bearer <sid>   ->  200 valid, 401 not
@@ -58,8 +59,18 @@ export interface OcculiteCheckOptions {
      */
     readonly requireState?: boolean;
 }
-/** A session id as the shell hands it over, `@…@` and all, or `undefined` when it is not one. */
+/** A session id as the shell or the gate hands it over, `@…@` and all, or `undefined` when it is not one. */
 export declare function parseSid(value: string | null | undefined): string | undefined;
+/**
+ * B-36: can the `?sid=` of a request be a session of the box whose gate named `gate`?
+ *
+ * A gate header of the 26-character shape says the box issues session ids of that shape (task 125),
+ * so a `?sid=` of any other shape there is the session's legacy alias, which the box's API refuses:
+ * the answer is known without asking. Without such a header - a CCU, an image from before the header,
+ * a ten-character header - nothing can be concluded, and the box decides as before. This only ever
+ * *refuses*: a `true` still has to be confirmed by the box.
+ */
+export declare function sidCanBeSession(sid: string, gate: string | undefined): boolean;
 /** Checks a session id against the box that issued it. */
 export declare class OcculiteAuthenticator {
     #private;

package/dist/occulite.js

@@ -8,8 +8,9 @@
  *
  * On openccu-lite nobody logs in *here*. The box's shell has already done it, lighttpd's gate has
  * already refused everyone who has no session (their D-28), and the shell opens an addon page with
- * the session on the URL: `?sid=@xxxxxxxxxx@`, the CCU convention. That session id **is** a valid
- * credential for the box's own APIs, so the check is one request:
+ * the session on the URL: `?sid=@xxxxxxxxxx@`, the CCU convention. On an image from before their
+ * task 125 that session id **is** a valid credential for the box's own APIs, so the check is one
+ * request (on a newer image the shell sends the gate's `X-Occulite-Session` instead, see below):
  *
  * ```
  * GET /api/meta/v1/enums   Authorization: Bearer <sid>   ->  200 valid, 401 not
@@ -32,10 +33,40 @@ export const OCCULITE_TIMEOUT_MS = 5000;
  * box - so the header is only a claim, and the box is asked about it like about any other session.
  */
 export const OCCULITE_SESSION_HEADER = 'x-occulite-session';
-/** A session id as the shell hands it over, `@…@` and all, or `undefined` when it is not one. */
+/**
+ * B-36: what an openccu-lite session id looks like, and nothing else is one.
+ *
+ * - **Since openccu-lite task 125** (occulited `1f71597`, their D-77) a session id is what Go's
+ *   `crypto/rand.Text` hands out: 26 characters of base32, `A-Z` and `2-7`. The box's API and its gate
+ *   match exactly this (`sidRe`, the gate's `SID_PATTERN`).
+ * - **Before task 125** it was the CCU's shape, ten of `[0-9a-zA-Z]` (auth-off's fixed id too). Since
+ *   then that shape is only a session's *legacy alias*, which the addon CGIs parse and the box's API
+ *   refuses as a credential from anywhere. The two cannot be told apart by their characters: a
+ *   ten-character value is a session on an older box and never one on a newer box.
+ * - **An API token** (`olt_` and 32 hex digits) is neither and is never a session: the header path
+ *   asks `/api/auth/v1/state`, which also answers for a token.
+ *
+ * A value of another shape or length cannot be an openccu-lite session on any image, so it is refused
+ * here, without asking the box.
+ */
+const SESSION_ID = /^[A-Z2-7]{26}$/;
+const LEGACY_ID = /^[0-9a-zA-Z]{10}$/;
+/** A session id as the shell or the gate hands it over, `@…@` and all, or `undefined` when it is not one. */
 export function parseSid(value) {
     const bare = (value ?? '').replace(/^@|@$/g, '').trim();
-    return /^[0-9a-zA-Z]{6,64}$/.test(bare) ? bare : undefined;
+    return SESSION_ID.test(bare) || LEGACY_ID.test(bare) ? bare : undefined;
+}
+/**
+ * B-36: can the `?sid=` of a request be a session of the box whose gate named `gate`?
+ *
+ * A gate header of the 26-character shape says the box issues session ids of that shape (task 125),
+ * so a `?sid=` of any other shape there is the session's legacy alias, which the box's API refuses:
+ * the answer is known without asking. Without such a header - a CCU, an image from before the header,
+ * a ten-character header - nothing can be concluded, and the box decides as before. This only ever
+ * *refuses*: a `true` still has to be confirmed by the box.
+ */
+export function sidCanBeSession(sid, gate) {
+    return gate === undefined || !SESSION_ID.test(gate) || SESSION_ID.test(sid);
 }
 /** Checks a session id against the box that issued it. */
 export class OcculiteAuthenticator {

package/dist/server.js

@@ -29,7 +29,7 @@ import { applyCookieToken, applySessionToken, clearedSessionCookie, createToken,
 import { DeviceImageService, readIconMapFile } from './images.js';
 import { clientAddress, parseLoginForm, pickLanguage, readBody, renderLoginPage, } from './login.js';
 import { createLogger, silentLogger } from './log.js';
-import { OCCULITE_SESSION_HEADER, OcculiteAuthenticator, parseSid } from './occulite.js';
+import { OCCULITE_SESSION_HEADER, OcculiteAuthenticator, parseSid, sidCanBeSession, } from './occulite.js';
 import { defaultDataDir, defaultMetadataDir, defaultUiDir, packageVersion } from './paths.js';
 import { proxyRequest, proxyUpgrade } from './proxy.js';
 import { RateLimiter, SessionStore } from './sessions.js';
@@ -184,8 +184,27 @@ export async function createWebHost(options = {}) {
         // session is checked against the box, turned into one of ours, and taken off the URL again
         // so that it does not sit in the address bar, in a bookmark and in every referrer.
         if (boxSessions && sessions && (method === 'GET' || method === 'HEAD')) {
-            const offered = url.searchParams.get('sid');
-            if (parseSid(offered) !== undefined) {
+            const offered = parseSid(url.searchParams.get('sid'));
+            if (offered !== undefined) {
+                // B-36: the gate header first. Since openccu-lite task 125 the `?sid=` a shell puts on
+                // the URL is the session's legacy alias, which the box's API refuses, while the same
+                // request carries the session the gate validated: a confirmed header signs the request
+                // in, whatever `?sid=` says, and the `?sid=` only comes off the URL.
+                const gate = gateSid(request);
+                if (gate !== undefined) {
+                    const session = await sessionFromGate(request, sessions.get(readCookie(request.headers.cookie, SESSION_COOKIE)));
+                    if (session?.credential === gate) {
+                        redirectWithoutSid(request, response, session, url, rest);
+                        return;
+                    }
+                }
+                if (!sidCanBeSession(offered, gate)) {
+                    // what the box would answer, without asking it: see sidCanBeSession
+                    log.warn(`login: the session offered from ${clientAddress(request)} cannot be one of this openccu-lite's (not asked)`);
+                    response.writeHead(302, { Location: '/', 'Cache-Control': 'no-store' });
+                    response.end();
+                    return;
+                }
                 await handleHandover(request, response, offered, url, rest);
                 return;
             }
@@ -356,17 +375,19 @@ export async function createWebHost(options = {}) {
             response.end();
             return;
         }
-        const store = sessions;
-        const session = store.create(checked.name, checked.level, checked.sid);
+        const session = sessions.create(checked.name, checked.level, checked.sid);
         backend?.noteMetaSession(checked.sid);
         log.info(`login: ${checked.name} (level ${String(checked.level)}) through the openccu-lite shell`);
-        // the same page, without the session in the URL
+        redirectWithoutSid(request, response, session, url, rest);
+    }
+    /** The same page without the session in the URL, with the cookie of the session it was let in by. */
+    function redirectWithoutSid(request, response, session, url, rest) {
         const query = new URLSearchParams(url.searchParams);
         query.delete('sid');
         const search = query.size === 0 ? '' : `?${query.toString()}`;
         response.writeHead(302, {
             Location: `${base}${rest}${search}`,
-            'Set-Cookie': sessionCookie(session.id, base, store.ttlMs / 1000, isHttps(request)),
+            'Set-Cookie': sessionCookie(session.id, base, sessions.ttlMs / 1000, isHttps(request)),
             'Cache-Control': 'no-store',
         });
         response.end();
@@ -403,9 +424,9 @@ export async function createWebHost(options = {}) {
     /**
      * B-94, D-65: the session of a request that came through openccu-lite's gate.
      *
-     * The `?sid=` hand-over and the cookie stay as they are; this only adds a third way in, for a
-     * request that has neither - a bookmark, a reload after our session expired - or whose cookie
-     * belongs to another box session than the one the gate found. The header is a claim until the box
+     * The cookie stays as it is; this adds a third way in, for a request that has none - a bookmark,
+     * a reload after our session expired - or whose cookie belongs to another box session than the
+     * one the gate found. A request with `?sid=` asks this first too (B-36). The header is a claim until the box
      * confirms it (`GET /api/auth/v1/state`): a CCU and an older openccu-lite image pass a client's
      * header through, and the backend's port is open to every process on the box.
      */

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,8 +28,9 @@ 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 { WriteLog } from '../write/log.js';
-import { isWriteMethod } from '../write/log.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';
 import { ConfigRepair } from '../write/repair.js';
 import { WriteQueue } from '../write/queue.js';
@@ -56,7 +57,7 @@ export class Backend {
     #options;
     #config;
     #queue;
-    #writeLog;
+    #rpcLog;
     #unknownMethodsSeen = new Set();
     #writer;
     #repair;
@@ -125,14 +126,14 @@ export class Backend {
         this.#queue = new WriteQueue({
             paceFor: (interfaceName) => writePaceFor(interfaceName, this.#config.connection.writePaceMs),
         });
-        this.#writeLog = new WriteLog({
+        this.#rpcLog = new RpcLog({
             file: config.cacheFile('write-log.json'),
             rpcLogFolder: config.connection.rpcLogFolder,
             onAppended: (entry) => {
-                this.events.emit('writeLog.appended', entry);
+                this.events.emit('rpcLog.appended', entry);
             },
             onError: (error) => {
-                this.#notice('warn', `write log: ${errorMessage(error)}`);
+                this.#notice('warn', `RPC log: ${errorMessage(error)}`);
             },
             ...(options.cacheWriteDelayMs === undefined ? {} : { writeDelayMs: options.cacheWriteDelayMs }),
         });
@@ -166,7 +167,7 @@ export class Backend {
         });
         await caches.load();
         const backend = new Backend(options, config, caches);
-        await backend.#writeLog.load();
+        await backend.#rpcLog.load();
         await backend.#linkTemplates.load();
         return backend;
     }
@@ -213,7 +214,7 @@ export class Backend {
         await this.#meta?.stop();
         this.#meta = undefined;
         await this.#caches.flush();
-        await this.#writeLog.flush();
+        await this.#rpcLog.flush();
         this.events.clear();
     }
     /**
@@ -236,7 +237,7 @@ export class Backend {
         }
         if (this.#sessions > 0) {
             if (previous === 0) {
-                void this.#resubscribe();
+                void runWithOrigin('background', () => this.#resubscribe());
             }
             return;
         }
@@ -246,7 +247,7 @@ export class Backend {
         }
         const timer = setTimeout(() => {
             this.#idleTimer = undefined;
-            void this.#unsubscribeIdle();
+            void runWithOrigin('background', () => this.#unsubscribeIdle());
         }, grace);
         if (typeof timer.unref === 'function') {
             timer.unref();
@@ -279,7 +280,9 @@ export class Backend {
      */
     async request(method, ...params) {
         try {
-            return await this.#dispatch(method, params);
+            // Task 48: everything a request awaits is a UI action for the RPC log; the console's
+            // own call is the console's. Whatever runs outside a request is background work.
+            return await runWithOrigin(method === 'rpc.call' ? 'console' : 'ui', () => this.#dispatch(method, params));
         }
         catch (error) {
             throw error instanceof BackendError ? error : internalError(errorMessage(error), error);
@@ -305,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':
@@ -468,10 +473,10 @@ export class Backend {
                 return this.#methods(p[0]);
             case 'write.cancel':
                 return this.#queue.cancel(p[0]);
-            case 'writeLog.list':
-                return this.#writeLog.list(p[0]);
-            case 'writeLog.clear':
-                this.#writeLog.clear();
+            case 'rpcLog.list':
+                return this.#rpcLog.list(p[0]);
+            case 'rpcLog.clear':
+                this.#rpcLog.clear();
                 return null;
             case 'data.file':
                 return this.#files.read(p[0]);
@@ -493,7 +498,15 @@ export class Backend {
         }
         return this.#manager;
     }
-    async #connect() {
+    /**
+     * Task 48: the connection is background work even when a `config.set` from the settings dialog
+     * asks for it - the watchdog, the callback servers and the polling timers it creates would
+     * otherwise inherit that request's origin for the rest of the session.
+     */
+    #connect() {
+        return runWithOrigin('background', () => this.#connectNow());
+    }
+    async #connectNow() {
         const connection = this.#config.connection;
         this.#noServiceMessages.clear();
         this.#serviceMessageFailures.clear();
@@ -508,10 +521,11 @@ export class Backend {
             onNotice: (level, message, interfaceName) => {
                 this.#notice(level, message, interfaceName);
             },
-            onConnected: (interfaceName) => this.#onInterfaceConnected(interfaceName),
+            onConnected: (interfaceName) => runWithOrigin('background', () => this.#onInterfaceConnected(interfaceName)),
             onCall: (record) => {
                 this.#onCall(record);
             },
+            originOf: currentOrigin,
             ...(this.#options.callbackHost === undefined ? {} : { callbackHost: this.#options.callbackHost }),
             ...(this.#options.defaultCallbackPorts === undefined
                 ? {}
@@ -522,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,
         });
@@ -833,7 +849,7 @@ export class Backend {
      * RPC
      */
     #onCall(record) {
-        this.#writeLog.append(record);
+        this.#rpcLog.append(record);
     }
     /** A read: straight to the interface, never queued. */
     async #read(interfaceName, method, params) {
@@ -842,7 +858,10 @@ export class Backend {
     /** A write: through the paced queue of that interface. */
     async #write(interfaceName, method, params) {
         const client = this.#requireManager().client(interfaceName);
-        return this.#queue.enqueue(interfaceName, () => client.call(method, params));
+        // Task 48: the queue runs a task from the timer that drained it, which is the *previous*
+        // task's context; the origin is the one of whoever enqueued, so it is taken here.
+        const origin = currentOrigin();
+        return this.#queue.enqueue(interfaceName, () => client.call(method, params, { origin }));
     }
     /*
      * configuration
@@ -877,7 +896,7 @@ export class Backend {
             : [];
         await this.#disconnect();
         const config = this.#withHostFacts(await this.#config.setConnection(connection));
-        this.#writeLog.setRpcLogFolder(config.connection.rpcLogFolder);
+        this.#rpcLog.setRpcLogFolder(config.connection.rpcLogFolder);
         if (config.connection.host !== previousHost) {
             await this.#caches.flush();
             this.#caches = new CacheStore({
@@ -942,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 });
@@ -1282,7 +1322,7 @@ export class Backend {
             return;
         }
         const timer = setInterval(() => {
-            void this.pollServiceMessages();
+            void runWithOrigin('background', () => this.pollServiceMessages());
         }, interval);
         if (typeof timer.unref === 'function') {
             timer.unref();
@@ -1310,7 +1350,7 @@ export class Backend {
         }
         const timer = setTimeout(() => {
             this.#hmipSweepTimer = undefined;
-            void this.sweepHmip();
+            void runWithOrigin('background', () => this.sweepHmip());
         }, this.#options.hmipSweepDelayMs ?? HMIP_SWEEP_DELAY_MS);
         if (typeof timer.unref === 'function') {
             timer.unref();
@@ -1565,6 +1605,7 @@ export const API_METHOD_NAMES = [
     'config.set',
     'config.discover',
     'config.clearCaches',
+    'config.callbackAddresses',
     'interfaces.list',
     'interfaces.reconnect',
     'rega.state',
@@ -1630,8 +1671,8 @@ export const API_METHOD_NAMES = [
     'rpc.call',
     'rpc.methods',
     'write.cancel',
-    'writeLog.list',
-    'writeLog.clear',
+    'rpcLog.list',
+    'rpcLog.clear',
     'data.file',
     'session.info',
 ];

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

@@ -21,6 +21,8 @@ export * from './config/legacyImport.js';
 export * from './config/store.js';
 export * from './config/linkTemplates.js';
 export * from './rpc/client.js';
+export * from './rpc/log.js';
+export * from './rpc/origin.js';
 export * from './rpc/server.js';
 export * from './interfaces/manager.js';
 export * from './cache/devices.js';
@@ -30,7 +32,6 @@ export * from './cache/unreach.js';
 export * from './cache/store.js';
 export * from './meta/index.js';
 export * from './write/queue.js';
-export * from './write/log.js';
 export * from './write/paramset.js';
 export * from './rega/auth.js';
 export * from './rega/client.js';

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

@@ -24,6 +24,8 @@ export * from './config/store.js';
 export * from './config/linkTemplates.js';
 // the protocol layer
 export * from './rpc/client.js';
+export * from './rpc/log.js';
+export * from './rpc/origin.js';
 export * from './rpc/server.js';
 export * from './interfaces/manager.js';
 // state
@@ -36,7 +38,6 @@ export * from './cache/store.js';
 export * from './meta/index.js';
 // the write path (task 6)
 export * from './write/queue.js';
-export * from './write/log.js';
 export * from './write/paramset.js';
 // the optional and the peripheral
 export * from './rega/auth.js';

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). */
@@ -65,6 +65,8 @@ export interface InterfaceManagerOptions {
     /** Called after a successful `init`; the backend fills its caches there. */
     readonly onConnected?: (interfaceName: string) => void | Promise<void>;
     readonly onCall?: (record: RpcCallRecord) => void;
+    /** Task 48: the origin of a call that names none, handed to every client (the backend's request context). */
+    readonly originOf?: RpcClientOptions['originOf'];
     readonly now?: () => number;
     readonly rpcTimeoutMs?: number;
     readonly watchdogIntervalMs?: number;
@@ -93,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
@@ -132,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. */